femic.pipeline.vdyp_stage Module

The femic.pipeline.vdyp_stage module owns the heaviest part of FEMIC’s Stage 01a compile path. It is the seam that turns prepared strata/sample-table inputs into external VDYP batch runs, per-stratum bootstrap results, smoothed yield curves, and the diagnostic artifacts operators inspect before handing the workflow off to BatchTIPSY.

If you are tracing why Stage 01a produced the wrong VDYP curves, why a host cannot launch the legacy VDYP runtime, or why curve-smoothing diagnostics look wrong, this is the first module to read. In practice it owns:

  • loading or caching the VDYP polygon/layer tables used as runtime input

  • launching the external VDYP console binary with local temp files

  • handling per-stratum sampling, cache reuse, and bootstrap orchestration

  • translating raw VDYP tables into smoothed L/M/H curve results

  • emitting the JSONL/text log artifacts that make Stage 01a debuggable

Start Here If…

Use this page first if you are trying to:

  • debug a Stage 01a failure before the BTC/BatchTIPSY boundary

  • understand why a host cannot find VDYP7Console.exe, vdyp_params-landp, wine, or the local vdyp_io/VDYP_CFG runtime assets

  • trace how FEMIC maps sample-table feature IDs to VDYP polygon output tables

  • investigate suspicious vdyp_fitdiag_*.png or tipsy_vdyp_*.png plots

  • work out whether a bug belongs in this module versus femic.pipeline.vdyp_io, femic.pipeline.vdyp_logging, or femic.pipeline.vdyp_sampling

Typical maintenance path:

  1. Start with run_vdyp_for_stratum() to see the single-stratum execution contract.

  2. Drop into execute_vdyp_batch() if the issue looks like external process launch, temp-file handling, or output import.

  3. Jump to execute_bootstrap_vdyp_runs() and load_or_build_vdyp_results_tsa() if the issue is about multi-stratum orchestration or cache reuse.

  4. Finish with execute_curve_smoothing_runs() and fit_stratum_curves() if the failure is visible in smoothed curves or downstream TIPSY overlays.

Typical Usage

The common call pattern is to let higher-level orchestration prepare the inputs and then pass one FMU/code runtime payload into the Stage 01a seam through the legacy tsa contract:

from femic.pipeline.legacy_runtime import build_legacy_01a_runtime_config
from femic.pipeline.vdyp_stage import load_or_build_vdyp_results_tsa

runtime_config = build_legacy_01a_runtime_config(
    tsa_code="08",
    resume_effective=True,
    force_run_vdyp=False,
    kwarg_overrides_for_tsa=None,
    vdyp_results_pickle_path="data/vdyp_results.pkl",
    vdyp_input_pandl_path="data/vdyp_input_pandl.feather",
    vdyp_ply_feather_path="data/vdyp_ply.feather",
    vdyp_lyr_feather_path="data/vdyp_lyr.feather",
    tipsy_params_columns=[],
    tipsy_params_path_prefix="data/tipsy_params_tsa",
    vdyp_results_tsa_pickle_path_prefix="data/vdyp_prep-tsa",
    vdyp_curves_smooth_tsa_feather_path_prefix="data/vdyp_curves_smooth-tsa",
)

# Higher-level callers then dispatch the selected FMU/code run through the
# Stage 01a seam. The payload still uses legacy ``tsa`` field names.

How This Fits Into The Pipeline

This module sits inside the Stage 01a compile flow described in Stage 01a: Strata, VDYP Curves, and TIPSY Input Generation.

At a high level, the owning sequence is:

  1. load prepared VDYP polygon/layer inputs and optional feather caches

  2. run external VDYP batches for one stratum or a sampled subset

  3. persist run logs and optional cached results for later reuse

  4. smooth and quality-gate the resulting curves into the surfaces consumed by downstream managed-curve/TIPSY steps

That means this module is a boundary layer, not just a math helper. It owns the handoff between FEMIC’s Python orchestration and the external proprietary VDYP runtime, then bridges the raw outputs back into FEMIC’s internal curve-fitting and diagnostics flow.

Main Sub-Flows

The most important sub-flows in this module are:

  • Input loading and cache hydration load_vdyp_input_tables() reads the PandL source plus feather caches and normalizes the polygon/layer tables used for later batch runs.

  • Single-batch execution execute_vdyp_batch() writes temp ply/lyr CSVs plus raw .out/.err spill under vdyp_io/scratch/, builds the external command line, captures stdout/stderr, and imports the resulting VDYP tables.

  • Per-stratum orchestration run_vdyp_for_stratum() resolves runtime assets, log paths, sampling behavior, and feature-ID mapping before dispatching one or more batches.

  • Bootstrap execution and cache reuse execute_bootstrap_vdyp_runs(), build_bootstrap_vdyp_results_runner(), and load_or_build_vdyp_results_tsa() control the per-stratum/per-SI execution loop and pickle-backed reuse of previously computed results.

  • Curve fitting and smoothing fit_stratum_curves(), execute_curve_smoothing_runs(), and build_smoothed_curve_table() turn raw VDYP output tables into the smoothed curves and diagnostics the rest of Stage 01a expects.

