femic.site_index Package

The femic.site_index package owns the provenance and reconciliation surface for existing British Columbia site-index products. It reads VRI, VDYP primary-layer, and SIBEC values, joins them at feature/BEC/species grain, and reports differences without fitting a model or changing a curve.

Start Here If…

Use this page first if you are trying to:

  • load the public SIBEC 2013 workbook and 2014 addendum into a tidy table;

  • read VRI SITE_INDEX/EST_SITE_INDEX;

  • read VDYP primary-layer site index;

  • run or extend the femic.site-index.reconciliation.v2 report;

  • report the AU-level TSA SI separately; or

  • understand why VRI and VDYP values are suppressed when species differ.

Typical Usage

from pathlib import Path
from femic.site_index import (
    aggregate_sibec_by_bgc_unit,
    combine_sibec_tables,
    load_sibec_addendum,
    load_sibec_table,
    load_vdyp_site_index,
    load_vri_site_index,
    reconcile_site_index,
    select_sibec_source,
    summarize_reconciliation,
)

vri = load_vri_site_index(Path("data/vri_vclr1p_checkpoint8.feather"))
vdyp = load_vdyp_site_index(Path("data/vdyp_lyr-tsa46.feather"))
sibec_table = combine_sibec_tables(
    load_sibec_table(Path("data/sibec2013approx_final.xlsx")),
    load_sibec_addendum(Path("data/2013sisuaddendum_jul2014.xlsx")),
)
sibec = select_sibec_source(aggregate_sibec_by_bgc_unit(sibec_table))
frame = reconcile_site_index(vri, vdyp, sibec, delta_threshold=2.0)
summary = summarize_reconciliation(frame, delta_threshold=2.0)

Key Entry Surfaces

Cross-References

Site-index provenance and reconciliation helpers.

This package consumes existing BC site-index products:

  • VRI SITE_INDEX and EST_SITE_INDEX per polygon;

  • VDYP primary-layer ESTIMATED_SITE_INDEX; and

  • SIBEC BEC-unit/species estimates.

It does not derive a new site-index model.

exception femic.site_index.AuSiteIndexError[source]

Bases: RuntimeError

Raised when a TSA AU-level site-index table cannot be read.

exception femic.site_index.SibecError[source]

Bases: RuntimeError

Raised when the SIBEC table is missing or malformed.

exception femic.site_index.SiteIndexReconciliationError[source]

Bases: RuntimeError

Raised when reconciliation inputs cannot be joined consistently.

exception femic.site_index.VdypError[source]

Bases: RuntimeError

Raised when a VDYP layer table cannot provide site-index fields.

exception femic.site_index.VriError[source]

Bases: RuntimeError

Raised when a VRI table cannot provide site-index fields.

femic.site_index.aggregate_sibec_by_bgc_unit(table, *, include_source=True)[source]

Aggregate SIBEC site-series rows to BEC-unit/species/source.

Parameters:
  • table (pandas.DataFrame) – Tidy SIBEC table from load_sibec_table() or combine_sibec_tables().

  • include_source (bool, optional) – Keep source_table in the grouping and output. Defaults to True so the 2013 approximation and 2014 addendum remain distinguishable.

Returns:

One row per source, BEC unit, and species with weighted mean SI (weighted by plot count when available, otherwise unweighted), minimum, maximum, mean standard error, site-series count, and total plot count.

Return type:

pandas.DataFrame

femic.site_index.combine_sibec_tables(*tables)[source]

Concatenate tidy SIBEC tables while preserving their source labels.

Parameters:

tables (DataFrame)

Return type:

DataFrame

femic.site_index.compose_bec_unit(zone, subzone, variant)[source]

Compose a BEC unit such as CWHvh3 from VRI fields.

Parameters:
  • zone (object)

  • subzone (object)

  • variant (object)

Return type:

str | None

femic.site_index.load_au_site_index(path)[source]

Read a TSA 03_input table into a long AU/species site-index table.

Parameters:

path (Path) – CSV, Feather, or Parquet TSA input table. The table must contain feature_id and one or more <species>_si columns.

Returns:

One row per AU/species with the AU identifier, BEC zone/subzone, planted/natural leading species, the species SI value, and a leading species flag.

Return type:

pandas.DataFrame

Raises:

AuSiteIndexError – If the table has no feature identifier or no species SI columns.

femic.site_index.load_sibec_addendum(path)[source]

Load the public 2014 SIBEC addendum (ciReportByUnit).

Parameters:

path (Path)

Return type:

DataFrame

femic.site_index.load_sibec_table(path, *, sheet_name=0, source_table='2013_approximation')[source]

Load a SIBEC workbook or CSV into the tidy femic.sibec.v2 table.

Parameters:
  • path (pathlib.Path) – XLSX workbook or CSV export.

  • sheet_name (str or int, optional) – Worksheet for an XLSX file. The public 2013 approximation workbook has its header on the third row.

  • source_table (str, optional) – Provenance label for the rows. Use 2013_approximation for the base workbook and 2014_addendum for the addendum.

