Guided Statistics

Start with a question, see what the data can support, and keep the evidence visible. The exploration and task-first tools explain their choices instead of silently choosing an analysis for you.

A safe first pass

Import the statistics package as stat. The public functions below are readable wrappers around runtime builtins. They return ordinary records, so you can inspect the numbers and explanations rather than accepting a hidden decision.

import "statistics" as stat

let values = [12.1, 12.4, 12.8, 13.0, 13.2, 13.5, 29.0]
let result = stat.explore(values, {name: "protein concentration"})

println(stat.explain(result))
println(stat.distribution_ascii(values))
result.review_flags

The examples on this page are copyable package examples. The raw stats_* names shown in the tables are implementation-level builtins; application code should normally use stat.*.

A short analysis that still explains itself

When the study design is already known, use a task-first helper. The helper keeps the code short but returns the method, reason, assumptions, alternatives, effect estimates, uncertainty, and the equivalent low-level call. It does not guess whether observations are paired or independent.

import "statistics" as stat

let control = [12.1, 12.4, 12.8, 13.0, 13.2]
let treated = [13.0, 13.5, 13.9, 14.2, 14.8]

let result = stat.compare_groups(control, treated, {method: "welch"})
println(stat.explain_task(result))

# Keep these with the numerical result.
result.method
result.assumptions
result.alternatives
result.reproducible_call

The same schema powers the CLI notebook generator. Run bl stats to see its questions, then create an editable notebook:

bl stats compare measurements.csv --columns control,treated --output comparison.bln
bl notebook comparison.bln

1. Understand one numeric variable

Begin here when you have one measurement such as expression, concentration, age, or read depth.

Centre and spread belong together

Variance is the average squared distance from the mean; SD is its square root and is in the original unit. Neither is “left” or “right.” On a symmetric bell-shaped distribution, mean ± 1, 2, and 3 SD are useful visual landmarks. They are not universal outlier rules for skewed data.

2. Audit a whole table and its design

let audit = stat.scan(data, {
  subject_column: "patient_id",
  group_column: "treatment",
  batch_column: "sequencing_batch"
})

println(stat.overview_ascii(data))
println(stat.explain(audit))
audit.recommendations

Column roles are declared by you; BioLang does not infer experimental units or randomization from convenient column names. Missingness patterns are investigation clues, not proof that data are MCAR, MAR, or MNAR.

3. Compare groups, relationships, and categories

Correlation describes association, not causation. A small p-value does not tell you whether an effect is important, whether groups were independent, or whether the study design was unbiased.

4. Omics and dependent data

5. Check fitted models

Raw builtins versus the public API

The runtime performs deterministic full-data calculations under the stats_* names. The package wrappers keep user code short and stable. For example, stat.explore calls stats_explore, and stat.glm_diagnostics calls stats_glm_diagnostics. Use the raw name only when developing or testing the runtime itself.

Where to go next

• Use Math & Statistics for direct summaries, hypothesis tests, probability functions, and mathematical operations.
• Use the Practical Biostatistics book for visual, concept-first learning.
• Keep the returned record with your analysis so the evidence, options, backend, and limitations remain auditable.