Key Entry Surfaces

The highest-value entrypoints in this module are:

  • load_vdyp_input_tables() Read or rebuild the polygon/layer tables that seed all later VDYP work.

  • run_vdyp_for_stratum() The best single entrypoint for understanding one stratum’s runtime contract.

  • execute_vdyp_batch() The external process seam where temp files, subprocess launch, and parse failures become visible.

  • execute_bootstrap_vdyp_runs() Multi-stratum orchestration across L/M/H site-index buckets.

  • load_or_build_vdyp_results_tsa() Reuse or rebuild pickled per-FMU/code VDYP results through the legacy tsa cache naming seam.

  • execute_curve_smoothing_runs() Convert raw batch outputs into smoothed curve products and fit diagnostics.

The small dataclasses near the top of the module are also worth reading because they make the main payload contracts explicit:

  • VdypBatchExecutionDependencies

  • VdypBatchTempArtifacts

  • VdypRunEventCounts

  • StratumFitRunConfig

  • CurveSmoothingPlotConfig

  • SmoothedCurveResult

Runtime Contracts And Artifacts

The most important runtime assumptions in this module are:

  • the external VDYP executable must be available, usually at VDYP7/VDYP7/VDYP7Console.exe relative to FEMIC_SOURCE_ROOT unless the caller passes an explicit path

  • the VDYP params file must exist, usually vdyp_params-landp

  • non-Windows hosts need wine available in PATH before VDYP execution

  • local runtime assets under vdyp_io/VDYP_CFG and vdyp_io/VDYP.INI must exist or be copyable from FEMIC_SOURCE_ROOT

  • optional environment overrides include FEMIC_SOURCE_ROOT, FEMIC_VDYP_CFG_DIR, and FEMIC_SAMPLING_SEED

The main artifacts this module writes or updates are:

  • temp batch inputs/outputs under vdyp_io/scratch/ for each subprocess run

  • per-run JSONL/text logs via femic.pipeline.vdyp_logging

  • stdout/stderr capture files for the external VDYP runtime

  • pickle caches for combined or per-FMU/code VDYP results

  • smoothed-curve tables and the diagnostic plots reviewed during Stage 01a

Failure Seams To Watch

The common failure boundaries in this module are:

  • missing host prerequisites wine absent on Linux/macOS, missing VDYP executable, or missing params file will fail before any batch run starts.

  • runtime asset drift If vdyp_io/VDYP_CFG or VDYP.INI is absent and FEMIC_SOURCE_ROOT does not point to a valid source tree, the external run will be misconfigured.

  • output parse failures execute_vdyp_batch() records parse-error events when the subprocess runs but the imported tables are missing, malformed, or empty.

  • feature-ID reconciliation issues run_vdyp_for_stratum() contains non-trivial mapping logic from source feature IDs to VDYP output tables using MAP_ID and polygon identifiers; this is a common place for edge-case mismatches.

  • sampling and fit-quality surprises auto sampling, cache reuse, or later fit-quality gates can produce unexpected partial results even when the external batch run itself succeeds.

Cross-References

Guides and references that pair especially closely with this module:

Related API pages:

VDYP execution stage helpers for legacy notebook migration.

class femic.pipeline.vdyp_stage.CurveSmoothingPlotConfig(plot, figsize, palette, palette_flavours, alphas, xlim, ylim)[source]

Bases: object

Plot defaults for legacy VDYP curve-smoothing overlays.

Parameters:

  • plot (bool)

  • figsize (tuple[float, float])

  • palette (tuple[Any, ...])

  • palette_flavours (tuple[str, ...])

  • alphas (tuple[float, ...])

  • xlim (tuple[float, float])

  • ylim (tuple[float, float])

alphas: tuple[float, ...]
figsize: tuple[float, float]
palette: tuple[Any, ...]
palette_flavours: tuple[str, ...]
plot: bool
xlim: tuple[float, float]
ylim: tuple[float, float]
class femic.pipeline.vdyp_stage.SmoothedCurveResult(stratumi, stratum_code, si_level, x, y, vdyp_out)[source]

Bases: object

One smoothed curve result for a stratum/SI combination.

Parameters:

  • stratumi (int)

  • stratum_code (str)

  • si_level (str)

  • x (Sequence[float])

  • y (Sequence[float])

  • vdyp_out (dict[Any, Any])

