femic.pipeline.io Module

The femic.pipeline.io module is FEMIC’s main path-resolution and run-configuration seam. It turns CLI/profile inputs into normalized run options, resolves which instance-root and external-data artifacts should be used, and assembles the environment payload that the legacy subprocess wrapper needs to execute Stage 00/01a/01b work consistently.

If you are debugging why FEMIC picked the wrong instance root, log directory, run profile, SiteProd artifact, THLB raster, or external data root, this is the first module to read. In practice it owns:

  • loading and validating YAML/JSON run profiles

  • normalizing FMU/code lists and other CLI/profile option surfaces

  • building the dataclass payloads that carry resolved path contracts

  • resolving canonical external-data, SiteProd, and THLB artifact locations

  • constructing the environment and command payload for legacy-script execution

Start Here If…

Use this page first if you are trying to:

  • understand how --instance-root and FEMIC_INSTANCE_ROOT affect runtime path resolution

  • trace how config/run_profile.*.yaml becomes effective FEMIC run options

  • debug whether FEMIC should use instance-local artifacts or published canonical assets from FEMIC_EXTERNAL_DATA_ROOT

  • inspect which environment variables the CLI passes into the legacy stage scripts

  • decide whether a path/bootstrap bug belongs here or in a lower-level stage helper such as femic.pipeline.siteprod or femic.workflows.legacy

Typical maintenance path:

  1. Start with load_pipeline_run_profile() and resolve_effective_run_options() if the issue begins with CLI/profile behavior.

  2. Move to resolve_run_paths() and build_pipeline_run_config() if the problem is about instance-root/log-dir/output-root resolution.

  3. Read resolve_legacy_external_data_paths(), resolve_legacy_siteprod_artifacts(), and resolve_legacy_thlb_raster_path() when artifact selection or public data fallback is the concern.

  4. Finish with build_legacy_execution_plan() if the failure is visible in subprocess env vars, working directory, manifest paths, or legacy command handoff.

Typical Usage

The common pattern is to normalize CLI/profile input first and only then build the subprocess-ready execution payload:

from pathlib import Path
from femic.pipeline.io import build_pipeline_run_config

run_config = build_pipeline_run_config(
    tsa_list=["k3z"],
     resume=True,
    run_id="docs_example",
    instance_root=Path("external/femic-k3z-instance"),
)

How This Fits Into The Pipeline

This module sits between the CLI layer and the legacy workflow/runtime layer. It does not perform the heavy geospatial, VDYP, TIPSY, or Patchworks work itself. Instead, it defines which files, paths, and environment contracts those stages will see.

That makes it a high-leverage debugging seam. If FEMIC is using the wrong data root, missing a required config path, writing logs to the wrong place, or pointing a stage at the wrong canonical artifact, the problem usually starts here before the downstream runtime ever begins.

Main Sub-Flows

The most important sub-flows in this module are:

  • Profile loading and normalization load_pipeline_run_profile(), normalize_tsa_list(), and resolve_effective_run_options() turn CLI/profile inputs into normalized execution options. The helper name still reflects the legacy tsa schema seam even when the selected targets are generic FMU/code values.

  • Dataclass payload construction build_pipeline_run_config() and the module-level dataclasses make the run/profile/path contracts explicit instead of passing unstructured path bags around the pipeline.

  • External-data and artifact resolution resolve_legacy_external_data_paths(), build_legacy_data_artifact_paths(), resolve_legacy_siteprod_artifacts(), and resolve_legacy_thlb_raster_path() decide which real source artifacts a stage should consume.

  • Legacy execution planning resolve_run_paths() and build_legacy_execution_plan() assemble the working directory, manifest/log locations, env vars, and command payload used to launch the legacy stage script.

Key Entry Surfaces

