als-statistics/docs/03-quick-start.md

A powerful and lightweight JavaScript library for descriptive statistics, regression, clustering, outlier detection, and noise analysis using a flexible table/column architecture.

## 🚀 Quick Start: Plug and Play

**als-statistics** allows you to explore data either directly (with standalone columns/tables) or by organizing it inside a `Statistics` instance for multi-table workflows.

### 📦 Standalone Columns

Create numeric or categorical columns on the fly:

```js
const {newColumn} = require("als-statistics");

// Ratio (numeric) column
const numbers = newColumn([1, 2, 3, 4, 5]);
console.log(numbers.mean);    // 3
console.log(numbers.median); // 3

// Categorical (string) column
const categories = newColumn(["A", "B", "A", "C"]);
console.log(categories.frequencies); // { A: 2, B: 1, C: 1 }
```

> `Statistics.newColumn(values)` automatically detects the type:
> - Numbers → `RatioColumn`: full statistical toolkit.
> - Strings → `Column`: ideal for frequency counts.

---


### 🧮 Standalone Tables

Tables let you manage multiple columns in a structured way.

```js
const table = Statistics.newTable({
  Numbers: [10, 20, 30, 40],
  Labels: ["X", "Y", "Z", "W"]
});

console.log(table.columns["Numbers"].mean);        // 25
console.log(table.columns["Labels"].frequencies);  // { X: 1, Y: 1, Z: 1, W: 1 }
```

> Tables automatically assign `Column` or `RatioColumn` types based on values.  
> Use `.columns[colName]` to access each column.

✨ Tables also support:
- Dynamic filtering
- Cloning with or without filters
- Column-level comparisons
- Transposing rows into columns
- Aggregating metrics (`descriptive`)

---


### 🔍 Row Filtering

Filter rows at both **column** and **table** levels:

```js
// Filter where Numbers ≤ 20
table.filterRowsBy("Numbers", v => v > 20);
console.log(table.columns["Numbers"].values); // [10, 20]
console.log(table.columns["Labels"].values);  // ["X", "Y"]

// Further filter the Numbers column directly
const col = table.columns["Numbers"];
col.filterRowsBy(v => v === 10);
console.log(col.values);                      // [20]
console.log(table.columns["Labels"].values);  // ["Y"]

// Reset all filters
table.clearAllRowsFilters();
```

> ⚠️ Filters are **exclusion-based**: the predicate returns **true to exclude** a row.  
> To keep values instead, use `v => !condition`.

---


### 📚 Using a Statistics Instance

Group and analyze multiple tables together:

```js
const stats = new Statistics();

const t1 = stats.addTable("Table1", { Data: [1, 2, 3] });
const t2 = stats.addTable("Table2", { Data: [4, 5, 6] });

// Aggregate metrics across tables
const means = stats.descriptive("mean");

console.log(means.columns["Table1"].values[0]); // 2
console.log(means.columns["Table2"].values[0]); // 5
```

> You can also apply filters globally using:
> - `stats.filterRows(indexes)`
> - `stats.clearAllRowsFilters()`

---