si_level: str
stratum_code: str
stratumi: int
vdyp_out: dict[Any, Any]
x: Sequence[float]
y: Sequence[float]
class femic.pipeline.vdyp_stage.StratumFitRunConfig(fit_rawdata, min_stands_per_si_bin, min_age, agg_type, plot, verbose, figsize, ylim, xlim)[source]

Bases: object

Defaults for pre-VDYP stratum curve-fit compilation runs.

Parameters:

  • fit_rawdata (bool)

  • min_stands_per_si_bin (int)

  • min_age (int)

  • agg_type (str)

  • plot (bool)

  • verbose (bool)

  • figsize (tuple[float, float])

  • ylim (tuple[float, float])

  • xlim (tuple[float, float])

agg_type: str
figsize: tuple[float, float]
fit_rawdata: bool
min_age: int
min_stands_per_si_bin: int
plot: bool
verbose: bool
xlim: tuple[float, float]
ylim: tuple[float, float]
class femic.pipeline.vdyp_stage.VdypBatchExecutionDependencies(write_vdyp_infiles, import_vdyp_tables, append_jsonl, append_text, build_stream_header, build_stream_log_block, subprocess_run)[source]

Bases: object

Resolved callable dependencies used by execute_vdyp_batch(…).

Parameters:

  • write_vdyp_infiles (Callable[[...], None])

  • import_vdyp_tables (Callable[[str], dict[Any, Any]])

  • append_jsonl (Callable[[str | Path, Any], None])

  • append_text (Callable[[str | Path, str], None])

  • build_stream_header (Callable[[...], str])

  • build_stream_log_block (Callable[[...], str])

  • subprocess_run (Callable[[...], Any])

append_jsonl: Callable[[str | Path, Any], None]
append_text: Callable[[str | Path, str], None]
build_stream_header: Callable[[...], str]
build_stream_log_block: Callable[[...], str]
import_vdyp_tables: Callable[[str], dict[Any, Any]]
subprocess_run: Callable[[...], Any]
write_vdyp_infiles: Callable[[...], None]
class femic.pipeline.vdyp_stage.VdypBatchTempArtifacts(vdyp_ply_csv, vdyp_lyr_csv, vdyp_out_txt, vdyp_err_txt, out_path, err_path)[source]

Bases: object

Resolved temp-file names and absolute paths for one VDYP batch run.

Parameters:

  • vdyp_ply_csv (str)

  • vdyp_lyr_csv (str)

  • vdyp_out_txt (str)

  • vdyp_err_txt (str)

  • out_path (Path)

  • err_path (Path)

err_path: Path
out_path: Path
vdyp_err_txt: str
vdyp_lyr_csv: str
vdyp_out_txt: str
vdyp_ply_csv: str
class femic.pipeline.vdyp_stage.VdypRunEventCounts(feature_count, cache_hits, ply_rows, lyr_rows)[source]

Bases: object

Normalized integer count fields shared by VDYP run events/headers.

Parameters:

  • feature_count (int)

  • cache_hits (int)

  • ply_rows (int)

  • lyr_rows (int)

cache_hits: int
feature_count: int
lyr_rows: int
ply_rows: int
femic.pipeline.vdyp_stage.build_bootstrap_vdyp_results_runner(*, tsa, run_id, results_for_tsa, si_levels, vdyp_run_events_path, append_jsonl_fn, run_vdyp_fn, vdyp_out_cache=None, nsamples_mode='auto', sampling_seed_base=None, execute_bootstrap_vdyp_runs_fn=<function execute_bootstrap_vdyp_runs>)[source]

Build a zero-arg bootstrap callback for load_or_build_vdyp_results_tsa(…).

Parameters:

  • tsa (str)

  • run_id (str)

  • results_for_tsa (Sequence[tuple[int, str, Any]])

  • si_levels (Sequence[str])

  • vdyp_run_events_path (str | Path)

  • append_jsonl_fn (Callable[[str | Path, Any], None])

  • run_vdyp_fn (Callable[[...], dict[Any, Any]])

  • vdyp_out_cache (dict[Any, Any] | None)

  • nsamples_mode (str | int)

  • sampling_seed_base (int | None)

  • execute_bootstrap_vdyp_runs_fn (Callable[[...], dict[int, dict[str, dict[Any, Any]]]])

Return type:

Callable[[], dict[int, dict[str, dict[Any, Any]]]]

femic.pipeline.vdyp_stage.build_curve_fit_adapter(*, curve_fit_impl=None, np_module=None)[source]

Build legacy-compatible curve_fit wrapper handling maxfev/max_nfev.

Parameters:

  • curve_fit_impl (Callable[[...], Any] | None)

  • np_module (Any | None)

Return type:

Callable[[…], Any]

femic.pipeline.vdyp_stage.build_curve_smoothing_plot_config(*, sns_module, plot=True, figsize=(8, 6), palette_name='Greens', palette_size=3, palette_flavours=('RdPu', 'Blues', 'Greens', 'Greys'), alphas=(1.0, 0.5, 0.1), xlim=(0, 300), ylim=(0, 600))[source]

