copra2 2.0.0rc3__py3-none-any.whl

copra/__init__.py

@@ -0,0 +1,8 @@
+"""COPRA — Constructing Proxy Records from Age Models.
+
+Python/Qt6 reimplementation of the original MATLAB/Octave toolbox. The
+scientifically relevant code lives in :mod:`copra.core` and has no Qt or
+matplotlib dependency; plotting and GUI layers build on top of it.
+"""
+
+__version__ = "2.0.0rc3"

copra/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m copra`` as an alias for the ``copra-cli`` entry point."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

copra/cli.py

@@ -0,0 +1,595 @@
+"""Command-line entry point (ports the scriptable behaviour of ``copra.m``).
+
+The ``copra-cli`` console script runs the whole non-interactive pipeline --
+load -> classify reversals -> (config-driven) reversal treatment -> hiatus
+handling -> Monte Carlo age model -> resample -> save results/session/log, and
+optionally save plots. All choices that ``copra.m`` collected interactively are
+supplied as CLI options or a TOML config file.
+
+Subcommands
+-----------
+run        Run the full pipeline and write outputs.
+check      Load the data and report reversals / hiatus candidates (no MC).
+reproduce  Re-run a saved JSON session (same inputs + seed => identical output).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import Counter
+from pathlib import Path
+
+from .core.hiatus import detect_hiatus_candidates
+from .core.io import CopraIOError, load_dating_table, load_proxy_record
+from .core.logging_ import (
+    load_json_session,
+    reproduce,
+    run_session,
+    save_results,
+)
+from .core.model import CopraSession, ReversalType
+from .core.reversals import (
+    ERROR_INCREASE_FACTOR,
+    classify_reversals,
+    treat_reversals,
+)
+
+
+def _error_factors_from_list(ids) -> dict[int, float]:
+    """Map repeated --increase-error ids to per-point factors (x1.1 per repeat)."""
+    counts = Counter(int(x) for x in (ids or []))
+    return {pid: ERROR_INCREASE_FACTOR**n for pid, n in counts.items()}
+
+
+_INTERP_CHOICES = ("linear", "pchip", "spline")
+
+# Keys read from a TOML ``[copra]`` table / defaults for a run.
+_DEFAULTS: dict = {
+    "M": 2000,
+    "interp": "pchip",
+    "output_dir": "output",
+    "confbnds_proxy": 95.0,
+    "confbnds_age": 95.0,
+    "sample_size": None,
+    "auto_hiatus": False,
+    "plots": False,
+}
+
+
+# --------------------------------------------------------------------------- #
+# Config handling
+# --------------------------------------------------------------------------- #
+def _load_config(path: str) -> dict:
+    import tomllib
+
+    with open(path, "rb") as fh:
+        data = tomllib.load(fh)
+    return data.get("copra", data)
+
+
+def _resolve_run_config(args: argparse.Namespace) -> dict:
+    """Merge defaults, an optional TOML config, and explicit CLI options."""
+    cfg = dict(_DEFAULTS)
+    if args.config:
+        cfg.update(_load_config(args.config))
+    scalar_keys = (
+        "dating",
+        "proxy",
+        "layercount",
+        "M",
+        "interp",
+        "seed",
+        "samplename",
+        "proxyname",
+        "output_dir",
+        "confbnds_proxy",
+        "confbnds_age",
+        "sample_size",
+        "hiatus",
+        "remove_points",
+        "increase_error",
+    )
+    for key in scalar_keys:
+        val = getattr(args, key, None)
+        if val is not None:
+            cfg[key] = val
+    for flag in ("auto_hiatus", "plots"):
+        cfg[flag] = bool(cfg.get(flag, False)) or bool(getattr(args, flag, False))
+    return cfg
+
+
+# --------------------------------------------------------------------------- #
+# Reporting helpers
+# --------------------------------------------------------------------------- #
+def _report_reversals(dating) -> None:
+    report = classify_reversals(dating)
+    if not report.has_reversal:
+        print("Reversals: none.")
+        return
+    print(
+        f"Reversals found: tractable around point(s) {report.tractable_points}, "
+        f"non-tractable around point(s) {report.nontractable_points}."
+    )
+    if any(t == ReversalType.NONTRACTABLE for t in report.rev_type):
+        print(
+            "  Note: non-tractable reversals should usually be removed "
+            "(--remove-points) before running."
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Subcommands
+# --------------------------------------------------------------------------- #
+def cmd_run(args: argparse.Namespace) -> int:
+    cfg = _resolve_run_config(args)
+    if not cfg.get("dating") or not cfg.get("proxy"):
+        print("error: --dating and --proxy are required.", file=sys.stderr)
+        return 2
+
+    remove_points = [int(x) for x in (cfg.get("remove_points") or [])]
+    error_factors = _error_factors_from_list(cfg.get("increase_error"))
+    samplename = cfg.get("samplename") or Path(cfg["dating"]).stem
+
+    print(f"Loading dating table: {cfg['dating']}")
+    _report_reversals(load_dating_table(cfg["dating"]))
+
+    hia = [float(x) for x in (cfg.get("hiatus") or [])]
+    if cfg["auto_hiatus"] and not hia:
+        dt = load_dating_table(cfg["dating"])
+        if remove_points or error_factors:
+            dt = treat_reversals(dt, remove_points, error_factors=error_factors)
+        hia = [float(x) for x in detect_hiatus_candidates(dt).depth]
+        print(f"Auto-detected hiatus depth(s): {hia if hia else 'none'}")
+
+    session = CopraSession(
+        dating_path=str(cfg["dating"]),
+        proxy_path=str(cfg["proxy"]),
+        layercount_path=str(cfg["layercount"]) if cfg.get("layercount") else None,
+        M=int(cfg["M"]),
+        interp_method=cfg["interp"],
+        hia_depth=hia,
+        remove_points=remove_points,
+        error_factors=error_factors,
+        confbnds_prxy=float(cfg["confbnds_proxy"]),
+        confbnds_age=float(cfg["confbnds_age"]),
+        samplename=samplename,
+        proxyname=cfg.get("proxyname") or "\\delta^{18}O",
+        sample_size=(float(cfg["sample_size"]) if cfg.get("sample_size") else None),
+        seed=int(cfg["seed"]) if cfg.get("seed") is not None else None,
+    )
+
+    print(
+        f"Running MC age model (M={session.M}, interp={session.interp_method}"
+        + (f", hiatus={hia}" if hia else "")
+        + (", layer counting" if session.layercount_path else "")
+        + ") ..."
+    )
+    run_session(session)
+    print(
+        f"Done: seed={session.seed}, redraws={session.ensemble.n_redraws}, "
+        f"{session.ensemble.ages.shape[0]} depths x {session.M} realizations."
+    )
+
+    paths = save_results(session, cfg["output_dir"])
+    for kind, path in paths.items():
+        print(f"  wrote {kind}: {path}")
+
+    if cfg["plots"]:
+        _save_plots(session, Path(cfg["output_dir"]), samplename)
+    return 0
+
+
+def _save_plots(session: CopraSession, output_dir: Path, samplename: str) -> None:
+    from matplotlib.backends.backend_agg import FigureCanvasAgg
+
+    from .plotting import plot_agemodel, plot_proxy_record
+
+    reversals = classify_reversals(session.dating)
+    figures = {
+        "agemodel": plot_agemodel(session, mode="mean", reversals=reversals),
+        "proxy": plot_proxy_record(session, mode="mean"),
+    }
+    for name, fig in figures.items():
+        FigureCanvasAgg(fig)
+        path = output_dir / f"{samplename}_{name}.png"
+        fig.savefig(path, dpi=120, bbox_inches="tight")
+        print(f"  wrote plot: {path}")
+
+
+def _save_figure(fig, path: Path) -> Path:
+    from matplotlib.backends.backend_agg import FigureCanvasAgg
+
+    FigureCanvasAgg(fig)
+    fig.savefig(path, dpi=120, bbox_inches="tight")
+    return path
+
+
+def _try_open(path: Path) -> None:
+    """Best-effort: open a file in the OS default viewer (never raises)."""
+    import subprocess
+
+    try:
+        if sys.platform == "darwin":
+            subprocess.Popen(
+                ["open", str(path)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        elif sys.platform.startswith("win"):
+            import os
+
+            os.startfile(str(path))  # type: ignore[attr-defined]
+        else:
+            subprocess.Popen(
+                ["xdg-open", str(path)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+    except Exception:
+        pass
+
+
+def _default_preview(fig, name: str) -> None:
+    """Save a preview figure to a temp PNG, report the path, and try to open it."""
+    import tempfile
+
+    fd, path_str = tempfile.mkstemp(prefix=f"copra_{name}_", suffix=".png")
+    import os
+
+    os.close(fd)
+    path = Path(path_str)
+    _save_figure(fig, path)
+    print(f"  preview ({name}) saved to: {path}")
+    _try_open(path)
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    dating = load_dating_table(args.dating)
+    d = dating.depth
+    print(f"Dating points: {len(dating)}  (depth {d[0]:g}..{d[-1]:g})")
+    if args.proxy:
+        proxy = load_proxy_record(args.proxy)
+        p = proxy.depth
+        print(f"Proxy samples: {len(proxy)}  (depth {p[0]:g}..{p[-1]:g})")
+    report = classify_reversals(dating)
+    _report_reversals(dating)
+    cand = detect_hiatus_candidates(dating)
+    if cand.any:
+        print(
+            f"Hiatus candidate depth(s): {[round(float(x), 2) for x in cand.depth]} "
+            f"(after dating point(s) {cand.after_points})"
+        )
+    else:
+        print("Hiatus candidates: none.")
+
+    if args.plots:
+        from .plotting import plot_dating_reversals, plot_hiatus_candidates
+
+        proxy = load_proxy_record(args.proxy) if args.proxy else None
+        out = Path(args.output_dir) if args.output_dir else Path(".")
+        out.mkdir(parents=True, exist_ok=True)
+        stem = Path(args.dating).stem
+        rev_png = _save_figure(
+            plot_dating_reversals(dating, report, proxy=proxy, samplename=stem),
+            out / f"{stem}_reversals.png",
+        )
+        hia_png = _save_figure(
+            plot_hiatus_candidates(dating, cand, proxy=proxy, samplename=stem),
+            out / f"{stem}_hiatus.png",
+        )
+        print(f"  wrote plot: {rev_png}")
+        print(f"  wrote plot: {hia_png}")
+    return 0
+
+
+def cmd_reproduce(args: argparse.Namespace) -> int:
+    if args.output_dir:
+        session = load_json_session(args.session)
+        run_session(session)
+        print(
+            f"Reproduced: seed={session.seed}, M={session.M}, "
+            f"ages={session.ensemble.ages.shape}"
+        )
+        paths = save_results(session, args.output_dir)
+        for kind, path in paths.items():
+            print(f"  wrote {kind}: {path}")
+    else:
+        ensemble = reproduce(args.session)
+        print(
+            f"Reproduced: seed={ensemble.seed}, ages={ensemble.ages.shape}, "
+            f"redraws={ensemble.n_redraws}"
+        )
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# Interactive mode (mirrors the guided copra.m workflow)
+# --------------------------------------------------------------------------- #
+def _ask(prompt, default, input_fn, output_fn):
+    suffix = f" [{default}]" if default not in ("", None) else ""
+    ans = input_fn(f"{prompt}{suffix}: ").strip()
+    return ans if ans else ("" if default is None else str(default))
+
+
+def _ask_yesno(prompt, default, input_fn, output_fn):
+    ans = input_fn(f"{prompt} [{'Y/n' if default else 'y/N'}]: ").strip().lower()
+    if not ans:
+        return default
+    return ans.startswith(("y", "j"))
+
+
+def _ask_number(prompt, default, cast, input_fn, output_fn):
+    while True:
+        ans = input_fn(f"{prompt} [{default}]: ").strip()
+        if not ans:
+            return default
+        try:
+            return cast(ans)
+        except ValueError:
+            output_fn(f"  Please enter a valid {cast.__name__}.")
+
+
+def _ask_choice(prompt, choices, default, input_fn, output_fn):
+    while True:
+        ans = _ask(f"{prompt} ({'/'.join(choices)})", default, input_fn, output_fn)
+        if ans in choices:
+            return ans
+        output_fn(f"  Choose one of: {', '.join(choices)}.")
+
+
+def _ask_existing_file(prompt, input_fn, output_fn):
+    while True:
+        ans = input_fn(f"{prompt} (blank to cancel): ").strip()
+        if not ans:
+            return None
+        if Path(ans).is_file():
+            return ans
+        output_fn(f"  File not found: {ans}")
+
+
+_AUTO_PREVIEW = object()  # sentinel: use the default preview handler
+
+
+def run_interactive(
+    input_fn=input,
+    output_fn=print,
+    default_output_dir="output",
+    preview_fn=_AUTO_PREVIEW,
+) -> int:
+    """Guided, prompt-driven run mirroring the MATLAB ``copra`` workflow.
+
+    ``input_fn``/``output_fn`` are injectable so the flow can be unit-tested with
+    scripted input. ``preview_fn(figure, name)`` displays the reversal and hiatus
+    review plots before the corresponding prompts; it defaults to
+    :func:`_default_preview` (saves a PNG and best-effort opens it) and can be set
+    to ``None`` to skip previews. Produces the same outputs as ``copra-cli run``
+    and records the choices in the JSON session, so the run stays reproducible.
+    """
+    p = output_fn
+    if preview_fn is _AUTO_PREVIEW:
+        preview_fn = _default_preview
+    p("COPRA — interactive age-depth modelling. Press Enter to accept [defaults].")
+
+    dating = _ask_existing_file("Dating-table file", input_fn, p)
+    if dating is None:
+        p("Cancelled.")
+        return 1
+    proxy = _ask_existing_file("Proxy-record file", input_fn, p)
+    if proxy is None:
+        p("Cancelled.")
+        return 1
+
+    layercount = None
+    if _ask_yesno("Provide layer-count data?", False, input_fn, p):
+        layercount = _ask_existing_file("Layer-count file", input_fn, p)
+
+    interp = _ask_choice("Interpolation method", _INTERP_CHOICES, "pchip", input_fn, p)
+    M = _ask_number("Number of MC realizations", 2000, int, input_fn, p)
+    confp = _ask_number("Proxy confidence interval (%)", 95.0, float, input_fn, p)
+    confa = _ask_number("Age confidence interval (%)", 95.0, float, input_fn, p)
+    seed_str = _ask("Random seed (blank = auto)", "", input_fn, p)
+    seed = int(seed_str) if seed_str else None
+    samplename = _ask("Sample name", Path(dating).stem, input_fn, p)
+    proxyname = _ask("Proxy name", "\\delta^{18}O", input_fn, p)
+
+    # Reversal review and (optional) treatment.
+    dating_tbl = load_dating_table(dating)
+    proxy_rec = load_proxy_record(proxy) if preview_fn is not None else None
+    report = classify_reversals(dating_tbl)
+    remove_points: list[int] = []
+    increase_ids: list[int] = []
+    if report.has_reversal:
+        p(
+            f"Reversals: tractable {report.tractable_points}, "
+            f"non-tractable {report.nontractable_points}."
+        )
+        if preview_fn is not None:
+            from .plotting import plot_dating_reversals
+
+            preview_fn(
+                plot_dating_reversals(
+                    dating_tbl, report, proxy=proxy_rec, samplename=samplename
+                ),
+                "reversals",
+            )
+        rm = _ask(
+            "Point id(s) to remove (space-separated, blank = none)", "", input_fn, p
+        )
+        remove_points = [int(x) for x in rm.split()]
+        ie = _ask(
+            "Point id(s) to widen error (repeat id to widen more, blank = none)",
+            "",
+            input_fn,
+            p,
+        )
+        increase_ids = [int(x) for x in ie.split()]
+    else:
+        p("Reversals: none.")
+
+    error_factors = _error_factors_from_list(increase_ids)
+
+    # Hiatus review.
+    treated = (
+        treat_reversals(dating_tbl, remove_points, error_factors=error_factors)
+        if (remove_points or error_factors)
+        else dating_tbl
+    )
+    candidates = detect_hiatus_candidates(treated)
+    if candidates.any:
+        depths = [round(float(x), 2) for x in candidates.depth]
+        p(f"Hiatus candidate depth(s): {depths}")
+        if preview_fn is not None:
+            from .plotting import plot_hiatus_candidates
+
+            preview_fn(
+                plot_hiatus_candidates(
+                    treated, candidates, proxy=proxy_rec, samplename=samplename
+                ),
+                "hiatus",
+            )
+    hia_in = _ask(
+        "Hiatus depths (space-separated; 'auto' = candidates; blank = none)",
+        "",
+        input_fn,
+        p,
+    )
+    if hia_in.strip().lower() == "auto":
+        hia = [float(x) for x in candidates.depth]
+    elif hia_in.strip():
+        hia = [float(x) for x in hia_in.split()]
+    else:
+        hia = []
+
+    output_dir = _ask("Output folder", default_output_dir, input_fn, p)
+    do_plots = _ask_yesno("Save plots?", True, input_fn, p)
+
+    session = CopraSession(
+        dating_path=str(dating),
+        proxy_path=str(proxy),
+        layercount_path=str(layercount) if layercount else None,
+        M=int(M),
+        interp_method=interp,
+        hia_depth=hia,
+        remove_points=remove_points,
+        error_factors=error_factors,
+        confbnds_prxy=float(confp),
+        confbnds_age=float(confa),
+        samplename=samplename or Path(dating).stem,
+        proxyname=proxyname or "\\delta^{18}O",
+        seed=seed,
+    )
+    p("Running MC age model ...")
+    run_session(session)
+    p(f"Done: seed={session.seed}, redraws={session.ensemble.n_redraws}.")
+    paths = save_results(session, output_dir)
+    for kind, path in paths.items():
+        p(f"  wrote {kind}: {path}")
+    if do_plots:
+        _save_plots(session, Path(output_dir), session.samplename)
+    return 0
+
+
+def cmd_interactive(args: argparse.Namespace) -> int:
+    return run_interactive()
+
+
+# --------------------------------------------------------------------------- #
+# Parser
+# --------------------------------------------------------------------------- #
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="copra-cli", description="COPRA age-depth modelling (command line)."
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    run = sub.add_parser("run", help="run the full pipeline and write outputs")
+    run.add_argument(
+        "--dating",
+        help="dating-table file (depth age ageerror [upper ageerror for asymmetric])",
+    )
+    run.add_argument("--proxy", help="proxy-record file (depth value [value error])")
+    run.add_argument("--layercount", help="layer-count file (depth age deptherror)")
+    run.add_argument("--M", type=int, help="number of Monte Carlo realizations")
+    run.add_argument("--interp", choices=_INTERP_CHOICES, help="interpolation method")
+    run.add_argument("--hiatus", type=float, nargs="*", help="explicit hiatus depth(s)")
+    run.add_argument("--auto-hiatus", action="store_true", help="detect hiatuses")
+    run.add_argument(
+        "--remove-points",
+        type=int,
+        nargs="*",
+        help="1-based dating point id(s) to remove",
+    )
+    run.add_argument(
+        "--increase-error",
+        type=int,
+        nargs="*",
+        help="1-based id(s); repeat an id to widen its error by 10% again",
+    )
+    run.add_argument("--confbnds-proxy", type=float, dest="confbnds_proxy")
+    run.add_argument("--confbnds-age", type=float, dest="confbnds_age")
+    run.add_argument(
+        "--sample-size",
+        type=float,
+        dest="sample_size",
+        help="proxy sample size (depth units); adds a uniform distance error",
+    )
+    run.add_argument("--seed", type=int, help="random seed (recorded either way)")
+    run.add_argument("--samplename")
+    run.add_argument("--proxyname")
+    run.add_argument("--output-dir", dest="output_dir", help="output folder")
+    run.add_argument("--plots", action="store_true", help="also save PNG plots")
+    run.add_argument("--config", help="TOML config file with a [copra] table")
+    run.set_defaults(func=cmd_run)
+
+    check = sub.add_parser("check", help="report reversals / hiatus candidates (no MC)")
+    check.add_argument("--dating", required=True, help="dating-table file")
+    check.add_argument(
+        "--proxy",
+        help="proxy-record file; with --plots its depth coverage is overlaid",
+    )
+    check.add_argument(
+        "--plots", action="store_true", help="save reversal and hiatus review plots"
+    )
+    check.add_argument(
+        "--output-dir",
+        dest="output_dir",
+        help="folder for --plots output (default: current dir)",
+    )
+    check.set_defaults(func=cmd_check)
+
+    repro = sub.add_parser("reproduce", help="re-run a saved JSON session")
+    repro.add_argument("session", help="path to a d_*.json session file")
+    repro.add_argument(
+        "--output-dir",
+        dest="output_dir",
+        help="if given, write results/session/log here",
+    )
+    repro.set_defaults(func=cmd_reproduce)
+
+    interactive = sub.add_parser(
+        "interactive", help="guided, prompt-driven run (like the MATLAB workflow)"
+    )
+    interactive.set_defaults(func=cmd_interactive)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Console-script entry point registered as ``copra-cli``.
+
+    With no subcommand it starts the interactive workflow (mirroring MATLAB
+    ``copra``); pass ``--help`` for the option reference.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if not getattr(args, "command", None):
+            return run_interactive()
+        return args.func(args)
+    except (CopraIOError, ValueError, FileNotFoundError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

copra/core/__init__.py

@@ -0,0 +1 @@
+"""Pure-computation core of COPRA (no Qt or matplotlib imports)."""