Crossfilter API翻譯

Crossfilter API Reference

---

crossfilter 表示多維數組集

# crossfilter([records])

構建新的多維數組集。記錄records被指定，添加指定的記錄records。
記錄records可以是任意的數組，JavaScript對象或者基礎數據。如例：

var payments = crossfilter([
  {date: "2011-11-14T16:17:54Z", quantity: 2, total: 190, tip: 100, type: "tab"},
  {date: "2011-11-14T16:20:19Z", quantity: 2, total: 190, tip: 100, type: "tab"},
  {date: "2011-11-14T16:28:54Z", quantity: 1, total: 300, tip: 200, type: "visa"},
  {date: "2011-11-14T16:30:43Z", quantity: 2, total: 90, tip: 0, type: "tab"},
  {date: "2011-11-14T16:48:46Z", quantity: 2, total: 90, tip: 0, type: "tab"},
  {date: "2011-11-14T16:53:41Z", quantity: 2, total: 90, tip: 0, type: "tab"},
  {date: "2011-11-14T16:54:06Z", quantity: 1, total: 100, tip: 0, type: "cash"},
  {date: "2011-11-14T16:58:03Z", quantity: 2, total: 90, tip: 0, type: "tab"},
  {date: "2011-11-14T17:07:21Z", quantity: 2, total: 90, tip: 0, type: "tab"},
  {date: "2011-11-14T17:22:59Z", quantity: 2, total: 90, tip: 0, type: "tab"},
  {date: "2011-11-14T17:25:45Z", quantity: 2, total: 200, tip: 0, type: "cash"},
  {date: "2011-11-14T17:29:52Z", quantity: 1, total: 200, tip: 100, type: "visa"}
]);

# crossfilter.add(records)

添加指定的記錄records到多維數組集crossfilter。

# crossfilter.remove()

從多維數組集中刪除所有當前過濾器匹配的記錄records。

# crossfilter.size()

返回記錄records的數量在多維數組集，獨立的任何過濾器中。例如，已經添加單一批次的
記錄到多維數據集中，這個方法將返回records.length。

# crossfilter.groupAll()

一個便捷的功能對所有的記錄進行分組和減少爲單一值。
注意：這個groupAll觀察所有的過濾器，和dimension的groupAll不一樣。

Dimension

---

# crossfilter.dimension(value)

使用指定的值訪問器函數構造一個新的dimension。這個函數必須返回自然有序的值，即：
正確的行爲關於javascript的<, <=和>,>=運算符。
這通常意味着基礎數據：booleans，數字或者字符串； 然而： 可以重寫object.valueOf來保證這個值和給定的對象值相似，如日期。

特別是，注意null和undefined是不支持的。此外，混合類型應該採用，例如：字符串和數字。
如果字符串和數字混合，那麼字符串將會強制轉換成數字，因此字符串必須可以強制轉換成數字，否則就會導致NaN。
例：

var paymentsByTotal = payments.dimension(function(d) { return d.total; });

給定的dimension訪問器函數返回的值必須是確定的，並且對於crossfilter的存在永遠不變。
性能說明：在內部，緩存給定的dimension的值。因此，如果 dimension值是從其他屬性派生的，
沒有必要在crossfilter以外派生值。只有當records添加到crossfilter中時才調用值函數。

dimension一旦創建就會綁定到crossfilter。創建超過8個dimension和超過16個dimension
會帶來額外的開銷。目前不支持一次超過32個dimension。但是可以用dimension.dispose
佈置dimension來給新的dimension騰出空間。dimension的狀態，記錄關聯的特定dimension的過濾器，如果真有的話。初期，如果dimension沒有指定過濾器：所有的records都會被選中。由於創建dimension比較佔用資源，因此應該謹慎保留對創建的任何dimension的引用。

# dimension.filter(value)

過濾records，使dimension值和value匹配，然後返回這個dimension。

這個被指定的value如果是null，這種情況下此方法相當於filterAll；
這個value如果是數組，這種情況下此方法相當於filterRange；
這個value如果是函數，這種情況下此方法相當於filterFunction；
除此之外，此方法相當於filterExact。

例：