Returns:

Tidy SIBEC table with schema_version, source_table, region, BGC unit, site series, site association, species, plot count, mean site index, and standard error.

Return type:

pandas.DataFrame

Raises:

SibecError – If the file has no usable rows or is missing required columns.

femic.site_index.load_vdyp_site_index(path)[source]

Read primary-layer VDYP site index from a Feather, Parquet, or CSV.

Parameters:

path (pathlib.Path) – VDYP layer table with FEATURE_ID, ESTIMATED_SITE_INDEX, and EST_SITE_INDEX_SPECIES_CD. If LAYER_LEVEL_CODE is present, only the primary layer (1) is kept.

Returns:

One row per feature with the VDYP site index and the species the estimate applies to.

Return type:

pandas.DataFrame

Raises:

VdypError – If required columns are missing or no usable rows remain.

femic.site_index.load_vri_site_index(path)[source]

Read VRI site-index fields from a Feather, Parquet, or CSV table.

Parameters:

path (pathlib.Path) – VRI checkpoint or export.

Returns:

One row per VRI feature with BEC unit, canonical species key, VRI SITE_INDEX, EST_SITE_INDEX, and projection attributes.

Return type:

pandas.DataFrame

Raises:

VriError – If a required identifier or site-index column is missing, or no usable rows remain.

femic.site_index.normalise_species(value)[source]

Return the canonical species key for a VRI or SIBEC code.

Parameters:

value (object)

Return type:

str | None

femic.site_index.reconcile_site_index(vri, vdyp, sibec_by_bgc_unit, *, delta_threshold=2.0, min_sibec_plot_count=7)[source]

Join VRI, VDYP, and SIBEC site-index values feature by feature.

Parameters:
Returns:

One row per VRI feature with source values, pairwise deltas, coverage status, and the documented reference value/source. The VDYP value is always the current curve input; the reference value is a comparison value and is not applied automatically.

Return type:

pandas.DataFrame

femic.site_index.select_sibec_source(table, *, preference=('2014_addendum', '2013_approximation'))[source]

Select one explicit SIBEC source per BEC-unit/species.

The addendum is preferred by default when it contains the key; the 2013 approximation is the fallback. This is a declared preference, not a silent collapse: the selected source is written to si_sibec_source.

Parameters:
  • table (DataFrame)

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

Return type:

DataFrame

femic.site_index.summarize_au_site_index(table)[source]

Return a JSON-serializable AU-level site-index summary.

Parameters:

table (DataFrame)

Return type:

dict[str, object]

femic.site_index.summarize_reconciliation(frame, *, delta_threshold=2.0)[source]

Return a JSON-serializable coverage and conflict summary.

Parameters:
  • frame (DataFrame)

  • delta_threshold (float)

Return type:

dict[str, object]

SIBEC site-index estimates from the public BC workbook.

SIBEC provides mean plot site index and standard error by BEC unit, site series, and tree species. This module turns the public workbook into a tidy table and aggregates site-series rows to the BEC-unit/species grain used by VRI and VDYP reconciliation.

This is an ingest adapter. It does not estimate or fit site index.

exception femic.site_index.sibec.SibecError[source]

Bases: RuntimeError

Raised when the SIBEC table is missing or malformed.

femic.site_index.sibec.aggregate_sibec_by_bgc_unit(table, *, include_source=True)[source]

Aggregate SIBEC site-series rows to BEC-unit/species/source.

Parameters:
  • table (pandas.DataFrame) – Tidy SIBEC table from load_sibec_table() or combine_sibec_tables().

  • include_source (bool, optional) – Keep source_table in the grouping and output. Defaults to True so the 2013 approximation and 2014 addendum remain distinguishable.

Returns:

One row per source, BEC unit, and species with weighted mean SI (weighted by plot count when available, otherwise unweighted), minimum, maximum, mean standard error, site-series count, and total plot count.

Return type:

pandas.DataFrame

femic.site_index.sibec.combine_sibec_tables(*tables)[source]

Concatenate tidy SIBEC tables while preserving their source labels.

Parameters:

tables (DataFrame)

Return type:

DataFrame

femic.site_index.sibec.load_sibec_addendum(path)[source]

Load the public 2014 SIBEC addendum (ciReportByUnit).

Parameters:

path (Path)

Return type:

DataFrame

femic.site_index.sibec.load_sibec_table(path, *, sheet_name=0, source_table='2013_approximation')[source]

Load a SIBEC workbook or CSV into the tidy femic.sibec.v2 table.

Parameters:
  • path (pathlib.Path) – XLSX workbook or CSV export.

  • sheet_name (str or int, optional) – Worksheet for an XLSX file. The public 2013 approximation workbook has its header on the third row.

  • source_table (str, optional) – Provenance label for the rows. Use 2013_approximation for the base workbook and 2014_addendum for the addendum.

Returns:

Tidy SIBEC table with schema_version, source_table, region, BGC unit, site series, site association, species, plot count, mean site index, and standard error.

