@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/exa-search/scripts/exa_extract.py

@@ -1,117 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["exa-py>=1.14.0"]
-# ///
-"""Fetch and extract content from URLs using Exa's /contents endpoint.
-
-Example:
-    uv run exa_extract.py \\
-        https://arxiv.org/abs/2401.04088 \\
-        https://www.nature.com/articles/s41586-024-07566-y \\
-        --text \\
-        -o extracted.json
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-from dataclasses import asdict, dataclass, field
-from typing import Any
-
-try:
-    from exa_py import Exa
-except ImportError:
-    print(
-        "exa_py not installed. Run: uv pip install exa-py  (or invoke with: uv run --with exa-py)",
-        file=sys.stderr,
-    )
-    sys.exit(2)
-
-
-EXA_INTEGRATION_HEADER = "k-dense-ai--scientific-agent-skills"
-
-
-@dataclass
-class ExtractedDocument:
-    """Typed view of a single extracted document for JSON export."""
-
-    url: str
-    id: str | None
-    title: str | None
-    author: str | None
-    published_date: str | None
-    text: str | None = None
-    highlights: list[str] = field(default_factory=list)
-
-
-def _build_contents(text: bool, highlights: bool) -> dict[str, Any]:
-    contents: dict[str, Any] = {}
-    if text:
-        contents["text"] = True
-    if highlights:
-        contents["highlights"] = True
-    if not contents:
-        # Default to full text when the caller doesn't pick anything.
-        contents["text"] = True
-    return contents
-
-
-def _to_typed(item: Any) -> ExtractedDocument:
-    return ExtractedDocument(
-        url=getattr(item, "url", ""),
-        id=getattr(item, "id", None),
-        title=getattr(item, "title", None),
-        author=getattr(item, "author", None),
-        published_date=getattr(item, "published_date", None),
-        text=getattr(item, "text", None),
-        highlights=list(getattr(item, "highlights", None) or []),
-    )
-
-
-def run(args: argparse.Namespace) -> dict[str, Any]:
-    api_key = os.environ.get("EXA_API_KEY")
-    if not api_key:
-        print("EXA_API_KEY environment variable is not set.", file=sys.stderr)
-        sys.exit(2)
-
-    client = Exa(api_key=api_key)
-    client.headers["x-exa-integration"] = EXA_INTEGRATION_HEADER
-
-    contents = _build_contents(args.text, args.highlights)
-    response = client.get_contents(urls=args.urls, **contents)
-
-    typed = [_to_typed(item) for item in getattr(response, "results", []) or []]
-    return {
-        "urls": list(args.urls),
-        "num_results": len(typed),
-        "results": [asdict(doc) for doc in typed],
-    }
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="Extract content from URLs with Exa.")
-    parser.add_argument("urls", nargs="+", help="One or more URLs to extract.")
-    parser.add_argument("--text", action="store_true", help="Return full-text content.")
-    parser.add_argument("--highlights", action="store_true", help="Return extracted highlight snippets.")
-    parser.add_argument("-o", "--output", default=None, help="Write JSON to this file (default: stdout).")
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    payload = run(args)
-    text = json.dumps(payload, indent=2, ensure_ascii=False)
-    if args.output:
-        with open(args.output, "w", encoding="utf-8") as fh:
-            fh.write(text)
-        print(f"Wrote {len(payload['results'])} documents to {args.output}")
-    else:
-        print(text)
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/skills/exa-search/scripts/exa_search.py

@@ -1,179 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["exa-py>=1.14.0"]
-# ///
-"""Run an Exa web search and write results to JSON.
-
-Uses the Exa Python SDK. Auth via the EXA_API_KEY environment variable.
-
-Example:
-    uv run exa_search.py "transformer architectures" \\
-        --category "research paper" \\
-        --text --highlights \\
-        -o results.json
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-from dataclasses import asdict, dataclass, field
-from typing import Any
-
-try:
-    from exa_py import Exa
-except ImportError:
-    print(
-        "exa_py not installed. Run: uv pip install exa-py  (or invoke with: uv run --with exa-py)",
-        file=sys.stderr,
-    )
-    sys.exit(2)
-
-
-EXA_INTEGRATION_HEADER = "k-dense-ai--scientific-agent-skills"
-
-
-@dataclass
-class SearchResult:
-    """Typed view of a single Exa search result for JSON export."""
-
-    title: str | None
-    url: str
-    id: str | None
-    author: str | None
-    published_date: str | None
-    score: float | None
-    text: str | None = None
-    highlights: list[str] = field(default_factory=list)
-    highlight_scores: list[float] = field(default_factory=list)
-
-
-def _split_csv(value: str | None) -> list[str] | None:
-    if not value:
-        return None
-    items = [item.strip() for item in value.split(",") if item.strip()]
-    return items or None
-
-
-def _build_contents(text: bool, highlights: bool) -> dict[str, Any] | None:
-    contents: dict[str, Any] = {}
-    if text:
-        contents["text"] = True
-    if highlights:
-        contents["highlights"] = True
-    return contents or None
-
-
-def _result_to_typed(item: Any) -> SearchResult:
-    highlights = list(getattr(item, "highlights", None) or [])
-    scores = list(getattr(item, "highlight_scores", None) or [])
-    return SearchResult(
-        title=getattr(item, "title", None),
-        url=getattr(item, "url", ""),
-        id=getattr(item, "id", None),
-        author=getattr(item, "author", None),
-        published_date=getattr(item, "published_date", None),
-        score=getattr(item, "score", None),
-        text=getattr(item, "text", None),
-        highlights=highlights,
-        highlight_scores=scores,
-    )
-
-
-def run(args: argparse.Namespace) -> dict[str, Any]:
-    api_key = os.environ.get("EXA_API_KEY")
-    if not api_key:
-        print("EXA_API_KEY environment variable is not set.", file=sys.stderr)
-        sys.exit(2)
-
-    client = Exa(api_key=api_key)
-    # Attribute API usage to this skill for integration tracking.
-    client.headers["x-exa-integration"] = EXA_INTEGRATION_HEADER
-
-    contents = _build_contents(args.text, args.highlights)
-
-    kwargs: dict[str, Any] = {
-        "query": args.query,
-        "num_results": args.num_results,
-        "type": args.type,
-    }
-    if args.category:
-        kwargs["category"] = args.category
-    if include := _split_csv(args.include_domains):
-        kwargs["include_domains"] = include
-    if exclude := _split_csv(args.exclude_domains):
-        kwargs["exclude_domains"] = exclude
-    if args.start_published_date:
-        kwargs["start_published_date"] = args.start_published_date
-    if args.end_published_date:
-        kwargs["end_published_date"] = args.end_published_date
-    if args.user_location:
-        kwargs["user_location"] = args.user_location
-
-    if contents is not None:
-        response = client.search_and_contents(**kwargs, **contents)
-    else:
-        response = client.search(**kwargs)
-
-    typed = [_result_to_typed(item) for item in getattr(response, "results", []) or []]
-    return {
-        "query": args.query,
-        "type": args.type,
-        "num_results": len(typed),
-        "autoprompt_string": getattr(response, "autoprompt_string", None),
-        "results": [asdict(result) for result in typed],
-    }
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="Search the web with Exa.")
-    parser.add_argument("query", help="Natural-language search query.")
-    parser.add_argument(
-        "--type",
-        default="auto",
-        choices=["auto", "fast", "deep"],
-        help="Search type. 'auto' is Exa's general-purpose search; 'fast' is lowest latency; 'deep' is highest quality at higher latency.",
-    )
-    parser.add_argument("--num-results", type=int, default=10, help="Number of results (1-100).")
-    parser.add_argument(
-        "--category",
-        default=None,
-        choices=[
-            "company",
-            "research paper",
-            "news",
-            "github",
-            "personal site",
-            "financial report",
-            "people",
-        ],
-        help="Bias results toward a content category.",
-    )
-    parser.add_argument("--include-domains", default=None, help="Comma-separated allowlist.")
-    parser.add_argument("--exclude-domains", default=None, help="Comma-separated blocklist.")
-    parser.add_argument("--start-published-date", default=None, help="ISO date, e.g. 2024-01-01.")
-    parser.add_argument("--end-published-date", default=None, help="ISO date, e.g. 2024-12-31.")
-    parser.add_argument("--user-location", default=None, help="Two-letter ISO country code.")
-    parser.add_argument("--text", action="store_true", help="Return full-text content per result.")
-    parser.add_argument("--highlights", action="store_true", help="Return extracted highlight snippets.")
-    parser.add_argument("-o", "--output", default=None, help="Write JSON to this file (default: stdout).")
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    payload = run(args)
-    text = json.dumps(payload, indent=2, ensure_ascii=False)
-    if args.output:
-        with open(args.output, "w", encoding="utf-8") as fh:
-            fh.write(text)
-        print(f"Wrote {len(payload['results'])} results to {args.output}")
-    else:
-        print(text)
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/skills/experimental-design/references/design_types.md