paymentsByTotal.filter([100, 200]); // 選取總額在100到200之間的付款
paymentsByTotal.filter(120); // 選取總額等於120的付款
paymentsByTotal.filter(function(d) { return d % 2; }); // 選取總額是奇數的付款
paymentsByTotal.filter(null); // 選取所有的付款

如果調用過濾器將會替換現有的過濾器,如果dimension有的話

# dimension.filterExact(value)

過濾records，使dimension值和value匹配，然後返回這個dimension。
例：

paymentsByTotal.filterExact(120); // 選取總額等於120的付款

注意使用排序運算符<, <=和>,>=進行精確比較。例如，如果傳遞的值是null， 這相當於0；
過濾不要用==和===運算符。

如果調用過濾器將會替換現有的過濾器,如果dimension有的話

# dimension.filterRange(range)

過濾records，使dimension值大於等於range[0]，小於range[1]，返回這個dimension。
例：

paymentsByTotal.filterRange([100, 200]); // 選取總額在100到200之間的付款

# dimension.filterFunction(function)

過濾records，被調用時使用指定的函數返回dimension值的真值，並返回dimension。
例：

paymentsByTotal.filterFunction(function(d) { return d % 2; }); // // 選取總額是奇數的付款

這可以用於實現聯合過濾器，例如：

// 選取總額在0到10或者20到30之間的付款
paymentsByTotal.filterFunction(function(d) { return 0 <= d && d < 10 || 20 <= d && d < 30; });

# dimension.filterAll()

清除任何dimension的過濾器，選取所有的records並返回dimension。
例：

paymentsByTotal.filterAll(); // 選取所有的付款

# dimension.top(k)

返回一個包含前k個records的數組，根據此dimension的自然順序。被返回的數組是按照降序的自然順序進行排列。這個方法和crossfilter當前的過濾器相交，只返回滿足所有能動的過濾器（包括此維度的過濾器）的records。
例：

var topPayments = paymentsByTotal.top(4); // the top four payments, by total
topPayments[0]; // the biggest payment
topPayments[1]; // the second-biggest payment
// etc.

如果根據crossfilter所有的過濾器選擇的records比k少，那就返回一個少於k的數組。
例：

var allPayments = paymentsByTotal.top(Infinity); //返回所有的

# dimension.bottom(k)

返回一個包含後k個records的數組，根據此dimension的自然順序。被返回的數組是按照升序的自然順序進行排列。這個方法和crossfilter當前的過濾器相交，只返回滿足所有能動的過濾器（包括此維度的過濾器）的records。
例：

var bottomPayments = paymentsByTotal.bottom(4); // the bottom four payments, by total
bottomPayments[0]; // the smallest payment
bottomPayments[1]; // the second-smallest payment
// etc.

# dimension.dispose()

刪除這個dimension（包括它的groups）從crossfilter。這爲添加到這個crossfilter其他的dimension釋放了空間。

Group (Map-Reduce)

---

# dimension.group([groupValue])

爲給定的dimension構造一個新的羣組，根據指定的groupValue函數，採取dimension的值作爲輸入值，並返回相應的四捨五入值。這個groupValue是可選的；如果不指定，則默認爲恆等函數。類似的值函數，groupValue必須返回自然有序的值；此外，這種順序必須符合這個dimension的值函數。
例：

var paymentGroupsByTotal = paymentsByTotal.group(function(total) { return Math.floor(total / 100); });

默認情況下，這個group的reduce函數將計算每個組的記錄數。此外，這個groups將按照記錄數排序。

注意：這個分組和crossfire當前的過濾器相交，除了相關聯的dimension的過濾器。因此，group方法僅考慮滿足除dimension的過濾器之外的每個過濾器的記錄。所以，如果付款的ceossfilter是按照type和total過濾，則總額的group只按照type觀察過濾器。

# group.size()

返回group中不同值的數量，無關任何過濾器；基礎數據。

# group.reduce(add, remove, initial)

指定分組的reduce函數，並返回這個group。默認的行爲，通過count進行縮減。
例：

//p是上一數據，v是當前數據
function reduceAdd(p, v) {
  return p + 1;
}

function reduceRemove(p, v) {
  return p - 1;
}

function reduceInitial() {
  return 0;
}