Build and apply legacy curve-smoothing plot defaults.

Parameters:

  • sns_module (Any)

  • plot (bool)

  • figsize (tuple[float, float])

  • palette_name (str)

  • palette_size (int)

  • palette_flavours (Sequence[str])

  • alphas (Sequence[float])

  • xlim (tuple[float, float])

  • ylim (tuple[float, float])

Return type:

CurveSmoothingPlotConfig

femic.pipeline.vdyp_stage.build_fit_stratum_curves_runner(*, f_table, fit_func, fit_func_bounds_func, strata_df, stratum_si_stats, species_list, curve_fit_fn, fit_rawdata, min_stands_per_si_bin=25, min_age, agg_type, plot, figsize, verbose, ylim, xlim, np_module, pd_module, sns_module, plt_module, message_fn=<built-in function print>, fit_stratum_curves_fn=<function fit_stratum_curves>)[source]

Build a compile-one callback that runs fit_stratum_curves(…) for one stratum.

Parameters:

  • f_table (Any)

  • fit_func (Callable[[...], Any])

  • fit_func_bounds_func (Callable[[...], Any])

  • strata_df (Any)

  • stratum_si_stats (Any)

  • species_list (Sequence[str])

  • curve_fit_fn (Callable[[...], Any])

  • fit_rawdata (bool)

  • min_stands_per_si_bin (int)

  • min_age (int)

  • agg_type (str)

  • plot (bool)

  • figsize (tuple[int, int])

  • verbose (bool)

  • ylim (Sequence[float])

  • xlim (Sequence[float])

  • np_module (Any)

  • pd_module (Any)

  • sns_module (Any)

  • plt_module (Any)

  • message_fn (Callable[[...], Any])

  • fit_stratum_curves_fn (Callable[[...], Any])

Return type:

Callable[[int, str], Any]

femic.pipeline.vdyp_stage.build_run_vdyp_for_stratum_runner(*, tsa, run_id, vdyp_ply, vdyp_lyr, rc_len, curve_fit_fn, fit_func, fit_func_bounds_func, append_jsonl_fn=None, vdyp_log_path=None, vdyp_stdout_log_path=None, vdyp_stderr_log_path=None, sampling_seed_base=None, run_vdyp_for_stratum_fn=<function run_vdyp_for_stratum>)[source]

Build a per-TSA VDYP runner callable for bootstrap dispatch helpers.

Parameters:

  • tsa (str)

  • run_id (str)

  • vdyp_ply (Any)

  • vdyp_lyr (Any)

  • rc_len (int)

  • curve_fit_fn (Callable[[...], Any])

  • fit_func (Callable[[...], Any])

  • fit_func_bounds_func (Callable[[...], Any])

  • append_jsonl_fn (Callable[[str | Path, Any], None] | None)

  • vdyp_log_path (str | Path | None)

  • vdyp_stdout_log_path (str | Path | None)

  • vdyp_stderr_log_path (str | Path | None)

  • sampling_seed_base (int | None)

  • run_vdyp_for_stratum_fn (Callable[[...], dict[Any, Any]])

Return type:

Callable[[…], dict[Any, Any]]

femic.pipeline.vdyp_stage.build_smoothed_curve_table(*, smoothed_runs, pd_module, output_path=None)[source]

Build and optionally persist the smoothed VDYP curve table.

Parameters:

  • smoothed_runs (Sequence[SmoothedCurveResult])

  • pd_module (Any)

  • output_path (str | Path | None)

Return type:

Any

femic.pipeline.vdyp_stage.build_stratum_fit_run_config(*, fit_rawdata=True, min_stands_per_si_bin=25, min_age=30, agg_type='median', plot=False, verbose=False, figsize=(8, 16), ylim=(0, 600), xlim=(0, 400))[source]

Build defaults for pre-VDYP stratum fit stage settings.

Parameters:

  • fit_rawdata (bool)

  • min_stands_per_si_bin (int)

  • min_age (int)

  • agg_type (str)

  • plot (bool)

  • verbose (bool)

  • figsize (tuple[float, float])

  • ylim (tuple[float, float])

  • xlim (tuple[float, float])

Return type:

StratumFitRunConfig

femic.pipeline.vdyp_stage.build_vdyp_batch_command(*, vdyp_binpath, vdyp_params_infile, vdyp_io_dir, vdyp_ply_csv, vdyp_lyr_csv, vdyp_out_txt, vdyp_err_txt, vdyp_cfg_dir=None)[source]

Build legacy VDYP command text used for execution and logging metadata.

