aadr-subset 0.1.0__py3-none-any.whl

aadr_subset/__init__.py

@@ -0,0 +1,5 @@
+"""aadr-subset: declarative AADR panel subsetting from YAML selectors."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

aadr_subset/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m aadr_subset` invocation."""
+
+from aadr_subset.cli import main
+
+if __name__ == "__main__":
+    main()

aadr_subset/cli.py

@@ -0,0 +1,359 @@
+"""click entry point + subcommand routing.
+
+Day 1: `validate` subcommand wired end-to-end. `select` / `inspect` /
+`report` / `template` land on Day 3+ per HLD project plan.
+
+Top-level exception handler maps AadrSubsetError subclasses → exit codes
+per LLD §3.8 pin. standalone_mode=False prevents click from intercepting
+exceptions before our handler runs.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from . import __version__
+from .commands.inspect_cmd import run_inspect
+from .commands.report_cmd import run_report
+from .commands.select_cmd import run_select
+from .commands.template_cmd import run_template
+from .commands.validate_cmd import run_validate
+from .errors import EXIT_UNEXPECTED, AadrSubsetError, UsageError
+from .selector import format_validation_errors
+
+
+def _version_message() -> str:
+    """Build the --version output. aadr-resolve version reported when the
+    import succeeds (it will not on Day 1 since aadr-resolve isn't imported
+    by validate). Day 2+ will pull aadr_resolve.__version__ here."""
+    try:
+        import aadr_resolve
+
+        aadr_resolve_v = getattr(aadr_resolve, "__version__", "<unknown>")
+        return f"aadr-subset {__version__}\naadr-resolve {aadr_resolve_v}"
+    except ImportError:
+        return f"aadr-subset {__version__}\naadr-resolve <not installed>"
+
+
+@click.group(invoke_without_command=False)
+@click.version_option(version=__version__, prog_name="aadr-subset", message=_version_message())
+@click.option(
+    "--quiet",
+    is_flag=True,
+    help="Suppress stdout summary on success; warnings to stderr; errors to stderr.",
+)
+@click.pass_context
+def cli(ctx: click.Context, quiet: bool) -> None:
+    """aadr-subset: declarative AADR panel subsetting from YAML selectors."""
+    ctx.ensure_object(dict)
+    ctx.obj["quiet"] = quiet
+
+
+@cli.command("validate")
+@click.argument("selector_path", type=click.STRING)
+@click.pass_context
+def validate_command(ctx: click.Context, selector_path: str) -> None:
+    """JSON-schema + semantic-constraint check on a selector YAML. No .anno
+    loaded. Useful in CI as a fast gate before any .anno is available."""
+    exit_code = run_validate(
+        selector_path=selector_path,
+        quiet=ctx.obj["quiet"],
+    )
+    sys.exit(exit_code)
+
+
+@cli.command("select")
+@click.argument("selector_path", type=click.STRING)
+@click.argument("anno_path", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "-o",
+    "--out",
+    type=click.Path(dir_okay=False),
+    default=None,
+    help="Output file path (default: stdout).",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["ids", "tsv", "json"]),
+    default="ids",
+    show_default=True,
+    help="Output format. `ids`=newline-delimited GeneticIDs; `tsv`=TSV with "
+    "genetic_id/individual_id/group_id/date_calbp/coverage/matched_criteria; "
+    "`json`=structured SubsetResult.",
+)
+@click.option(
+    "--schema-override",
+    type=click.Choice(["A", "B", "C", "D", "E"]),
+    default=None,
+    help="Force AnnoFrame schema class (A-E). Use when .anno is renamed but "
+    "matches an existing class signature.",
+)
+@click.option(
+    "--allow-empty",
+    is_flag=True,
+    help="Downgrade zero-match exit 1 to exit 0 (write an empty output file).",
+)
+@click.option(
+    "--allow-empty-source",
+    is_flag=True,
+    help="Allow individual_ids_source to be empty (exits 0 instead of 1).",
+)
+@click.option(
+    "--include-matched-criteria",
+    is_flag=True,
+    help="Include per-sample matched_criteria in JSON output (off by default).",
+)
+@click.option(
+    "--source-anno",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="Source .anno for cross-version IID lift. Required when selector sets resolve_to_version.",
+)
+@click.option(
+    "--mid-bridge",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="Optional MID-rename bridge TSV (4 cols: v_old_label, mid_old, "
+    "v_new_label, mid_new). Layers on top of aadr-resolve's GID-stable "
+    "auto-detection.",
+)
+@click.option(
+    "--strict-resolve",
+    is_flag=True,
+    help="On cross-version resolution, fail exit 1 if any source Individual_ID "
+    "fails to resolve. Default: warn to stderr and proceed with the resolvable "
+    "subset.",
+)
+@click.option(
+    "--coverage-column",
+    default=None,
+    metavar="NAME",
+    help="Canonical coverage field for min_coverage filters. Routed through "
+    "AnnoFrame.coverage_via(NAME). Useful for v62.0 (class D, no native "
+    "coverage column) — pass e.g. 'snps_hit_1240k' for a derived proxy. "
+    "Selector's coverage_column: takes precedence when both are set.",
+)
+@click.option(
+    "--coverage-derive",
+    default=None,
+    metavar="NAME",
+    help="Alias for --coverage-column (only one of the two may be set). "
+    "Mnemonic for the v62-class-D derived-proxy use case.",
+)
+@click.pass_context
+def select_command(
+    ctx: click.Context,
+    selector_path: str,
+    anno_path: str,
+    out: str | None,
+    fmt: str,
+    schema_override: str | None,
+    allow_empty: bool,
+    allow_empty_source: bool,
+    include_matched_criteria: bool,
+    source_anno: str | None,
+    mid_bridge: str | None,
+    strict_resolve: bool,
+    coverage_column: str | None,
+    coverage_derive: str | None,
+) -> None:
+    """Materialize a selector against a target AADR .anno; emit sample IDs / TSV / JSON.
+
+    Full HLD select surface: populations + individual_ids + date +
+    modern_only + min_coverage + any:/exclude: combinators against a
+    single .anno; ids / tsv / json output; cross-version IID lift via
+    --source-anno + selector.resolve_to_version.
+    """
+    exit_code = run_select(
+        selector_path=selector_path,
+        anno_path=anno_path,
+        out=out,
+        fmt=fmt,
+        schema_override=schema_override,
+        allow_empty=allow_empty,
+        allow_empty_source=allow_empty_source,
+        include_matched_criteria=include_matched_criteria,
+        source_anno=source_anno,
+        mid_bridge=mid_bridge,
+        strict_resolve=strict_resolve,
+        coverage_column=coverage_column,
+        coverage_derive=coverage_derive,
+        quiet=ctx.obj["quiet"],
+    )
+    sys.exit(exit_code)
+
+
+@cli.command("inspect")
+@click.argument("selector_path", type=click.STRING)
+@click.argument("anno_path", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--schema-override",
+    type=click.Choice(["A", "B", "C", "D", "E"]),
+    default=None,
+    help="Force AnnoFrame schema class (A-E).",
+)
+@click.option(
+    "--allow-empty-source",
+    is_flag=True,
+    help="Allow individual_ids_source to be empty.",
+)
+@click.option(
+    "--strict-resolve",
+    is_flag=True,
+    help="Show STRICT-RESOLVE diagnostic in the summary when missing-after-"
+    "resolve IDs are present. Per HLD §Inspect mode, --strict-resolve is "
+    "accepted for diagnostic display but never changes inspect's exit code "
+    "(inspect always exits 0).",
+)
+@click.pass_context
+def inspect_command(
+    ctx: click.Context,
+    selector_path: str,
+    anno_path: str,
+    schema_override: str | None,
+    allow_empty_source: bool,
+    strict_resolve: bool,
+) -> None:
+    """Diagnostic dry-run: shows what a selector matches against a target
+    .anno without writing any output. Always exits 0 (informational)."""
+    exit_code = run_inspect(
+        selector_path=selector_path,
+        anno_path=anno_path,
+        schema_override=schema_override,
+        allow_empty_source=allow_empty_source,
+        strict_resolve=strict_resolve,
+        quiet=ctx.obj["quiet"],
+    )
+    sys.exit(exit_code)
+
+
+@cli.command("report")
+@click.argument("selector_path", type=click.STRING)
+@click.argument("anno_path", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "-o",
+    "--out",
+    type=click.Path(dir_okay=False),
+    default=None,
+    help="Output file path (default: stdout).",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["tsv", "json"]),
+    default="tsv",
+    show_default=True,
+    help="Report format. `tsv`=per-group columns; `json`=structured object.",
+)
+@click.option(
+    "--schema-override",
+    type=click.Choice(["A", "B", "C", "D", "E"]),
+    default=None,
+    help="Force AnnoFrame schema class (A-E).",
+)
+@click.option(
+    "--allow-empty",
+    is_flag=True,
+    help="Downgrade zero-match exit 1 to exit 0 (write a header-only report).",
+)
+@click.option(
+    "--allow-empty-source",
+    is_flag=True,
+    help="Allow individual_ids_source to be empty.",
+)
+@click.option(
+    "--include-empty-groups",
+    is_flag=True,
+    help="Include rows for .anno groups with zero matches (n_matched=0). "
+    "Useful for population-survey workflows.",
+)
+@click.pass_context
+def report_command(
+    ctx: click.Context,
+    selector_path: str,
+    anno_path: str,
+    out: str | None,
+    fmt: str,
+    schema_override: str | None,
+    allow_empty: bool,
+    allow_empty_source: bool,
+    include_empty_groups: bool,
+) -> None:
+    """Per-population aggregate output: group_id, n_matched, n_in_anno,
+    pct_matched, date_min/max_calbp, coverage_median (+ JSON adds
+    coverage_min/max). Atomic write."""
+    exit_code = run_report(
+        selector_path=selector_path,
+        anno_path=anno_path,
+        out=out,
+        fmt=fmt,
+        schema_override=schema_override,
+        allow_empty=allow_empty,
+        allow_empty_source=allow_empty_source,
+        include_empty_groups=include_empty_groups,
+        quiet=ctx.obj["quiet"],
+    )
+    sys.exit(exit_code)
+
+
+@cli.command("template")
+@click.argument("name", required=False, default=None, type=click.STRING)
+@click.option(
+    "-o",
+    "--out",
+    type=click.Path(dir_okay=False),
+    default=None,
+    help="Output file path for emit mode (default: stdout).",
+)
+@click.pass_context
+def template_command(ctx: click.Context, name: str | None, out: str | None) -> None:
+    """Discover or emit a shipped selector template.
+
+    No-argument form: prints the sorted list of shipped templates to
+    stdout. Argument form: emits `<name>.yaml`'s verbatim content
+    (including its metadata block and comments) to stdout or --out PATH.
+    Unknown names exit 2 with a discovery hint."""
+    exit_code = run_template(name=name, out=out, quiet=ctx.obj["quiet"])
+    sys.exit(exit_code)
+
+
+def main() -> None:
+    """Top-level entry point. Maps AadrSubsetError subclasses to exit codes;
+    uncaught exceptions exit 70 (BSD EX_SOFTWARE)."""
+    try:
+        cli(standalone_mode=False)
+    except click.UsageError as e:
+        # click's own usage error (bad arg counts, etc.) → exit 2 by default;
+        # we map to 4 to align with HLD §Exit codes (usage error = 4).
+        sys.stderr.write(f"Usage error: {e.format_message()}\n")
+        sys.exit(4)
+    except click.exceptions.Abort:
+        # ctrl-C, etc. → exit 130 (conventional SIGINT exit code).
+        sys.exit(130)
+    except UsageError as e:
+        # UsageError may carry a list[ValidationError] payload (from
+        # selector load) or a plain message (from engine feature-gate).
+        if e.errors:
+            sys.stderr.write(format_validation_errors(e.errors) + "\n")
+        elif str(e):
+            sys.stderr.write(f"{e}\n")
+        sys.exit(e.exit_code)
+    except AadrSubsetError as e:
+        # Other tool-internal errors carry exit_code.
+        if str(e):
+            sys.stderr.write(f"{e}\n")
+        sys.exit(e.exit_code)
+    except SystemExit:
+        # run_<verb> orchestrators raise SystemExit via sys.exit() — pass
+        # through.
+        raise
+    except Exception:
+        # Uncaught exception → exit 70 with traceback to stderr.
+        import traceback
+
+        sys.stderr.write("INTERNAL ERROR: uncaught exception (please report):\n")
+        traceback.print_exc(file=sys.stderr)
+        sys.exit(EXIT_UNEXPECTED)

aadr_subset/commands/__init__.py

@@ -0,0 +1 @@
+"""Per-subcommand orchestrators. Each `run_<verb>` returns an int exit code."""

aadr_subset/commands/inspect_cmd.py

@@ -0,0 +1,129 @@
+"""inspect subcommand orchestrator.
+
+Diagnostic dry-run: shows what a selector matches against a target .anno
+without writing any file. Always exits 0 — inspect is informational; a
+non-zero exit on zero-match would defeat the purpose.
+
+Per LLD §3.10 / §4.3. Day 4 ships the single-version path; cross-version
+diagnostics land Day 6 alongside select's cross-version flow.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import replace
+
+import aadr_resolve
+
+from ..engine import select_samples
+from ..errors import EXIT_SUCCESS, IOFailure, UsageError, ValidationError
+from ..reporting import format_inspect_summary
+from ..selector import compute_signature, load_selector
+
+
+def run_inspect(
+    *,
+    selector_path: str,
+    anno_path: str,
+    schema_override: str | None,
+    allow_empty_source: bool,
+    strict_resolve: bool,
+    quiet: bool,
+) -> int:
+    """Orchestrate `aadr-subset inspect`. Always returns EXIT_SUCCESS.
+
+    Day-4 sequence (§4.3 reduced for single-version):
+    1. Load + validate selector.
+    2. Load target AnnoFrame.
+    3. Engine evaluation with include_matched_criteria=True (inspect's
+       output uses matched_criteria via the branch breakdown).
+    4. Populate run-env metadata.
+    5. Print format_inspect_summary to stdout (NOT stderr — inspect has
+       no machine-readable output to protect).
+    6. Return EXIT_SUCCESS regardless of n_matched. SoftValidationFailure
+       from zero matches becomes a stdout "0 samples matched" message.
+       strict_resolve diagnostics surface in the summary block but don't
+       change exit code (HLD §Inspect mode pin).
+    """
+    # 1. Load + validate selector.
+    _metadata, selector = load_selector(
+        selector_path,
+        allow_empty_source=allow_empty_source,
+    )
+
+    # 2. Load AnnoFrame.
+    schema_override_enum = _parse_schema_override(schema_override)
+    try:
+        anno = aadr_resolve.AnnoFrame.from_path(
+            anno_path,
+            schema_override=schema_override_enum,
+        )
+    except aadr_resolve.SchemaDetectionError as e:
+        raise IOFailure(f"AADR .anno schema unrecognized: {e}") from e
+    except (OSError, aadr_resolve.IOFailure) as e:
+        raise IOFailure(f"cannot load .anno at {anno_path}: {e}") from e
+
+    # 3. Engine evaluation. include_matched_criteria=True so the inspect
+    # summary can show per-branch attribution.
+    result = select_samples(
+        anno,
+        selector,
+        include_matched_criteria=True,
+    )
+
+    # 4. Compute signature + populate run-env metadata. cli_coverage_column
+    # is None until --coverage-column ships; selector.coverage_column alone
+    # drives the signature today.
+    sig = compute_signature(selector, cli_coverage_column=None)
+    result = replace(
+        result,
+        anno_file=str(anno_path),
+        anno_version=anno.version,
+        schema_class=anno.schema_class.value,
+        selector_file=selector_path,
+        selector_signature=sig,
+    )
+
+    # 5. Print inspect summary to STDOUT.
+    summary = format_inspect_summary(result, anno)
+
+    # strict_resolve diagnostic: HLD pins it as informational-only on
+    # inspect. Day 4 has no cross-version yet, so missing_after_resolve
+    # is always empty; reserved for Day 6.
+    if strict_resolve and result.warnings.missing_after_resolve:
+        missing = result.warnings.missing_after_resolve
+        shown = missing[:10]
+        summary += (
+            f"\n\n[STRICT-RESOLVE would fail: {len(missing)} Individual_ID(s) "
+            f"failed to resolve. First 10: {shown}]"
+        )
+
+    if not quiet:
+        sys.stdout.write(summary + "\n")
+
+    return EXIT_SUCCESS
+
+
+def _parse_schema_override(value: str | None):  # type: ignore[no-untyped-def]
+    """Map a CLI --schema-override CLASS letter to aadr_resolve.SchemaClass."""
+    if value is None:
+        return None
+    from aadr_resolve.types import SchemaClass
+
+    try:
+        return SchemaClass[value]
+    except KeyError as e:
+        raise UsageError(
+            errors=[
+                ValidationError(
+                    file="<cli>",
+                    line=1,
+                    col=1,
+                    pointer="/--schema-override",
+                    message=(
+                        f"unknown schema class '{value}'; expected one of "
+                        f"{[c.name for c in SchemaClass]}"
+                    ),
+                )
+            ],
+        ) from e