The highest-value entrypoints in this module are:

  • load_pipeline_run_profile() Load and validate YAML/JSON run-profile files.

  • resolve_effective_run_options() Merge explicit CLI values with profile defaults.

  • resolve_legacy_external_data_paths() Pick the effective external data root and the main VRI/VDYP/management-unit/SiteProd source paths.

  • resolve_legacy_siteprod_artifacts() Prefer instance-local or canonical pre-stacked SiteProd assets when both TIFF and band-map sidecar are available.

  • resolve_legacy_thlb_raster_path() Fall back from instance-local data/misc.thlb.tif to the canonical public mirror when needed.

  • build_legacy_execution_plan() Build the final subprocess-ready payload for legacy stage execution.

The small dataclasses in this module are also important because they define the main path and config contracts explicitly:

  • PipelineRunConfig

  • PipelineRunProfile

  • EffectiveRunOptions

  • RunPaths

  • LegacyExecutionPlan

  • LegacyDataArtifactPaths

  • LegacyExternalDataPaths

  • LegacySiteProdArtifacts

Artifact Resolution Rules

The most important path/artifact resolution behavior in this module is:

  • run profiles are loaded from YAML or JSON and must have mapping-shaped root, selection, modes, and run sections when present

  • the legacy tsa selection list is normalized to canonical string case codes even when it is being used generically for FMU selection

  • instance-root-aware paths are built under the active runtime root instead of assuming one hard-coded workspace layout

  • external data is resolved from the first viable candidate among: caller/env override, repo-local data, sibling ../data, and ~/data

  • canonical SiteProd behavior prefers a paired TIFF + band-map sidecar before falling back to the old export-and-stack path

  • THLB raster behavior prefers instance-local data/misc.thlb.tif first and then falls back to FEMIC_EXTERNAL_DATA_ROOT/misc.thlb.tif

