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.v2report;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
femic.site_index.sibec.load_sibec_table()Load the public workbook or a CSV intofemic.sibec.v2.femic.site_index.sibec.load_sibec_addendum()Load the 2014 addendum and preservesource_table.femic.site_index.sibec.combine_sibec_tables()Concatenate SIBEC sources without collapsing their provenance.femic.site_index.sibec.aggregate_sibec_by_bgc_unit()Aggregate site-series rows by source, BEC unit, and species.femic.site_index.sibec.select_sibec_source()Choose one explicit source per key with the addendum-first preference.femic.site_index.au.load_au_site_index()Read03_inputat the analysis-unit/species grain.femic.site_index.au.summarize_au_site_index()Summarize the AU-level report without joining it to polygons.femic.site_index.vri.load_vri_site_index()Select VRI site-index fields and build BEC/species keys.femic.site_index.vdyp.load_vdyp_site_index()Select primary-layer VDYP site index.femic.site_index.reconcile.reconcile_site_index()Produce the feature-level reconciliation table.femic.site_index.reconcile.summarize_reconciliation()Produce the JSON-serializable coverage and conflict summary.python -m femic.site_indexCommand-line entry point.
Cross-References
Site-index provenance and reconciliation helpers.
This package consumes existing BC site-index products:
VRI
SITE_INDEXandEST_SITE_INDEXper polygon;VDYP primary-layer
ESTIMATED_SITE_INDEX; andSIBEC BEC-unit/species estimates.
It does not derive a new site-index model.
- exception femic.site_index.AuSiteIndexError[source]
Bases:
RuntimeErrorRaised when a TSA AU-level site-index table cannot be read.
- exception femic.site_index.SibecError[source]
Bases:
RuntimeErrorRaised when the SIBEC table is missing or malformed.
- exception femic.site_index.SiteIndexReconciliationError[source]
Bases:
RuntimeErrorRaised when reconciliation inputs cannot be joined consistently.
- exception femic.site_index.VdypError[source]
Bases:
RuntimeErrorRaised when a VDYP layer table cannot provide site-index fields.
- exception femic.site_index.VriError[source]
Bases:
RuntimeErrorRaised 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()orcombine_sibec_tables().include_source (bool, optional) – Keep
source_tablein the grouping and output. Defaults toTrueso 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
CWHvh3from 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_inputtable into a long AU/species site-index table.- Parameters:
path (Path) – CSV, Feather, or Parquet TSA input table. The table must contain
feature_idand one or more<species>_sicolumns.- 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.v2table.- 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_approximationfor the base workbook and2014_addendumfor 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, andEST_SITE_INDEX_SPECIES_CD. IfLAYER_LEVEL_CODEis 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:
vri (pandas.DataFrame) – Output of
femic.site_index.vri.load_vri_site_index().vdyp (pandas.DataFrame) – Output of
femic.site_index.vdyp.load_vdyp_site_index().sibec_by_bgc_unit (pandas.DataFrame) – Output of
femic.site_index.sibec.aggregate_sibec_by_bgc_unit().delta_threshold (float, optional) – Absolute difference in metres above which a row is flagged as a conflict. The default is
2.0m.min_sibec_plot_count (int, optional) – Minimum SIBEC plot count for SIBEC to become the reference value when VRI has no
SITE_INDEX. The default is7.
- 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:
RuntimeErrorRaised 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()orcombine_sibec_tables().include_source (bool, optional) – Keep
source_tablein the grouping and output. Defaults toTrueso 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.v2table.- 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_approximationfor the base workbook and2014_addendumfor 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:
RuntimeErrorRaised 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_inputtable into a long AU/species site-index table.- Parameters:
path (Path) – CSV, Feather, or Parquet TSA input table. The table must contain
feature_idand one or more<species>_sicolumns.- 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:
RuntimeErrorRaised 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
CWHvh3from 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:
RuntimeErrorRaised 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, andEST_SITE_INDEX_SPECIES_CD. IfLAYER_LEVEL_CODEis 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:
RuntimeErrorRaised 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:
vri (pandas.DataFrame) – Output of
femic.site_index.vri.load_vri_site_index().vdyp (pandas.DataFrame) – Output of
femic.site_index.vdyp.load_vdyp_site_index().sibec_by_bgc_unit (pandas.DataFrame) – Output of
femic.site_index.sibec.aggregate_sibec_by_bgc_unit().delta_threshold (float, optional) – Absolute difference in metres above which a row is flagged as a conflict. The default is
2.0m.min_sibec_plot_count (int, optional) – Minimum SIBEC plot count for SIBEC to become the reference value when VRI has no
SITE_INDEX. The default is7.
- 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