@@ -1,129 +0,0 @@
-# Design Types and the Replication Structure
-
-Choosing the right design structure is mostly about matching the *unit of
-randomization* and the *unit of replication* to your question, and respecting any
-nesting in the analysis. This file walks through the standard structures and then
-treats the single most common fatal error — pseudoreplication — in depth.
-
-## Table of contents
-- [Completely randomized design](#completely-randomized-design)
-- [Randomized complete block design](#randomized-complete-block-design)
-- [Latin square](#latin-square)
-- [Repeated-measures and crossover](#repeated-measures-and-crossover)
-- [Split-plot designs](#split-plot-designs)
-- [Cluster / group-randomized designs](#cluster--group-randomized-designs)
-- [Nested designs and pseudoreplication](#nested-designs-and-pseudoreplication)
-
-## Completely randomized design
-
-Units are assigned to treatments purely at random, no blocking. Simplest design;
-appropriate when units are homogeneous and there's no identifiable nuisance factor.
-Analyze with one-way ANOVA / regression. If units are *not* homogeneous, the
-nuisance variation inflates error — block instead.
-
-## Randomized complete block design
-
-Group units into **blocks** of similar units (day, batch, litter), and randomize all
-treatments *within* each block. Every treatment appears once per block. The
-between-block variation is removed from the error term, sharply increasing precision
-when blocks differ. Analyze with `treatment + block` in the model. This is the
-default upgrade over a completely randomized design whenever a nuisance factor exists.
-
-## Latin square
-
-Controls **two** nuisance factors simultaneously with a square layout: each treatment
-appears exactly once in every row and every column. Classic uses: row = day, column =
-position/order, cell = treatment. Requires #treatments = #rows = #columns, and assumes
-no interactions between the blocking factors and treatment. Efficient when both
-nuisance dimensions matter and runs are limited. (Graeco-Latin squares extend this to
-three nuisance factors.)
-
-## Repeated-measures and crossover
-
-Each subject receives more than one condition, serving as its own control. This
-removes between-subject variation — usually the largest noise source — so these
-designs are far more powerful per subject.
-
-- **Repeated measures:** the same units measured under several conditions or over
-  time.
-- **Crossover:** each subject receives each treatment in sequence, with **washout**
-  periods between to clear carry-over. Subjects are randomized to treatment *orders*
-  (e.g. an AB/BA crossover; or a Williams square for ≥3 treatments to balance order).
-
-Watch for:
-- **Carry-over / residual effects** — an effect of the previous treatment persisting
-  into the next period. Adequate washout is essential; otherwise the design is biased.
-- **Period effects** — systematic change over time (learning, fatigue, disease
-  progression). Balanced orders let you separate period from treatment.
-- **Correlation within subject** — the repeated observations are not independent; the
-  analysis must model it (mixed model / repeated-measures ANOVA). Sample-size/power
-  for these depends on the within-subject correlation — use simulation in the
-  **statistical-power** skill.
-
-## Split-plot designs
-
-Arises when some factors are **hard to change** (applied to large units) and others
-are **easy to change** (applied to sub-units). The hard-to-change factor is randomized
-to whole plots; the easy factor is randomized to subplots within each whole plot.
-Example: oven temperature (whole plot — you can't re-set it per sample) × coating type
-(subplot — applied per sample). Crucially there are **two different error terms** — one
-for whole-plot factors, one for subplot factors — and the analysis must use both.
-Treating a split-plot as a completely randomized factorial gives wrong (usually
-anticonservative) tests for the whole-plot factor. Industrial DOE and agricultural
-trials are full of accidental split-plots; recognize when a factor can't be reset per
-run.
-
-## Cluster / group-randomized designs
-
-When the intervention is delivered to a *group* (a clinic's protocol, a classroom
-curriculum, a village water supply), you can only randomize at the group level. The
-**cluster is the unit of randomization**, and because members of a cluster are
-correlated, it is effectively the unit of replication too.
-
-- Power depends on the number of **clusters** far more than the number of individuals,
-  and on the **intraclass correlation (ICC)**. Adding people to existing clusters
-  helps much less than adding clusters.
-- The **design effect** `DEFF = 1 + (m − 1)·ICC` (m = cluster size) quantifies how
-  much the effective sample size shrinks; even a small ICC with large clusters costs
-  dearly. Power these by simulation (see **statistical-power**).
-- Analyze with a method that accounts for clustering (mixed model with a cluster
-  random effect, or GEE). Analyzing individuals as independent is pseudoreplication.
-
-## Nested designs and pseudoreplication
-
-**Pseudoreplication** is treating non-independent measurements as independent
-replicates. It is the most common and most damaging design error in experimental
-biology, and it cannot be fixed after data collection — only by designing and
-analyzing at the correct level.
-
-The principle: **the replicate is whatever the treatment is independently applied
-and randomized to.** Measurements taken below that level are *technical replicates* —
-they improve the precision of a single unit's value but do **not** add degrees of
-freedom for testing the treatment.
-
-Worked examples:
-- **One dish per treatment, 50 cells imaged.** Treatment applied to the dish ⇒ n = 1
-  per treatment. The 50 cells describe that one dish; they are not 50 independent
-  tests of the treatment. You need multiple independently treated dishes.
-- **3 mice per group, 100 cells each.** n = 3 (mice) for a treatment given to the
-  mouse, not 300 (cells). Average within mouse, or use a mixed model with mouse as a
-  random effect.
-- **One tank of fish given a diet, every fish measured.** The tank is the unit (the
-  diet was randomized to the tank) ⇒ n = number of tanks, not number of fish. Shared
-  tank water, temperature, and social effects make fish within a tank correlated.
-- **Repeated measurements over time on the same subject** are nested within subject;
-  the subject is the replicate.
-
-How to avoid it:
-1. **Identify the experimental unit** = the smallest physical entity to which a
-   treatment level is independently and randomly assigned.
-2. **Replicate at that level** — more independently treated units, not more
-   measurements per unit (though technical replicates can reduce measurement noise).
-3. **Analyze with the nesting respected** — average to the unit level, or fit a mixed
-   model with random effects for the nesting (cells in mice, fish in tanks, time in
-   subjects). The fixed-effect treatment test then uses the correct, larger error and
-   correct degrees of freedom.
-
-Technical replicates are still worth taking — they sharpen each unit's estimate — but
-report and analyze them as what they are, never as independent biological replicates.
-For sample size of nested/clustered designs, use simulation in **statistical-power**.

package/skills/experimental-design/references/factorial_and_doe.md

@@ -1,130 +0,0 @@
-# Factorial and Design-of-Experiments (DOE)
-
-When several factors might affect a response, testing them **one factor at a time
-(OFAT)** is both wasteful and blind to interactions. Factorial designs vary factors
-*together*, so you estimate every main effect and interaction from the same runs,
-with better precision per run. This file covers the family of DOE designs and the
-concepts (resolution, aliasing) needed to read them. Generate them with
-`scripts/doe_designs.py`.
-
-## Table of contents
-- [Why factorial beats OFAT](#why-factorial-beats-ofat)
-- [Full factorial (2^k)](#full-factorial)
-- [Fractional factorial (2^(k-p))](#fractional-factorial)
-- [Resolution and aliasing](#resolution-and-aliasing)
-- [Screening designs (Plackett-Burman)](#screening-designs)
-- [Response-surface designs](#response-surface-designs)
-- [Space-filling designs](#space-filling-designs)
-- [Choosing a design](#choosing-a-design)
-
-## Why factorial beats OFAT
-
-Vary one factor while holding others fixed and you (1) spend runs inefficiently and
-(2) can never see **interactions** — cases where the effect of A depends on the level
-of B, which are the rule, not the exception, in real systems. A factorial varies all
-factors simultaneously across runs; each effect is estimated using *all* the data, so
-a 2^k factorial is more precise than k separate OFAT studies of the same size.
-
-## Full factorial
-
-A **2^k** design runs every combination of k factors at two levels (low/high, coded
-−1/+1). It estimates all k main effects and all 2^k − k − 1 interactions.
-
-- Runs = 2^k: 8 for 3 factors, 16 for 4, 32 for 5. Practical to ~5 factors.
-- Use when you have a handful of factors and want a full picture including
-  interactions.
-- `two_level_factorial({"temp": (20,60), "conc": (1,10), "pH": (6,8)})` → 8 runs.
-- For factors with more than two levels, use `full_factorial` with explicit level
-  lists (runs = product of level counts — grows fast).
-
-Add **center points** (all factors at their midpoint) to a two-level design to get a
-cheap check for curvature: if the center response departs from the factorial average,
-a linear model is inadequate and you need a response-surface design.
-
-## Fractional factorial
-
-When k is large, 2^k is too many runs — but most high-order interactions are
-negligible (the *sparsity-of-effects* principle). A **2^(k−p)** fractional factorial
-runs a carefully chosen fraction (1/2, 1/4, ...) of the full design, trading the
-ability to estimate some interactions for far fewer runs.
-
-- `fractional_factorial(factors, generator="a b c abc")` builds a half-fraction of 4
-  factors in 8 runs. The generator string (Yates notation) assigns each factor to a
-  column; a multi-letter token aliases that factor with an interaction.
-- The price is **aliasing**: some effects become indistinguishable. You must know
-  which.
-
-## Resolution and aliasing
-
-**Aliasing** (confounding) means two effects are estimated by the same contrast — the
-data cannot separate them. Which effects are aliased is summarized by the design's
-**resolution**:
-
-| Resolution | Aliasing | Interpretation |
-|------------|----------|----------------|
-| **III** | main effects aliased with 2-factor interactions | Screening only; a "significant" main effect might be an interaction |
-| **IV** | main effects clear of 2FI, but 2FIs aliased with each other | Good for screening; main effects trustworthy |
-| **V** | main effects and 2FIs all clear of each other (aliased with 3FI+) | Can model main effects and 2-factor interactions confidently |
-
-Always state the resolution and inspect the alias structure before interpreting a
-fractional design. Concluding "factor C has no effect" is unsafe if C is aliased with
-a real interaction (it could cancel out). When in doubt, choose a higher-resolution
-generator (more runs) or add runs to **de-alias** (fold-over / augment the design).
-
-## Screening designs
-
-When the goal is to **find the vital few** factors out of many (5, 10, 20+), use a
-screening design that estimates main effects only, as cheaply as possible:
-- **Plackett-Burman** (`plackett_burman`): runs = the next multiple of 4 above k
-  (e.g. 12 runs for up to 11 factors). Resolution III — two-factor interactions are
-  heavily confounded with main effects. Perfect for triage: run it, keep the few
-  factors with large effects, then study those with a full or higher-resolution
-  factorial.
-- Resolution III fractional factorials serve the same purpose.
-
-Screen first, optimize later — don't try to learn interactions and find the optimum
-in one cheap design.
-
-## Response-surface designs
-
-Two-level designs fit only a flat (linear + interaction) model; they cannot locate an
-interior optimum or describe **curvature**. To fit a quadratic and optimize, use a
-response-surface methodology (RSM) design over continuous factors:
-
-- **Central composite design (CCD)** (`central_composite`): a 2^k factorial + center
-  points + axial ("star") points. The axial points add the levels needed to estimate
-  quadratic terms. With `face="circumscribed"` (default) the axial points sit
-  *outside* the factorial box (so actual factor levels exceed your stated low/high);
-  use `face="inscribed"` or `"faced"` to keep everything within the original range.
-- **Box-Behnken** (`box_behnken`, needs ≥3 factors): a quadratic design that avoids
-  the extreme all-low/all-high corners — useful when those corners are unsafe,
-  expensive, or infeasible. More economical than a CCD for 3–5 factors.
-
-Workflow: screen → factorial (find important factors & rough region) → response
-surface (model curvature, locate optimum), often moving the experimental region
-between steps (path of steepest ascent).
-
-## Space-filling designs
-
-For **computer experiments / simulations** (deterministic or expensive models) where
-classical replication and blocking don't apply, you want even coverage of a
-high-dimensional input space:
-- **Latin hypercube** (`latin_hypercube`): each factor's range is divided into
-  n_samples equal bins, sampled once each, arranged to spread points apart
-  (`criterion="maximin"`). Gives good coverage with relatively few points and is the
-  standard input design for surrogate/emulator modeling and sensitivity analysis.
-
-## Choosing a design
-
-| Goal | Factors | Design | Script function |
-|------|---------|--------|-----------------|
-| Screen many factors | 5–20+ | Plackett-Burman / Res III | `plackett_burman` |
-| Main effects, some interactions, few runs | 4–8 | Res IV/V fractional | `fractional_factorial` |
-| All effects + interactions | 2–5 | Full 2^k factorial | `two_level_factorial` |
-| Multi-level categorical | few | Full factorial | `full_factorial` |
-| Optimize a response (curvature) | 2–5 | Central composite / Box-Behnken | `central_composite`, `box_behnken` |
-| Cover a simulation input space | any | Latin hypercube | `latin_hypercube` |
-
-In all cases, **randomize run order** (the scripts do by default) so factors aren't
-confounded with time-related drift, and add center points to two-level designs as a
-curvature check.

package/skills/experimental-design/references/randomization_and_blocking.md

@@ -1,116 +0,0 @@
-# Randomization, Blocking, Stratification, and Controls
-
-These are the tools of *local control*: removing or balancing nuisance variation so
-the comparison you care about is clean. Randomization handles the unknown
-confounders; blocking and stratification handle the known ones; controls and
-blinding handle the systematic biases.
-
-## Randomization — why and how
-
-Randomization assigns treatments to units by chance, so that in expectation every
-confounder (measured or not, known or unknown) is balanced across arms. This is the
-foundation of causal inference: without it, an observed difference could always be
-due to some variable that happened to track the grouping.
-
-Use a **seeded, reproducible** schedule (see `scripts/randomization.py`) and follow
-it exactly. Record the seed. "I randomized somehow" is neither auditable nor
-reproducible.
-
-### Methods (and when each is right)
-
-| Method | What it does | Use when |
-|--------|--------------|----------|
-| **Simple** | Independent random assignment per unit | n is large (≳100); simplicity matters; imbalance is tolerable |
-| **Permuted block** | Within each block, arms appear in fixed ratio; order shuffled | You need balance throughout enrollment, or n is small/moderate, or intake is sequential |
-| **Stratified block** | Separate blocks within each level of a prognostic factor | A known covariate (site, sex, stage) must be balanced across arms |
-| **Cluster** | Whole groups (clinics, classes) assigned to arms | The intervention is delivered at a group level |
-| **Minimization** | Adaptively assign to minimize imbalance across several covariates | Many prognostic factors and small n (specialized; not in the script) |
-
-**Simple randomization caveat:** with small n it behaves like flipping a few coins —
-you can easily get 12 vs. 8 instead of 10 vs. 10, and worse for subgroups. Blocking
-fixes this.
-
-**Block size:** must be a multiple of the ratio unit (e.g. for 1:1, sizes 2, 4, 6).
-Smaller blocks balance more tightly but are more predictable in unblinded trials
-(a clinician who knows the block size can guess the last allocation). Vary block
-size or keep it concealed when predictability is a concern.
-
-## Blocking — removing known nuisance variation
-
-A **block** is a group of units expected to be similar (same day, batch, litter,
-plate, instrument run). You randomize treatments *within* each block. The nuisance
-variation between blocks is then removed from the error term, so the treatment
-comparison is more precise — often dramatically so.
-
-Block on anything that (a) you can identify before the experiment and (b) you
-expect to affect the response but isn't of interest itself:
-- **Time:** day, week, session, processing batch.
-- **Space:** plate, plate position/edge, shelf, cage rack, field plot.
-- **Material:** reagent lot, animal litter, cell passage, donor.
-- **People/instruments:** technician, machine, sequencing run.
-
-Rule of thumb: *"Block what you can, randomize what you cannot."* If you suspect a
-factor matters but can't block it, at least randomize across it and record it as a
-covariate.
-
-**Randomized complete block design (RCBD):** every treatment appears once in every
-block. This is the workhorse design — analyze with treatment + block in the model.
-
-## Stratification vs. blocking vs. covariate adjustment
-
-These overlap; the distinction is about *when* you control the variable:
-- **Stratify / block at design time** when the factor is known before assignment and
-  you want guaranteed balance (the safest, since it doesn't rely on a model).
-- **Adjust as a covariate at analysis time** (ANCOVA, regression) when the factor is
-  continuous or measured after assignment. Often you do both: stratify on the big
-  ones, adjust for the rest.
-
-A few strata are better than many: stratifying on too many factors at once leaves
-strata with too few units to block effectively. For many covariates and small n,
-minimization is the alternative.
-
-## Controls
-
-A comparison needs a concurrent baseline. Match the control to the threat you're
-ruling out:
-- **Untreated / standard-of-care control** — isolates the treatment effect from time.
-- **Vehicle / sham control** — isolates the active ingredient from the delivery
-  (injection stress, vehicle solvent, sham surgery).
-- **Positive control** — a treatment known to produce the effect, to confirm the
-  assay can detect one at all.
-- **Concurrent, not historical** — controls run at the same time as the treatment;
-  historical controls reintroduce time confounding.
-
-## Blinding
-
-Blinding prevents expectation from biasing measurement and behavior:
-- **Single-blind:** the subject doesn't know the assignment.
-- **Double-blind:** neither subject nor experimenter/assessor knows.
-- **Blinded outcome assessment:** at minimum, whoever measures the outcome shouldn't
-  know the group — cheap and high-value even in animal/bench work.
-Allocation concealment (the person enrolling can't foresee the next assignment) is
-distinct from blinding and just as important; a sealed seeded schedule provides it.
-
-## Batch effects and plate layout (especially omics / HTS)
-
-Batch effects are systematic technical differences between processing groups and are
-a leading cause of irreproducible high-throughput results.
-- **Never let batch align with the biological condition.** If all cases are in batch
-  1 and all controls in batch 2, condition and batch are perfectly confounded and
-  no normalization can separate them.
-- **Randomize or block sample-to-batch and position-within-plate.** Spread each
-  condition across all batches and across plate positions.
-- **Avoid edge effects:** evaporation and thermal gradients make outer wells differ;
-  don't load all controls into edge columns. Randomize positions, or include
-  replicates spanning edge and interior.
-- **Include anchor/reference samples** in every batch to estimate and correct batch
-  shifts.
-- Use `assign_factorial_runs()` / the randomization functions to generate a
-  randomized processing order and position map.
-
-## Documentation
-
-Record, and ideally pre-register: the randomization method, the seed, block sizes,
-stratification factors, the schedule itself, and the planned analysis (which must
-include block/stratum/cluster terms). This is what makes the study auditable and the
-primary analysis confirmatory rather than exploratory.