Parameters:

  • vdyp_binpath (str)

  • vdyp_params_infile (str)

  • vdyp_io_dir (str | Path)

  • vdyp_ply_csv (str)

  • vdyp_lyr_csv (str)

  • vdyp_out_txt (str)

  • vdyp_err_txt (str)

  • vdyp_cfg_dir (str | Path | None)

Return type:

str

femic.pipeline.vdyp_stage.build_vdyp_run_context(*, base_context=None, tsa=None, run_id=None, vdyp_stdout_log_path=None, vdyp_stderr_log_path=None, vdyp_binpath=None, vdyp_params=None)[source]

Build VDYP run context payload while preserving caller-provided values.

Parameters:

  • base_context (Mapping[str, Any] | None)

  • tsa (str | None)

  • run_id (str | None)

  • vdyp_stdout_log_path (str | Path | None)

  • vdyp_stderr_log_path (str | Path | None)

  • vdyp_binpath (str | Path | None)

  • vdyp_params (str | Path | None)

Return type:

dict[str, Any]

femic.pipeline.vdyp_stage.build_vdyp_run_event(*, status, phase, counts, cmd, context, **extra_fields)[source]

Build one VDYP run event payload with shared base fields.

Parameters:

  • status (str)

  • phase (str)

  • counts (VdypRunEventCounts)

  • cmd (str)

  • context (Mapping[str, Any])

  • extra_fields (Any)

Return type:

dict[str, Any]

femic.pipeline.vdyp_stage.collect_vdyp_batch_run_metadata(*, result, out_path, err_path, run_started, time_fn=<built-in function time>)[source]

Collect subprocess/file metadata shared by parse-error and success events.

Parameters:

  • result (Any)

  • out_path (str | Path)

  • err_path (str | Path)

  • run_started (float)

  • time_fn (Callable[[], float])

Return type:

dict[str, Any]

femic.pipeline.vdyp_stage.compile_strata_fit_results(*, strata_df, compile_one_fn, message_fn=<built-in function print>)[source]

Compile fit payloads for each selected stratum index/code pair.

Parameters:

  • strata_df (Any)

  • compile_one_fn (Callable[[int, str], Any])

  • message_fn (Callable[[...], Any])

Return type:

list[list[Any]]

femic.pipeline.vdyp_stage.emit_vdyp_run_event(*, append_jsonl_fn, vdyp_log_path, status, phase, counts, cmd, context, **extra_fields)[source]

Emit one VDYP run event record through the provided append sink.

Parameters:

  • append_jsonl_fn (Callable[[str | Path, Any], None])

  • vdyp_log_path (str | Path)

  • status (str)

  • phase (str)

  • counts (VdypRunEventCounts)

  • cmd (str)

  • context (Mapping[str, Any])

  • extra_fields (Any)

Return type:

None

femic.pipeline.vdyp_stage.ensure_local_vdyp_runtime_assets(*, vdyp_io_dir, source_root, copytree_fn=<function copytree>, copy2_fn=<function copy2>)[source]

Ensure legacy relative VDYP runtime assets exist under local vdyp_io/.

Parameters:

  • vdyp_io_dir (str | Path)

  • source_root (str | Path | None)

  • copytree_fn (Callable[[...], Any])

  • copy2_fn (Callable[[...], Any])

Return type:

None

femic.pipeline.vdyp_stage.execute_bootstrap_vdyp_runs(*, tsa, run_id, results_for_tsa, si_levels, vdyp_run_events_path, append_jsonl_fn, run_vdyp_fn, vdyp_out_cache=None, nsamples_mode='auto', verbose=True, half_rel_ci=0.01, ipp_mode=None, nsamples_c1=0.05, sampling_seed_base=None)[source]

Execute bootstrap VDYP runs across stratum/SI combinations.

Parameters:

  • tsa (str)

  • run_id (str)

  • results_for_tsa (Sequence[tuple[int, str, Any]])

  • si_levels (Sequence[str])

  • vdyp_run_events_path (str | Path)

  • append_jsonl_fn (Callable[[str | Path, Any], None])

  • run_vdyp_fn (Callable[[...], dict[Any, Any]])

  • vdyp_out_cache (dict[Any, Any] | None)

  • nsamples_mode (str | int)

  • verbose (bool)

  • half_rel_ci (float)

  • ipp_mode (str | None)

  • nsamples_c1 (float)

  • sampling_seed_base (int | None)

Return type:

dict[int, dict[str, dict[Any, Any]]]

femic.pipeline.vdyp_stage.execute_curve_smoothing_runs(*, tsa, run_id, results_for_tsa, si_levels, vdyp_results_for_tsa, kwarg_overrides_for_tsa, process_vdyp_out_fn, append_jsonl_fn, vdyp_curve_events_path, curve_fit_fn, body_fit_func, body_fit_func_bounds_func, toe_fit_func, toe_fit_func_bounds_func, use_au_first_growth_selector=False, force_tail_blend_candidate=False, enable_late_gate_rescue=True, message_fn=<built-in function print>)[source]