爲了縮減total的總數(計算total的總和)，你可以修改add函數和remove函數，如下實施：

function reduceAdd(p, v) {
  return p + v.total;
}

function reduceRemove(p, v) {
  return p - v.total;
}

除了add函數以外，remove函數也是需要的，因爲group的縮減是逐漸地隨着記錄被過濾而更新的；在一些情況下，需要從先前計算的group reduction中刪除記錄。使用許多不同的屬性，你可以使用javascript閉包創建add和remove函數。

# group.reduceCount()

一個便捷的方法爲了統計記錄數量的reduce函數，返回這個group。

# group.reduceSum(value)

一個便捷的方法使用指定的value訪問器計算記錄總和的reduce函數，返回這個group。
例：

//按照付款類型，計算付款總額，相同類型的付款值累加
var paymentsByType = payments.dimension(function(d) { return d.type; }),
    paymentVolumeByType = paymentsByType.group().reduceSum(function(d) { return d.total; }),
    topTypes = paymentVolumeByType.top(1);
topTypes[0].key; // the top payment type (e.g., "tab")
topTypes[0].value; // the payment volume for that type (e.g., 920)

# group.order(orderValue)

指定orderValue計算前K個組。默認的order函數是恆等函數，假定reduction值是自然順序（如簡單的計數和款項）。
例：

function reduceAdd(p, v) {
  ++p.count;
  p.total += v.total;
  return p;
}

function reduceRemove(p, v) {
  --p.count;
  p.total -= v.total;
  return p;
}

function reduceInitial() {
  return {count: 0, total: 0};
}

function orderValue(p) {
  return p.total;
}

var topTotals = paymentVolumeByType.reduce(reduceAdd, reduceRemove, reduceInitial).order(orderValue).top(2);
topTotals[0].key;   // payment type with highest total (e.g., "tab")
topTotals[0].value; // reduced value for that type (e.g., {count:8, total:920})

這種技術同樣可以計算每個組中特殊值的個數，把計數每一個組縮減的值存儲爲map，當計數到達零時刪除這個map。

# group.orderNatural()

使用自然順序縮減值的便捷方法。返回這個分組。

# group.top(k)

返回一個包含前k個組的新數組，根據被關聯縮減值的組順序。被返回的數組是按照縮減（統計會不會更容易理解？）值的降序排列。
例：

//檢索付款類型數量最多的一個
var paymentsByType = payments.dimension(function(d) { return d.type; }),
    paymentCountByType = paymentsByType.group(),
    topTypes = paymentCountByType.top(1);
topTypes[0].key; // the top payment type (e.g., "tab")
topTypes[0].value; // the count of payments of that type (e.g., 8)

通過crossfilter的過濾器如果group少於k個，就返回一個少於k的數組。如果有一個少於k的非空組，這個方法也有可能返回空的組（零個被選定的記錄）。

# group.all()

返回包含所有的組的數組，按照key的升序排列。就像top，被返回的對象包含key和value兩個屬性。被返回的數組也有可能包含空的組：group縮減初始化函數返回的值。
例：

//通過類型計數付款
var types = paymentCountByType.all();

這個方法比’top(Infinity)’更快，因爲整個數組原樣被返回，而不是選擇新數組和排序。不要修改被返回的數組！

# group.dispose()

從dimension中刪除group。當新的過濾器應用於crossfilter時這個組將不再更新，如果他沒有其他引用，則可能被垃圾回收。

Group All（Reduce）

# dimension.groupAll()

將所有的記錄分組到一個簡單的組中的便捷函數。被返回的對象相當於一個標準的grouping，除了沒有top和order方法。相反，使用value檢索符合所有records的縮減值。

# groupAll.reduce(add, remove, initial)

相當於reduce。

# groupAll.value()

相當於all()[0].value。

Extras

crossfilter有幾個額外的東西，你應該會感覺很有用。

# crossfilter.bisect

恆等平分；適用於數字，字符串，日期和自然可比的對象。

# crossfilter.bisect.by(value)

使用指定的value訪問器構建一個新的平分器，這個訪問器必須能返回一個自然有序的值。

---

參考：
crossfilter API 原文
中文 API 原文