aadr_subset/commands/report_cmd.py

@@ -0,0 +1,168 @@
+"""report subcommand orchestrator.
+
+Per-population aggregate output. Same selector + AnnoFrame loading as
+`select`, then `reporting.write_report_tsv` / `write_report_json` instead
+of formats.py writers.
+
+Per LLD §3.13 / §4.5. Day 5 ships the single-version path; cross-version
+lands Day 6 alongside select's cross-version flow.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from dataclasses import replace
+from pathlib import Path
+
+import aadr_resolve
+
+from ..engine import select_samples
+from ..errors import (
+    EXIT_SUCCESS,
+    IOFailure,
+    SoftValidationFailure,
+    UsageError,
+    ValidationError,
+)
+from ..reporting import write_report_json, write_report_tsv
+from ..selector import compute_signature, load_selector
+from ..types import ReportFormat
+
+
+def run_report(
+    *,
+    selector_path: str,
+    anno_path: str,
+    out: str | None,
+    fmt: str,
+    schema_override: str | None,
+    allow_empty: bool,
+    allow_empty_source: bool,
+    include_empty_groups: bool,
+    quiet: bool,
+) -> int:
+    """Orchestrate `aadr-subset report`. Returns exit code.
+
+    Day-5 sequence (§4.5 reduced for single-version):
+    1. Load + validate selector.
+    2. Load target AnnoFrame.
+    3. Compute selector_signature.
+    4. Engine evaluation (include_matched_criteria=False — report doesn't
+       need per-row criteria, only group aggregates).
+    5. Exit-1 gate: n_matched == 0 and not allow_empty → SoftValidationFailure.
+    6. Populate run-env metadata.
+    7. Write report (TSV or JSON) via reporting.write_report_*.
+    8. One-line stdout summary unless quiet (HLD §Reports: report's stdout
+       summary is intentionally a one-liner — no parse/eval/write breakdown).
+    9. Return EXIT_SUCCESS.
+    """
+    t_parse_start = time.monotonic()
+
+    # 1. Load + validate selector.
+    _metadata, selector = load_selector(
+        selector_path,
+        allow_empty_source=allow_empty_source,
+    )
+
+    # 2. Load AnnoFrame.
+    schema_override_enum = _parse_schema_override(schema_override)
+    try:
+        anno = aadr_resolve.AnnoFrame.from_path(
+            anno_path,
+            schema_override=schema_override_enum,
+        )
+    except aadr_resolve.SchemaDetectionError as e:
+        raise IOFailure(f"AADR .anno schema unrecognized: {e}") from e
+    except (OSError, aadr_resolve.IOFailure) as e:
+        raise IOFailure(f"cannot load .anno at {anno_path}: {e}") from e
+
+    # 3. Compute selector signature.
+    sig = compute_signature(selector, cli_coverage_column=None)
+
+    parse_time = time.monotonic() - t_parse_start
+
+    # 4. Engine evaluation.
+    t_eval_start = time.monotonic()
+    result = select_samples(
+        anno,
+        selector,
+        include_matched_criteria=False,
+    )
+    eval_time = time.monotonic() - t_eval_start
+
+    # 5. Exit-1 gate.
+    if result.n_matched == 0 and not allow_empty:
+        raise SoftValidationFailure(
+            "selector matched 0 samples — report not written. "
+            "Pass --allow-empty for a header-only report."
+        )
+
+    # 6. Populate run-env metadata.
+    result = replace(
+        result,
+        anno_file=str(anno_path),
+        anno_version=anno.version,
+        schema_class=anno.schema_class.value,
+        selector_file=selector_path,
+        selector_signature=sig,
+    )
+
+    # 7. Write report.
+    fmt_enum = ReportFormat(fmt)
+    t_write_start = time.monotonic()
+    out_path = Path(out) if out else None
+    if fmt_enum == ReportFormat.TSV:
+        write_report_tsv(
+            result,
+            anno,
+            include_empty_groups=include_empty_groups,
+            out_path=out_path,
+        )
+    else:
+        write_report_json(
+            result,
+            anno,
+            include_empty_groups=include_empty_groups,
+            out_path=out_path,
+        )
+    write_time = time.monotonic() - t_write_start
+
+    # 8. One-line stdout summary (HLD §Reports). Intentionally not the
+    # multi-segment parse/eval/write breakdown that select uses.
+    if not quiet:
+        n_pops = len(result.per_population_counts)
+        pop_word = "population" if n_pops == 1 else "populations"
+        out_label = str(out_path) if out_path else "stdout"
+        total = parse_time + eval_time + write_time
+        sys.stderr.write(
+            f"Wrote {out_label} ({n_pops} {pop_word}, {result.n_matched} samples) "
+            f"in {total:.2f}s.\n"
+        )
+
+    return EXIT_SUCCESS
+
+
+def _parse_schema_override(value: str | None):  # type: ignore[no-untyped-def]
+    """Map a CLI --schema-override CLASS letter to aadr_resolve.SchemaClass."""
+    if value is None:
+        return None
+    from aadr_resolve.types import SchemaClass
+
+    try:
+        return SchemaClass[value]
+    except KeyError as e:
+        raise UsageError(
+            errors=[
+                ValidationError(
+                    file="<cli>",
+                    line=1,
+                    col=1,
+                    pointer="/--schema-override",
+                    message=(
+                        f"unknown schema class '{value}'; expected one of "
+                        f"{[c.name for c in SchemaClass]}"
+                    ),
+                )
+            ],
+        ) from e