Build smoothed VDYP curves for each stratum/SI combination.

Parameters:

  • tsa (str)

  • run_id (str)

  • results_for_tsa (Sequence[tuple[int, str, Any]])

  • si_levels (Sequence[str])

  • vdyp_results_for_tsa (Mapping[int, Mapping[str, dict[Any, Any]]])

  • kwarg_overrides_for_tsa (Mapping[tuple[str, str], Mapping[str, Any]])

  • process_vdyp_out_fn (Callable[[...], tuple[Sequence[float], Sequence[float]]])

  • append_jsonl_fn (Callable[[str | Path, Any], None])

  • vdyp_curve_events_path (str | Path)

  • curve_fit_fn (Callable[[...], Any])

  • body_fit_func (Callable[[...], Any])

  • body_fit_func_bounds_func (Callable[[...], Any])

  • toe_fit_func (Callable[[...], Any])

  • toe_fit_func_bounds_func (Callable[[...], Any])

  • use_au_first_growth_selector (bool)

  • force_tail_blend_candidate (bool)

  • enable_late_gate_rescue (bool)

  • message_fn (Callable[[...], Any])

Return type:

list[SmoothedCurveResult]

femic.pipeline.vdyp_stage.execute_vdyp_batch(*, feature_ids, vdyp_ply, vdyp_lyr, vdyp_binpath, vdyp_params_infile, vdyp_io_dirname, vdyp_log_path, vdyp_stdout_log_path, vdyp_stderr_log_path, phase, cache_hits=0, timeout=30, run_id=None, base_context=None, write_vdyp_infiles=None, import_vdyp_tables_fn=None, append_jsonl_fn=None, append_text_fn=None, build_stream_header_fn=None, build_stream_log_block_fn=None, subprocess_run=None)[source]

Run one VDYP batch and return parsed per-feature output tables.

Parameters:

  • feature_ids (Sequence[int])

  • vdyp_ply (Any)

  • vdyp_lyr (Any)

  • vdyp_binpath (str)

  • vdyp_params_infile (str)

  • vdyp_io_dirname (str)

  • vdyp_log_path (str | Path)

  • vdyp_stdout_log_path (str | Path)

  • vdyp_stderr_log_path (str | Path)

  • phase (str)

  • cache_hits (int)

  • timeout (int)

  • run_id (str | None)

  • base_context (Mapping[str, Any] | None)

  • write_vdyp_infiles (Callable[[...], None] | None)

  • import_vdyp_tables_fn (Callable[[str], dict[Any, Any]] | None)

  • append_jsonl_fn (Callable[[str | Path, Any], None] | None)

  • append_text_fn (Callable[[str | Path, str], None] | None)

  • build_stream_header_fn (Callable[[...], str] | None)

  • build_stream_log_block_fn (Callable[[...], str] | None)

  • subprocess_run (Callable[[...], Any] | None)

Return type:

dict[Any, Any]

femic.pipeline.vdyp_stage.fit_stratum_curves(*, f_table, fit_func, fit_func_bounds_func, strata_df, stratum_si_stats, stratumi, species_list, curve_fit_fn, np_module, pd_module, sns_module, plt_module, plot=True, figsize=(6, 12), verbose=False, xlim=(0, 300), ylim=(0, 500), si_levelquants=None, linestyles=None, markers=None, palette_flavours=None, maxfev=100000, min_age=30, max_age=300, max_records=15000, sigma_exponent=1.0, window=10, min_periods=None, center=False, agg_type='median', sv_thresh=0.1, rawdata_alpha=0.05, fitattr_thresh=1.0, fit_rawdata=True, min_stands_per_si_bin=25, debug=False, message_fn=<built-in function print>)[source]

Fit per-SI species curves for one stratum using legacy notebook logic.

Parameters:

  • f_table (Any)

  • fit_func (Callable[[...], Any])

  • fit_func_bounds_func (Callable[[Any], Any])

  • strata_df (Any)

  • stratum_si_stats (Any)

  • stratumi (int)

  • species_list (Sequence[str])

  • curve_fit_fn (Callable[[...], Any])

  • np_module (Any)

  • pd_module (Any)

  • sns_module (Any)

  • plt_module (Any)

  • plot (bool)

  • figsize (tuple[float, float])

  • verbose (bool)

  • xlim (tuple[float, float])

  • ylim (tuple[float, float])

  • si_levelquants (Mapping[str, Sequence[float]] | None)

  • linestyles (Sequence[str] | None)

  • markers (Sequence[str] | None)

  • palette_flavours (Sequence[str] | None)

  • maxfev (int)

  • min_age (int)

  • max_age (int)

  • max_records (int)

  • sigma_exponent (float)

  • window (int)

  • min_periods (int | None)

  • center (bool)

  • agg_type (str)

  • sv_thresh (float)

  • rawdata_alpha (float)

  • fitattr_thresh (float)

  • fit_rawdata (bool)

  • min_stands_per_si_bin (int)

  • debug (bool)

  • message_fn (Callable[[...], Any])