Return type:

pandas.DataFrame

Raises:

SibecError – If the file has no usable rows or is missing required columns.

femic.site_index.sibec.select_sibec_source(table, *, preference=('2014_addendum', '2013_approximation'))[source]

Select one explicit SIBEC source per BEC-unit/species.

The addendum is preferred by default when it contains the key; the 2013 approximation is the fallback. This is a declared preference, not a silent collapse: the selected source is written to si_sibec_source.

Parameters:
  • table (DataFrame)

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

Return type:

DataFrame

AU-level TSA site-index reader and summary.

The TSA 03_input-<tsa>.csv table is at the analysis-unit grain, not the VRI polygon/layer grain. This module reports it separately so the two grains are never silently conflated.

exception femic.site_index.au.AuSiteIndexError[source]

Bases: RuntimeError

Raised when a TSA AU-level site-index table cannot be read.

femic.site_index.au.load_au_site_index(path)[source]

Read a TSA 03_input table into a long AU/species site-index table.

Parameters:

path (Path) – CSV, Feather, or Parquet TSA input table. The table must contain feature_id and one or more <species>_si columns.

Returns:

One row per AU/species with the AU identifier, BEC zone/subzone, planted/natural leading species, the species SI value, and a leading species flag.

Return type:

pandas.DataFrame

Raises:

AuSiteIndexError – If the table has no feature identifier or no species SI columns.

femic.site_index.au.summarize_au_site_index(table)[source]

Return a JSON-serializable AU-level site-index summary.

Parameters:

table (DataFrame)

Return type:

dict[str, object]

VRI site-index fields and BEC/species keys.

The VRI checkpoint already carries SITE_INDEX and EST_SITE_INDEX per polygon. This reader selects those fields and builds the BEC-unit and species keys used by SIBEC and VDYP reconciliation.

exception femic.site_index.vri.VriError[source]

Bases: RuntimeError

Raised when a VRI table cannot provide site-index fields.

femic.site_index.vri.compose_bec_unit(zone, subzone, variant)[source]

Compose a BEC unit such as CWHvh3 from VRI fields.

Parameters:
  • zone (object)

  • subzone (object)

  • variant (object)

Return type:

str | None

femic.site_index.vri.load_vri_site_index(path)[source]

Read VRI site-index fields from a Feather, Parquet, or CSV table.

Parameters:

path (pathlib.Path) – VRI checkpoint or export.

Returns:

One row per VRI feature with BEC unit, canonical species key, VRI SITE_INDEX, EST_SITE_INDEX, and projection attributes.

Return type:

pandas.DataFrame

Raises:

VriError – If a required identifier or site-index column is missing, or no usable rows remain.

femic.site_index.vri.normalise_species(value)[source]

Return the canonical species key for a VRI or SIBEC code.

Parameters:

value (object)

Return type:

str | None

VDYP layer site-index values used by FEMIC curves.

The VDYP layer table already carries ESTIMATED_SITE_INDEX and the species the estimate applies to. This reader selects the primary layer and returns one site-index value per feature. It does not run VDYP or refit a curve.

exception femic.site_index.vdyp.VdypError[source]

Bases: RuntimeError

Raised when a VDYP layer table cannot provide site-index fields.

femic.site_index.vdyp.load_vdyp_site_index(path)[source]

Read primary-layer VDYP site index from a Feather, Parquet, or CSV.

Parameters:

path (pathlib.Path) – VDYP layer table with FEATURE_ID, ESTIMATED_SITE_INDEX, and EST_SITE_INDEX_SPECIES_CD. If LAYER_LEVEL_CODE is present, only the primary layer (1) is kept.

Returns:

One row per feature with the VDYP site index and the species the estimate applies to.

Return type:

pandas.DataFrame

Raises:

VdypError – If required columns are missing or no usable rows remain.

Reconcile VRI, VDYP, and SIBEC site-index values.

The reconciliation is intentionally a reporting layer. It records the values each existing BC product provides, the differences between them, and a documented reference value. It never rewrites a curve, changes an AAC, or fits a new site-index model.

exception femic.site_index.reconcile.SiteIndexReconciliationError[source]

Bases: RuntimeError

Raised when reconciliation inputs cannot be joined consistently.

femic.site_index.reconcile.reconcile_site_index(vri, vdyp, sibec_by_bgc_unit, *, delta_threshold=2.0, min_sibec_plot_count=7)[source]

Join VRI, VDYP, and SIBEC site-index values feature by feature.

Parameters:
Returns:

One row per VRI feature with source values, pairwise deltas, coverage status, and the documented reference value/source. The VDYP value is always the current curve input; the reference value is a comparison value and is not applied automatically.

Return type:

pandas.DataFrame

femic.site_index.reconcile.summarize_reconciliation(frame, *, delta_threshold=2.0)[source]

Return a JSON-serializable coverage and conflict summary.

Parameters:
  • frame (DataFrame)

  • delta_threshold (float)

Return type:

dict[str, object]