als-statistics/docs/04-column/01-columns.md

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

## 📊 Working with Columns

The `Column` and `RatioColumn` classes represent the two main types of data: **categorical** and **numeric**. Each supports filtering, statistics, and derived metrics.

> ✅ Columns can now be **empty** (`[]`) — all methods handle them gracefully and return default values like `0`, `NaN`, or `[]`.

---

### `Column` (Categorical Data)

- **Use For:** Strings, labels, categories.
- **Created By:**
  - `Statistics.newColumn(["A", "B", "A"])`
  - `table.addColumn("Name", ["A", "B", "A"])`

#### 🔧 Key Properties & Methods:

| Feature                     | Description                                                                 |
|----------------------------|-----------------------------------------------------------------------------|
| `values`                   | Array of current values (after filters).                                    |
| `n`                        | Number of unfiltered values.                                                |
| `frequencies`              | Object with counts of each unique value.                                    |
| `relativeFrequencies`      | Object with proportions (relative frequencies).                             |
| `sorted`                   | Alphabetically sorted values.                                               |
| `percentile(p)`            | Percentile by index, e.g., `50` is median (treats values as ordered).       |
| `median`, `q1`, `q3`       | Predefined percentiles (50th, 25th, 75th).                                  |
| `count(fn, filtered=true)` | Number of values satisfying a condition.                                    |
| `filterRows(indexes)`      | Exclude rows by their indexes.                                              |
| `filterRowsBy(fn)`         | Exclude rows where `fn(value, index)` returns `true`.                       |
| `clearRowsFilters()`       | Remove all filters.                                                         |
| `clone(filtered = true)`   | Create a filtered or unfiltered copy of the column.                         |

#### 🧪 Example:

~~~js
const col = Statistics.newColumn(["A", "B", "A", "C"]);
col.filterRowsBy(v => v === "B"); // Exclude "B"
console.log(col.values);          // ["A", "A", "C"]
console.log(col.frequencies);     // { A: 2, C: 1 }
~~~

---

### `RatioColumn` (Numeric Data)

- **Use For:** Numbers (measurements, ratings, etc.).
- **Created By:**
  - `Statistics.newColumn([1, 2, 3])`
  - `table.addColumn("Scores", [1, 2, 3])`

#### 📐 Basic Statistics:

| Method              | Description                             |
|---------------------|-----------------------------------------|
| `sum`, `mean`       | Total and average of values.            |
| `min`, `max`, `range` | Extremes and spread.                 |

#### 📊 Variability Metrics:

- **Population**:
  - `variancePopulation`, `stdDevPopulation`
  - `skewnessPopulation`, `kurtosisPopulation`
- **Sample**:
  - `varianceSample`, `stdDevSample`
  - `skewnessSample`, `kurtosisSample`

#### 📏 Dispersion:

- `cv`: Coefficient of Variation
- `relativeDispersion`: StdDev / Median
- `iqr`: Interquartile range

#### 🔍 Advanced Metrics:

- `geometricMean`, `harmonicMean`, `flatness`
- `sumOfSquares`: Σ(x²)
- `normalizedValues`: Min-max scaling to [0, 1]
- `zScores`: Standardized values (z = (x - μ) / σ)
- `confidenceInterval95`: `{ low, high, width }` — 95% CI around the mean
- `spectralPowerDensityArray`, `spectralPowerDensityMetric`: Noise structure indicators
- `noiseStability`: Simple noise estimator

#### 🧭 New Tools:

| Method                         | Description                                                                 |
|--------------------------------|-----------------------------------------------------------------------------|
| `xValues`                      | Automatically generates `[1, 2, ..., n]` for regression or plotting.        |
| `regressionSlope(customX?)`   | Calculates slope (β) vs. `xValues` or custom X-axis.                       |

> `regressionSlope` uses covariance and variance internally. Returns `0` if X is constant.

#### ⚠️ Outlier Detection:

- `outliersIQR`: Outliers using interquartile method.
- `outliersZScore(threshold = 3)`: Outliers based on z-scores.

#### 🧪 Example:

~~~js
const col = Statistics.newColumn([1, 2, 3, 100]);
col.filterRowsBy(v => v > 10); // Exclude 100
console.log(col.mean);         // 2
console.log(col.outliersIQR);  // []
console.log(col.regressionSlope()); // 1 (if x = [1, 2, 3])
~~~

---

✅ Both `Column` and `RatioColumn` support row-level filtering and full integration with `Table` and `Statistics`.