Return type:

dict[str, Any]

femic.pipeline.vdyp_stage.load_or_build_vdyp_results_tsa(*, tsa, force_run_vdyp, vdyp_results_tsa_pickle_path, vdyp_results_pickle_path, run_bootstrap_fn, print_fn=<built-in function print>, load_pickle_fn=<function _default_load_pickle>, dump_pickle_fn=<function _default_dump_pickle>, load_compat_pickle_fn=<function _default_load_compat_pickle>)[source]

Resolve per-TSA VDYP results from cache, combined cache, or fresh bootstrap.

Parameters:

  • tsa (str)

  • force_run_vdyp (bool)

  • vdyp_results_tsa_pickle_path (str | Path)

  • vdyp_results_pickle_path (str | Path)

  • run_bootstrap_fn (Callable[[], dict[int, dict[str, dict[Any, Any]]]])

  • print_fn (Callable[[...], Any])

  • load_pickle_fn (Callable[[str | Path], Any])

  • dump_pickle_fn (Callable[[Any, str | Path], None])

  • load_compat_pickle_fn (Callable[[str | Path], Any])

Return type:

dict[int, dict[str, dict[Any, Any]]]

femic.pipeline.vdyp_stage.load_vdyp_input_tables(*, vdyp_input_pandl_path, vdyp_ply_feather_path, vdyp_lyr_feather_path, read_from_source=False, source_where=None, source_mask=None, source_map_ids=None, source_feature_ids=None, source_map_id_chunk_size=5, source_feature_id_chunk_size=None, gpd_module=None, message_fn=<built-in function print>)[source]

Load VDYP polygon/layer tables from feather cache or source geodatabase.

Parameters:

  • vdyp_input_pandl_path (str | Path)

  • vdyp_ply_feather_path (str | Path)

  • vdyp_lyr_feather_path (str | Path)

  • read_from_source (bool)

  • source_where (str | None)

  • source_mask (Any | None)

  • source_map_ids (Sequence[str] | None)

  • source_feature_ids (Sequence[Any] | None)

  • source_map_id_chunk_size (int | None)

  • source_feature_id_chunk_size (int | None)

  • gpd_module (Any | None)

  • message_fn (Callable[[...], Any])

Return type:

tuple[Any, Any]

femic.pipeline.vdyp_stage.normalize_vdyp_run_event_counts(*, feature_count, cache_hits, ply_rows, lyr_rows)[source]

Normalize run-event count fields to integers in one shared seam.

Parameters:

  • feature_count (Any)

  • cache_hits (Any)

  • ply_rows (Any)

  • lyr_rows (Any)

Return type:

VdypRunEventCounts

femic.pipeline.vdyp_stage.plot_curve_overlays(*, results_for_tsa, si_levels, smoothed_runs, plot, figsize, palette, pd_module, plt_module, dataframe_type, xlim=(0, 300), ylim=(0, 600), message_fn=<built-in function print>)[source]

Render legacy VDYP overlay plots for smoothed curves.

Parameters:

  • results_for_tsa (Sequence[tuple[int, str, Any]])

  • si_levels (Sequence[str])

  • smoothed_runs (Sequence[SmoothedCurveResult])

  • plot (bool)

  • figsize (tuple[float, float])

  • palette (Sequence[Any])

  • pd_module (Any)

  • plt_module (Any)

  • dataframe_type (type)

  • xlim (tuple[float, float])

  • ylim (tuple[float, float])

  • message_fn (Callable[[...], Any])

Return type:

None

femic.pipeline.vdyp_stage.resolve_vdyp_batch_execution_dependencies(*, write_vdyp_infiles, import_vdyp_tables_fn, append_jsonl_fn, append_text_fn, build_stream_header_fn, build_stream_log_block_fn, subprocess_run)[source]

Resolve injected/default callable dependencies for VDYP batch execution.

Parameters:

  • write_vdyp_infiles (Callable[[...], None] | None)

  • import_vdyp_tables_fn (Callable[[str], dict[Any, Any]] | None)

  • append_jsonl_fn (Callable[[str | Path, Any], None] | None)

  • append_text_fn (Callable[[str | Path, str], None] | None)

  • build_stream_header_fn (Callable[[...], str] | None)

  • build_stream_log_block_fn (Callable[[...], str] | None)

  • subprocess_run (Callable[[...], Any] | None)

Return type:

VdypBatchExecutionDependencies

femic.pipeline.vdyp_stage.resolve_vdyp_batch_scratch_dir(vdyp_io_dir)[source]