Those rules are why this module matters for fresh clones, tmp-clone reruns, and the bundled external/* example instances. It is the place where FEMIC decides whether a stripped instance copy can still borrow canonical public artifacts from the mirrored data root.

Environment And Legacy Handoff

When FEMIC launches the legacy stage script, this module is responsible for the main env contract, including:

  • FEMIC_TSA_LIST (legacy env name for selected FMU/code targets)

  • FEMIC_RESUME and FEMIC_NO_CACHE

  • FEMIC_RUN_ID and FEMIC_RUN_UUID

  • FEMIC_LOG_DIR and FEMIC_OUTPUT_ROOT

  • FEMIC_INSTANCE_ROOT and FEMIC_SOURCE_ROOT

  • FEMIC_VDYP_CFG_DIR

  • FEMIC_RUN_CONFIG_PATH / FEMIC_RUN_CONFIG_SHA256

  • optional boundary/stratification/managed-curve overrides

If the legacy script sees the wrong config, wrong working directory, or wrong artifact root, the bug often traces back to how build_legacy_execution_plan() assembled this environment.

Failure Seams To Watch

The common failure boundaries in this module are:

  • invalid run-profile structure malformed or incorrectly typed YAML/JSON fields raise early normalization errors here rather than later in the pipeline

  • wrong instance-root assumptions if the caller expects repo-coupled behavior but passes a different --instance-root, downstream stages may appear to “lose” files when the real problem is path resolution

  • incomplete public-data materialization canonical fallback paths only help if external/femic-public-data has been materialized with DataLad and FEMIC_EXTERNAL_DATA_ROOT points at real payloads

  • SiteProd/THLB mismatch confusion a missing paired SiteProd TIFF + bandmap or a missing THLB raster can cause FEMIC to switch from canonical-artifact mode back to a legacy fallback path

  • env drift into legacy scripts if log-dir, config, or VDYP-related env vars look wrong in downstream runs, this module is usually where to inspect first

Cross-References

Guides and references that pair especially closely with this module:

Related API pages:

I/O-oriented helpers shared across pipeline entrypoints.

class femic.pipeline.io.EffectiveRunOptions(tsa_list, strata_list, resume, dry_run, verbose, skip_checks, debug_rows, run_id, log_dir, boundary_path, boundary_layer, boundary_code, strat_bec_grouping, strat_species_combo_count, strat_include_tm_species2_for_single, strat_top_area_coverage, strat_target_nstrata, tipsy_vdyp_ylim, vdyp_sampling_mode, vdyp_two_pass_rebin, vdyp_min_stands_per_si_bin, vdyp_toe_shift_years, vdyp_force_tail_blend, vdyp_enable_late_gate_rescue, managed_curve_mode, managed_curve_x_scale, managed_curve_y_scale, managed_curve_truncate_at_culm, managed_curve_max_age, yield_assumptions_path, vri_rel_candidates, vdyp_input_rel_candidates)[source]

Bases: object

Resolved run options after merging CLI values with optional profile config.

Parameters:

  • tsa_list (list[str])

  • strata_list (list[str])

  • resume (bool)

  • dry_run (bool)

  • verbose (bool)

  • skip_checks (bool)

  • debug_rows (int | None)

  • run_id (str | None)

  • log_dir (Path)

  • boundary_path (Path | None)

  • boundary_layer (str | None)

  • boundary_code (str | None)

  • strat_bec_grouping (str | None)

  • strat_species_combo_count (int | None)

  • strat_include_tm_species2_for_single (bool | None)

  • strat_top_area_coverage (float | None)

  • strat_target_nstrata (int | None)

  • tipsy_vdyp_ylim (tuple[float, float] | None)

  • vdyp_sampling_mode (str | int | None)

  • vdyp_two_pass_rebin (bool | None)

  • vdyp_min_stands_per_si_bin (int | None)

  • vdyp_toe_shift_years (float | None)

  • vdyp_force_tail_blend (bool | None)

  • vdyp_enable_late_gate_rescue (bool | None)

  • managed_curve_mode (str | None)

  • managed_curve_x_scale (float | None)

  • managed_curve_y_scale (float | None)

  • managed_curve_truncate_at_culm (bool | None)

  • managed_curve_max_age (int | None)

  • yield_assumptions_path (Path | None)

  • vri_rel_candidates (list[Path] | None)

  • vdyp_input_rel_candidates (list[Path] | None)

boundary_code: str | None
boundary_layer: str | None
boundary_path: Path | None
debug_rows: int | None
dry_run: bool
log_dir: Path
managed_curve_max_age: int | None
managed_curve_mode: str | None
managed_curve_truncate_at_culm: bool | None
managed_curve_x_scale: float | None
managed_curve_y_scale: float | None
resume: bool
run_id: str | None
skip_checks: bool
strat_bec_grouping: str | None
strat_include_tm_species2_for_single: bool | None
strat_species_combo_count: int | None
strat_target_nstrata: int | None
strat_top_area_coverage: float | None
strata_list: list[str]
tipsy_vdyp_ylim: tuple[float, float] | None
tsa_list: list[str]
vdyp_enable_late_gate_rescue: bool | None
vdyp_force_tail_blend: bool | None
vdyp_input_rel_candidates: list[Path] | None
vdyp_min_stands_per_si_bin: int | None
vdyp_sampling_mode: str | int | None
vdyp_toe_shift_years: float | None
vdyp_two_pass_rebin: bool | None
verbose: bool
vri_rel_candidates: list[Path] | None
yield_assumptions_path: Path | None
class femic.pipeline.io.LegacyDataArtifactPaths(ria_stands_path, vdyp_input_pandl_path, site_prod_bc_gdb_path, tsa_boundaries_feather_path, vri_vclr1p_categorical_columns_path, ria_vclr1p_feature_tif_path, siteprod_gdb_path, siteprod_tmpexport_tif_path_prefix, siteprod_tif_path, siteprod_bandmap_path, vdyp_ply_feather_path, vdyp_lyr_feather_path, vdyp_results_tsa_pickle_path_prefix, vdyp_results_pickle_path, vdyp_curves_smooth_tsa_feather_path_prefix, vdyp_curves_smooth_feather_path, tipsy_params_path_prefix, tipsy_params_columns_path, model_input_bundle_dir, misc_thlb_tif_path, stands_shp_dir)[source]

Bases: object

Legacy data artifact paths used by 00_data-prep orchestration.

Parameters:

  • ria_stands_path (Path)

  • vdyp_input_pandl_path (Path)

  • site_prod_bc_gdb_path (Path)

  • tsa_boundaries_feather_path (Path)

  • vri_vclr1p_categorical_columns_path (Path)

  • ria_vclr1p_feature_tif_path (Path)

  • siteprod_gdb_path (Path)

  • siteprod_tmpexport_tif_path_prefix (Path)

  • siteprod_tif_path (Path)

  • siteprod_bandmap_path (Path)

  • vdyp_ply_feather_path (Path)

  • vdyp_lyr_feather_path (Path)

  • vdyp_results_tsa_pickle_path_prefix (Path)

  • vdyp_results_pickle_path (Path)

  • vdyp_curves_smooth_tsa_feather_path_prefix (Path)

  • vdyp_curves_smooth_feather_path (Path)

  • tipsy_params_path_prefix (Path)

  • tipsy_params_columns_path (Path)

  • model_input_bundle_dir (Path)

  • misc_thlb_tif_path (Path)

  • stands_shp_dir (Path)

misc_thlb_tif_path: Path
model_input_bundle_dir: Path
ria_stands_path: Path
ria_vclr1p_feature_tif_path: Path
site_prod_bc_gdb_path: Path
siteprod_bandmap_path: Path
siteprod_gdb_path: Path
siteprod_tif_path: Path
siteprod_tmpexport_tif_path_prefix: Path
stands_shp_dir: Path
tipsy_params_columns_path: Path
tipsy_params_path_prefix: Path
tsa_boundaries_feather_path: Path
vdyp_curves_smooth_feather_path: Path
vdyp_curves_smooth_tsa_feather_path_prefix: Path
vdyp_input_pandl_path: Path
vdyp_lyr_feather_path: Path
vdyp_ply_feather_path: Path
vdyp_results_pickle_path: Path
vdyp_results_tsa_pickle_path_prefix: Path
vri_vclr1p_categorical_columns_path: Path
class femic.pipeline.io.LegacyExecutionPlan(script_path, run_paths, run_id, run_uuid, tsa_list, manifest_path, checkpoint_paths, output_root, output_version_tag, run_config_path, run_config_sha256, env, cmd, working_dir)[source]

Bases: object

Fully resolved execution inputs for legacy subprocess runs.

Parameters:

  • script_path (Path)

  • run_paths (RunPaths)

  • run_id (str)

  • run_uuid (str)

  • tsa_list (list[str])

  • manifest_path (Path)

  • checkpoint_paths (list[Path])

  • output_root (Path)

  • output_version_tag (str)

  • run_config_path (Path | None)

  • run_config_sha256 (str | None)

  • env (dict[str, str])

  • cmd (list[str])

  • working_dir (Path)

checkpoint_paths: list[Path]
cmd: list[str]
env: dict[str, str]
manifest_path: Path
output_root: Path
output_version_tag: str
run_config_path: Path | None
run_config_sha256: str | None
run_id: str
run_paths: RunPaths
run_uuid: str
script_path: Path
tsa_list: list[str]
working_dir: Path
class femic.pipeline.io.LegacyExternalDataPaths(external_data_root, vri_vclr1p_path, vdyp_input_pandl_path, tsa_boundaries_path, site_prod_bc_gdb_path, siteprod_tif_path, siteprod_bandmap_path)[source]

Bases: object

Resolved external source roots consumed by legacy 00_data-prep.

Parameters:

  • external_data_root (Path)

  • vri_vclr1p_path (Path)

  • vdyp_input_pandl_path (Path)

  • tsa_boundaries_path (Path)

  • site_prod_bc_gdb_path (Path)

  • siteprod_tif_path (Path)

  • siteprod_bandmap_path (Path)

external_data_root: Path
site_prod_bc_gdb_path: Path
siteprod_bandmap_path: Path
siteprod_tif_path: Path
tsa_boundaries_path: Path
vdyp_input_pandl_path: Path
vri_vclr1p_path: Path
class femic.pipeline.io.LegacySiteProdArtifacts(siteprod_tif_path, siteprod_bandmap_path, use_prestacked, source_label)[source]

Bases: object

Resolved SiteProd artifacts for Stage 00 runtime selection.

Parameters:

  • siteprod_tif_path (Path)

  • siteprod_bandmap_path (Path)

  • use_prestacked (bool)

  • source_label (str)

siteprod_bandmap_path: Path
siteprod_tif_path: Path
source_label: str
use_prestacked: bool
class femic.pipeline.io.PipelineRunConfig(tsa_list, resume, debug_rows=None, run_id=None, log_dir=None, output_root=PosixPath('outputs'), run_config_path=None, run_config_sha256=None, boundary_path=None, boundary_layer=None, boundary_code=None, strat_bec_grouping=None, strat_species_combo_count=None, strat_include_tm_species2_for_single=None, strat_top_area_coverage=None, strat_target_nstrata=None, tipsy_vdyp_ylim=None, vdyp_sampling_mode=None, vdyp_two_pass_rebin=None, vdyp_min_stands_per_si_bin=None, vdyp_toe_shift_years=None, vdyp_force_tail_blend=None, vdyp_enable_late_gate_rescue=None, managed_curve_mode=None, managed_curve_x_scale=None, managed_curve_y_scale=None, managed_curve_truncate_at_culm=None, managed_curve_max_age=None, yield_assumptions_path=None, vri_rel_candidates=None, vdyp_input_rel_candidates=None, instance_root=None)[source]

Bases: object

Explicit run configuration passed from CLI into workflow wrappers.

Parameters:

  • tsa_list (list[str])

  • resume (bool)

  • debug_rows (int | None)

  • run_id (str | None)

  • log_dir (Path | None)

  • output_root (Path)

  • run_config_path (Path | None)

  • run_config_sha256 (str | None)

  • boundary_path (Path | None)

  • boundary_layer (str | None)

  • boundary_code (str | None)

  • strat_bec_grouping (str | None)

  • strat_species_combo_count (int | None)

  • strat_include_tm_species2_for_single (bool | None)

  • strat_top_area_coverage (float | None)

  • strat_target_nstrata (int | None)

  • tipsy_vdyp_ylim (tuple[float, float] | None)

  • vdyp_sampling_mode (str | int | None)

  • vdyp_two_pass_rebin (bool | None)

  • vdyp_min_stands_per_si_bin (int | None)

  • vdyp_toe_shift_years (float | None)

  • vdyp_force_tail_blend (bool | None)

  • vdyp_enable_late_gate_rescue (bool | None)

  • managed_curve_mode (str | None)

  • managed_curve_x_scale (float | None)

  • managed_curve_y_scale (float | None)

  • managed_curve_truncate_at_culm (bool | None)

  • managed_curve_max_age (int | None)

  • yield_assumptions_path (Path | None)

  • vri_rel_candidates (list[Path] | None)

  • vdyp_input_rel_candidates (list[Path] | None)

  • instance_root (Path | None)

boundary_code: str | None = None
boundary_layer: str | None = None
boundary_path: Path | None = None
debug_rows: int | None = None
instance_root: Path | None = None
log_dir: Path | None = None
managed_curve_max_age: int | None = None
managed_curve_mode: str | None = None
managed_curve_truncate_at_culm: bool | None = None
managed_curve_x_scale: float | None = None
managed_curve_y_scale: float | None = None
output_root: Path = PosixPath('outputs')
resume: bool
run_config_path: Path | None = None
run_config_sha256: str | None = None
run_id: str | None = None
strat_bec_grouping: str | None = None
strat_include_tm_species2_for_single: bool | None = None
strat_species_combo_count: int | None = None
strat_target_nstrata: int | None = None
strat_top_area_coverage: float | None = None
tipsy_vdyp_ylim: tuple[float, float] | None = None
tsa_list: list[str]
vdyp_enable_late_gate_rescue: bool | None = None
vdyp_force_tail_blend: bool | None = None
vdyp_input_rel_candidates: list[Path] | None = None
vdyp_min_stands_per_si_bin: int | None = None
vdyp_sampling_mode: str | int | None = None
vdyp_toe_shift_years: float | None = None
vdyp_two_pass_rebin: bool | None = None
vri_rel_candidates: list[Path] | None = None
yield_assumptions_path: Path | None = None
class femic.pipeline.io.PipelineRunProfile(tsa_list=None, strata_list=None, resume=False, dry_run=False, verbose=False, skip_checks=False, debug_rows=None, run_id=None, log_dir=None, boundary_path=None, boundary_layer=None, boundary_code=None, strat_bec_grouping=None, strat_species_combo_count=None, strat_include_tm_species2_for_single=None, strat_top_area_coverage=None, strat_target_nstrata=None, tipsy_vdyp_ylim=None, vdyp_sampling_mode=None, vdyp_two_pass_rebin=None, vdyp_min_stands_per_si_bin=None, vdyp_toe_shift_years=None, vdyp_force_tail_blend=None, vdyp_enable_late_gate_rescue=None, managed_curve_mode=None, managed_curve_x_scale=None, managed_curve_y_scale=None, managed_curve_truncate_at_culm=None, managed_curve_max_age=None, yield_assumptions_path=None, vri_rel_candidates=None, vdyp_input_rel_candidates=None)[source]

Bases: object

Config-file driven run profile for selecting TSAs/strata and mode flags.

Parameters:

  • tsa_list (list[str] | None)

  • strata_list (list[str] | None)

  • resume (bool)

  • dry_run (bool)

  • verbose (bool)

  • skip_checks (bool)

  • debug_rows (int | None)

  • run_id (str | None)

  • log_dir (Path | None)

  • boundary_path (Path | None)

  • boundary_layer (str | None)

  • boundary_code (str | None)

  • strat_bec_grouping (str | None)

  • strat_species_combo_count (int | None)

  • strat_include_tm_species2_for_single (bool | None)

  • strat_top_area_coverage (float | None)

  • strat_target_nstrata (int | None)

  • tipsy_vdyp_ylim (tuple[float, float] | None)

  • vdyp_sampling_mode (str | int | None)

  • vdyp_two_pass_rebin (bool | None)

  • vdyp_min_stands_per_si_bin (int | None)

  • vdyp_toe_shift_years (float | None)

  • vdyp_force_tail_blend (bool | None)

  • vdyp_enable_late_gate_rescue (bool | None)

  • managed_curve_mode (str | None)

  • managed_curve_x_scale (float | None)

  • managed_curve_y_scale (float | None)

  • managed_curve_truncate_at_culm (bool | None)

  • managed_curve_max_age (int | None)

  • yield_assumptions_path (Path | None)

  • vri_rel_candidates (list[Path] | None)

  • vdyp_input_rel_candidates (list[Path] | None)

boundary_code: str | None = None
boundary_layer: str | None = None
boundary_path: Path | None = None
debug_rows: int | None = None
dry_run: bool = False
log_dir: Path | None = None
managed_curve_max_age: int | None = None
managed_curve_mode: str | None = None
managed_curve_truncate_at_culm: bool | None = None
managed_curve_x_scale: float | None = None
managed_curve_y_scale: float | None = None
resume: bool = False
run_id: str | None = None
skip_checks: bool = False
strat_bec_grouping: str | None = None
strat_include_tm_species2_for_single: bool | None = None
strat_species_combo_count: int | None = None
strat_target_nstrata: int | None = None
strat_top_area_coverage: float | None = None
strata_list: list[str] | None = None
tipsy_vdyp_ylim: tuple[float, float] | None = None
tsa_list: list[str] | None = None
vdyp_enable_late_gate_rescue: bool | None = None
vdyp_force_tail_blend: bool | None = None
vdyp_input_rel_candidates: list[Path] | None = None
vdyp_min_stands_per_si_bin: int | None = None
vdyp_sampling_mode: str | int | None = None
vdyp_toe_shift_years: float | None = None
vdyp_two_pass_rebin: bool | None = None
verbose: bool = False
vri_rel_candidates: list[Path] | None = None
yield_assumptions_path: Path | None = None
class femic.pipeline.io.RunPaths(repo_root, script_path, log_dir)[source]

Bases: object

Resolved filesystem roots used by the legacy workflow wrapper.

Parameters:

  • repo_root (Path)

  • script_path (Path)

  • log_dir (Path)

log_dir: Path
repo_root: Path
script_path: Path
femic.pipeline.io.build_legacy_data_artifact_paths(*, output_root='data')[source]

Build legacy 00_data-prep artifact path payload under one data root.

Parameters:

output_root (str | Path)

Return type:

LegacyDataArtifactPaths

femic.pipeline.io.build_legacy_execution_plan(*, run_config, script_path, python_executable, base_env)[source]

Resolve all command/env/path details needed to execute the legacy script.

Parameters:

  • run_config (PipelineRunConfig)

  • script_path (Path)

  • python_executable (str)

  • base_env (Mapping[str, str])

Return type:

LegacyExecutionPlan

femic.pipeline.io.build_pipeline_run_config(*, tsa_list, resume, debug_rows=None, run_id=None, log_dir=None, output_root=PosixPath('outputs'), run_config_path=None, run_config_sha256=None, boundary_path=None, boundary_layer=None, boundary_code=None, strat_bec_grouping=None, strat_species_combo_count=None, strat_include_tm_species2_for_single=None, strat_top_area_coverage=None, strat_target_nstrata=None, tipsy_vdyp_ylim=None, vdyp_sampling_mode=None, vdyp_two_pass_rebin=None, vdyp_min_stands_per_si_bin=None, vdyp_toe_shift_years=None, vdyp_force_tail_blend=None, vdyp_enable_late_gate_rescue=None, managed_curve_mode=None, managed_curve_x_scale=None, managed_curve_y_scale=None, managed_curve_truncate_at_culm=None, managed_curve_max_age=None, yield_assumptions_path=None, vri_rel_candidates=None, vdyp_input_rel_candidates=None, instance_root=None)[source]

Create normalized pipeline run configuration from CLI inputs.

Parameters:

  • tsa_list (Iterable[str] | None)

  • resume (bool)

  • debug_rows (int | None)

  • run_id (str | None)

  • log_dir (Path | None)

  • output_root (Path)

  • run_config_path (Path | None)

  • run_config_sha256 (str | None)

  • boundary_path (Path | None)

  • boundary_layer (str | None)

  • boundary_code (str | None)

  • strat_bec_grouping (str | None)

  • strat_species_combo_count (int | None)

  • strat_include_tm_species2_for_single (bool | None)

  • strat_top_area_coverage (float | None)

  • strat_target_nstrata (int | None)

  • tipsy_vdyp_ylim (tuple[float, float] | None)

  • vdyp_sampling_mode (str | int | None)

  • vdyp_two_pass_rebin (bool | None)

  • vdyp_min_stands_per_si_bin (int | None)

  • vdyp_toe_shift_years (float | None)

  • vdyp_force_tail_blend (bool | None)

  • vdyp_enable_late_gate_rescue (bool | None)

  • managed_curve_mode (str | None)

  • managed_curve_x_scale (float | None)

  • managed_curve_y_scale (float | None)

  • managed_curve_truncate_at_culm (bool | None)

  • managed_curve_max_age (int | None)

  • yield_assumptions_path (Path | None)

  • vri_rel_candidates (Sequence[str | Path] | None)

  • vdyp_input_rel_candidates (Sequence[str | Path] | None)

  • instance_root (Path | None)

Return type:

PipelineRunConfig

femic.pipeline.io.build_ria_vri_checkpoint_paths(*, output_root='data', count=8, stem_prefix='ria_vri_vclr1p_checkpoint', suffix='.feather')[source]

Build ordered legacy VRI checkpoint artifact paths.

Parameters:

  • output_root (str | Path)

  • count (int)

  • stem_prefix (str)

  • suffix (str)

Return type:

dict[int, Path]

femic.pipeline.io.discover_git_worktree_root(path)[source]

Return the nearest enclosing git worktree root for a path, if any.

Parameters:

path (str | Path)

Return type:

Path | None

femic.pipeline.io.file_sha256(path)[source]

Return SHA256 hex digest for file contents.

Parameters:

path (Path)

Return type:

str

femic.pipeline.io.is_windows_annex_pointer_stub(path, *, os_name=None, max_pointer_bytes=4096)[source]

Return True when a Windows worktree file still looks like an annex pointer stub.

Parameters:

  • path (str | Path)

  • os_name (str | None)

  • max_pointer_bytes (int)

Return type:

bool

femic.pipeline.io.load_default_tsa_list(config_path=PosixPath('config/dev.toml'))[source]

Load default TSA list from a dev-facing TOML config file.

Parameters:

config_path (Path)

Return type:

list[str]

femic.pipeline.io.load_pipeline_run_profile(config_path)[source]

Load YAML/JSON run profile used to seed CLI options.

Parameters:

config_path (Path)

Return type:

PipelineRunProfile

femic.pipeline.io.materialize_annex_artifact_path(path, *, subprocess_run=None)[source]

Run git annex get for a tracked worktree path and return a readable payload path.

Parameters:

  • path (str | Path)

  • subprocess_run (Callable[[...], CompletedProcess[str]] | None)

Return type:

Path | None

femic.pipeline.io.normalize_tsa_list(tsa_list, *, default_tsa_list=None)[source]

Return zero-padded TSA codes, defaulting to configured dev defaults.

Parameters:

  • tsa_list (Iterable[str] | None)

  • default_tsa_list (Iterable[str] | None)

Return type:

list[str]

femic.pipeline.io.resolve_effective_run_options(*, tsa_list, resume, dry_run, verbose, skip_checks, debug_rows, run_id, log_dir, profile)[source]

Merge CLI run values with profile defaults and normalize for execution.

Parameters:

  • tsa_list (list[str] | None)

  • resume (bool)

  • dry_run (bool)

  • verbose (bool)

  • skip_checks (bool)

  • debug_rows (int | None)

  • run_id (str | None)

  • log_dir (Path)

  • profile (PipelineRunProfile | None)

Return type:

EffectiveRunOptions

femic.pipeline.io.resolve_legacy_external_data_paths(*, repo_root, env_override=None, required_vri_rel=None, vri_rel_candidates=None, vdyp_input_rel_candidates=None, tsa_boundaries_rel='bc/tsa/FADM_TSA.gdb', siteprod_rel_candidates=None)[source]

Resolve legacy external data root + canonical VRI/TSA source paths.

Parameters:

  • repo_root (str | Path)

  • env_override (str | None)

  • required_vri_rel (str | Path | None)

  • vri_rel_candidates (Sequence[str | Path] | None)

  • vdyp_input_rel_candidates (Sequence[str | Path] | None)

  • tsa_boundaries_rel (str | Path)

  • siteprod_rel_candidates (Sequence[str | Path] | None)

Return type:

LegacyExternalDataPaths

femic.pipeline.io.resolve_legacy_siteprod_artifacts(*, legacy_data_paths, external_data_paths)[source]

Prefer canonical pre-stacked SiteProd artifacts when both TIFF + band map exist.

Parameters:

  • legacy_data_paths (LegacyDataArtifactPaths)

  • external_data_paths (LegacyExternalDataPaths)

Return type:

LegacySiteProdArtifacts

femic.pipeline.io.resolve_legacy_thlb_raster_path(*, legacy_data_paths, external_data_paths, exists_fn=None)[source]

Resolve THLB raster path with external-data fallback for instance clones.

Parameters:

  • legacy_data_paths (LegacyDataArtifactPaths)

  • external_data_paths (LegacyExternalDataPaths)

  • exists_fn (Callable[[Path], bool] | None)

Return type:

Path

femic.pipeline.io.resolve_run_paths(*, script_path, instance_root=None, log_dir=None)[source]

Resolve canonical script/repo/log paths for a pipeline run invocation.

Parameters:

  • script_path (Path)

  • instance_root (Path | None)

  • log_dir (Path | None)

Return type:

RunPaths

femic.pipeline.io.resolve_windows_annex_pointer_payload_path(path, *, os_name=None, max_pointer_bytes=4096)[source]

Resolve Windows git-annex pointer stubs to readable payload paths when possible.

Parameters:

  • path (str | Path)

  • os_name (str | None)

  • max_pointer_bytes (int)

Return type:

Path