openavmkit.headless

Run the OpenAVMKit pipeline stages without Jupyter.

The notebooks in notebooks/pipeline are the reference workflow. This module runs the same sequence of :mod:openavmkit.pipeline calls from plain Python, so scripts, CI jobs and desktop front ends can drive a locality end to end and receive structured progress (see :mod:openavmkit.progress).

Stages mirror the notebooks:

• assemble -- 01-assemble: load, merge, enrich, tag model groups.
• clean -- 02-clean: fills, equity clusters, sales processing, scrutiny.
• model -- 03-model: splits, spatial lag, area stats, try/finalize models, ratio study report.

Like the notebooks, a stage works inside its locality folder (in/, out/, cache/). :func:run_stage changes into that folder for the duration of the call and restores the previous working directory afterwards; it is meant to run one stage at a time per process.

run_stage

run_stage(project_dir, stage, on_progress=None, cancel=None, *, verbose=False, run_vacant=True, drop_scrutiny_outliers=None, do_shaps=False, use_saved_params=True)

Run one pipeline stage for a locality.

Parameters:

Name	Type	Description	Default
project_dir	path - like	The locality folder (the one containing in/ and out/).	required
stage	str	One of "assemble", "clean" or "model".	required
on_progress	callable	Receives a :class:openavmkit.progress.ProgressEvent at each step.	None
cancel	callable	Returns True to request cancellation; the stage then raises :class:openavmkit.progress.Cancelled at the next step boundary.	None
verbose	bool	Passed through to the pipeline functions. Defaults to False.	False
run_vacant	bool	Whether finalize_models also runs vacant-only models. Defaults to True, matching 03-model.	True
drop_scrutiny_outliers	bool	Whether sales scrutiny drops flagged sales (cluster and heuristic outliers). Defaults to analysis.sales_scrutiny.drop (clusters, heuristics), each True when not set, matching 02-clean.	None
do_shaps	bool	Whether try_models computes SHAP values. Defaults to False.	False
use_saved_params	bool	Whether finalize_models reuses saved tuned hyperparameters. Defaults to True, matching 03-model.	True

Raises:

Type	Description
ValueError	If stage is not a known stage.
Cancelled	If cancel returned True during the run.

Source code in openavmkit/headless.py

def run_stage(
    project_dir: str | os.PathLike,
    stage: str,
    on_progress: Optional[ProgressCallback] = None,
    cancel: Optional[CancelCheck] = None,
    *,
    verbose: bool = False,
    run_vacant: bool = True,
    drop_scrutiny_outliers: Optional[bool] = None,
    do_shaps: bool = False,
    use_saved_params: bool = True,
) -> None:
    """Run one pipeline stage for a locality.

    Parameters
    ----------
    project_dir : path-like
        The locality folder (the one containing ``in/`` and ``out/``).
    stage : str
        One of ``"assemble"``, ``"clean"`` or ``"model"``.
    on_progress : callable, optional
        Receives a :class:`openavmkit.progress.ProgressEvent` at each step.
    cancel : callable, optional
        Returns True to request cancellation; the stage then raises
        :class:`openavmkit.progress.Cancelled` at the next step boundary.
    verbose : bool, optional
        Passed through to the pipeline functions. Defaults to False.
    run_vacant : bool, optional
        Whether ``finalize_models`` also runs vacant-only models. Defaults to True,
        matching 03-model.
    drop_scrutiny_outliers : bool, optional
        Whether sales scrutiny drops flagged sales (cluster and heuristic outliers).
        Defaults to ``analysis.sales_scrutiny.drop`` (``clusters``, ``heuristics``), each
        True when not set, matching 02-clean.
    do_shaps : bool, optional
        Whether ``try_models`` computes SHAP values. Defaults to False.
    use_saved_params : bool, optional
        Whether ``finalize_models`` reuses saved tuned hyperparameters.
        Defaults to True, matching 03-model.

    Raises
    ------
    ValueError
        If ``stage`` is not a known stage.
    openavmkit.progress.Cancelled
        If ``cancel`` returned True during the run.
    """
    if stage not in STAGES:
        raise ValueError(f"Unknown stage '{stage}'. Expected one of: {', '.join(STAGES)}")
    project_dir = Path(project_dir).resolve()
    with progress.reporting(on_progress, cancel, stage), _in_locality(project_dir):
        if stage == "assemble":
            _assemble(verbose)
        elif stage == "clean":
            _clean(verbose, drop_scrutiny_outliers)
        else:
            _model(verbose, run_vacant, do_shaps, use_saved_params)