Return the disposable scratch directory used for raw VDYP batch spill.

Parameters:

vdyp_io_dir (str | Path)

Return type:

Path

femic.pipeline.vdyp_stage.resolve_vdyp_batch_temp_artifacts(*, vdyp_ply_name, vdyp_lyr_name, vdyp_out_name, vdyp_err_name)[source]

Resolve temp-file basenames and full paths for VDYP batch processing.

Parameters:

  • vdyp_ply_name (str)

  • vdyp_lyr_name (str)

  • vdyp_out_name (str)

  • vdyp_err_name (str)

Return type:

VdypBatchTempArtifacts

femic.pipeline.vdyp_stage.run_vdyp_for_stratum(*, sample_table, tsa, run_id, vdyp_ply, vdyp_lyr, rc_len, curve_fit_fn, fit_func, fit_func_bounds_func, nsamples='auto', vdyp_io_dirname='vdyp_io', vdyp_params_infile='vdyp_params-landp', vdyp_binpath='VDYP7/VDYP7/VDYP7Console.exe', nsamples_c1=0.01, nsamples_c2=0.1, verbose=False, confidence=95, half_rel_ci=0.05, min_samples=100, max_samples=640, ipp_mode=None, vdyp_timeout=2.0, vdyp_out_cache=None, sampling_seed=None, vdyp_log_path=None, vdyp_stdout_log_path=None, vdyp_stderr_log_path=None, log_context=None, which_fn=None, build_tsa_vdyp_log_paths_fn=None, append_jsonl_fn=None, append_text_fn=None, execute_vdyp_batch_fn=None, write_vdyp_infiles_fn=None, import_vdyp_tables_fn=None, nsamples_from_curves_fn=None, message_fn=<built-in function print>)[source]

Run VDYP for one stratum sample table with logging and sampling orchestration.

Parameters:

  • sample_table (Any)

  • tsa (str)

  • run_id (str)

  • vdyp_ply (Any)

  • vdyp_lyr (Any)

  • rc_len (int)

  • curve_fit_fn (Callable[[...], Any])

  • fit_func (Callable[[...], Any])

  • fit_func_bounds_func (Callable[[...], Any])

  • nsamples (str | int)

  • vdyp_io_dirname (str)

  • vdyp_params_infile (str)

  • vdyp_binpath (str)

  • nsamples_c1 (float)

  • nsamples_c2 (float)

  • verbose (bool)

  • confidence (float)

  • half_rel_ci (float)

  • min_samples (int)

  • max_samples (int)

  • ipp_mode (str | None)

  • vdyp_timeout (float)

  • vdyp_out_cache (dict[Any, Any] | None)

  • sampling_seed (int | None)

  • vdyp_log_path (str | Path | None)

  • vdyp_stdout_log_path (str | Path | None)

  • vdyp_stderr_log_path (str | Path | None)

  • log_context (Mapping[str, Any] | None)

  • which_fn (Callable[[str], str | None] | None)

  • build_tsa_vdyp_log_paths_fn (Callable[[...], Mapping[str, str | Path]] | None)

  • append_jsonl_fn (Callable[[str | Path, Any], None] | None)

  • append_text_fn (Callable[[str | Path, str], None] | None)

  • execute_vdyp_batch_fn (Callable[[...], dict[Any, Any]] | None)

  • write_vdyp_infiles_fn (Callable[[...], None] | None)

  • import_vdyp_tables_fn (Callable[[str], dict[Any, Any]] | None)

  • nsamples_from_curves_fn (Callable[[...], tuple[int, Any]] | None)

  • message_fn (Callable[[...], Any])

Return type:

dict[Any, Any]

femic.pipeline.vdyp_stage.run_vdyp_sampling(*, sample_table, nsamples, min_samples, max_samples, nsamples_c1, nsamples_c2, confidence, half_rel_ci, ipp_mode, vdyp_timeout, rc_len, verbose, vdyp_out_cache, random_seed, run_batch_fn, nsamples_from_curves_fn, message_fn=<built-in function print>)[source]

Run legacy VDYP sampling flow (auto/all/fixed) for one stratum sample table.

Parameters:

  • sample_table (Any)

  • nsamples (str | int)

  • min_samples (int)

  • max_samples (int)

  • nsamples_c1 (float)

  • nsamples_c2 (float)

  • confidence (float)

  • half_rel_ci (float)

  • ipp_mode (str | None)

  • vdyp_timeout (float)

  • rc_len (int)

  • verbose (bool)

  • vdyp_out_cache (dict[Any, Any] | None)

  • random_seed (int | None)

  • run_batch_fn (Callable[[...], dict[Any, Any]])

  • nsamples_from_curves_fn (Callable[[...], tuple[int, Any]])

  • message_fn (Callable[[...], Any])

Return type:

dict[Any, Any]