Site-Index Reconciliation (femic.site-index.reconciliation.v2)
Purpose
This page is the contract for reporting and reconciling the site-index values that FEMIC already receives from three British Columbia products:
VRI polygon
SITE_INDEXandEST_SITE_INDEX;VDYP primary-layer
ESTIMATED_SITE_INDEX; andSIBEC site-series estimates by BEC unit and tree species.
The reconciliation is a reporting layer. It does not derive a new site-index model, refit VDYP/TIPSY curves, change an AAC/THLB calculation, or silently replace a curve input.
The first pilot is TSA46. Its coverage and limits are recorded below so a consumer does not mistake a sparse VDYP layer value for a complete polygon estimate. The AU-level TSA SI is reported separately and is never forced into the polygon table.
Quick Contract
Reconciliation schema:
femic.site-index.reconciliation.v2.SIBEC tidy schema:
femic.sibec.v2.AU-level schema:
femic.site-index.au.v1.VRI reader schema:
femic.vri.site-index.v1.VDYP reader schema:
femic.vdyp.site-index.v1.Polygon grain: one output row per VRI feature.
AU grain: one output row per analysis unit and species.
Join keys:
feature_id; BEC unit key; canonical species key.Default conflict threshold:
2.0m.Default SIBEC reference minimum:
7plots.SIBEC source preference:
2014_addendumfirst, then2013_approximation; the selected source is written explicitly.Reference precedence: VRI
SITE_INDEX-> SIBEC (meeting the plot-count minimum) -> VDYP -> VRIEST_SITE_INDEX.The VDYP value is always retained as the current curve input; the reference value is never applied automatically.
Source Inputs
VRI
femic.site_index.vri.load_vri_site_index reads a VRI Feather, Parquet, or
CSV table and selects:
FEATURE_ID;BEC_ZONE_CODE,BEC_SUBZONE,BEC_VARIANT;SPECIES_CD_1andSPECIES_PCT_1;SITE_INDEXandEST_SITE_INDEX; andPROJ_AGE_1andPROJ_HEIGHT_1.
The BEC unit is composed as zone + subzone + variant (for example
CWHvh2). The lookup key is upper-cased so VRI and SIBEC spelling
differences do not prevent a match.
The VRI reader uses a small alias map for known code variants. H maps to
HW, FDC maps to FD, and AC maps to AT. Unknown codes are
kept as-is and simply fail to match SIBEC or VDYP; they are not guessed.
VDYP
femic.site_index.vdyp.load_vdyp_site_index reads a VDYP layer table and
keeps the primary layer (LAYER_LEVEL_CODE == "1") with a non-null
ESTIMATED_SITE_INDEX. It records the species named by
EST_SITE_INDEX_SPECIES_CD.
This is the polygon/layer-level VDYP output. It is not the AU-level SI in
the 03_input TSA table. The pilot showed that only a small share of VDYP
primary layers carry a non-null site index, so the reconciliation does not
claim complete VDYP coverage.
SIBEC
femic.site_index.sibec.load_sibec_table reads the public 2013
approximation workbook (header on the third row) or a CSV export. It
normalises the columns to:
source_table(source provenance);region,bgc_unit,site_series,site_association;species;plot_count,mean_site_index,standard_error; andschema_version = femic.sibec.v2.
load_sibec_addendum reads the 2014 addendum (ciReportByUnit). It
removes the repeated page-header blocks and accepts the addendum’s
Sample Size / Mean Site Index / Standard Error columns. The result
keeps source_table = 2014_addendum; it is never silently merged into the
2013 approximation.
combine_sibec_tables concatenates the two tidy tables while preserving the
source_table labels. aggregate_sibec_by_bgc_unit groups site-series rows
to BEC unit + species + source and reports:
si_sibec_mean(weighted by plot count when counts are available, otherwise unweighted);si_sibec_minandsi_sibec_max;mean standard error;
total plot count; and
the number of contributing site series.
select_sibec_source then chooses one row per BEC-unit/species with the
declared preference: the 2014 addendum first, then the 2013 approximation. The
selected label is written to si_sibec_source and carried into the
reconciliation as si_sibec_vri_source and si_sibec_vdyp_source.
The mean is not a polygon-level SIBEC estimate. VRI does not carry a site series, so SIBEC site-series rows cannot be joined directly to a polygon. The SIBEC range is used to test whether a VRI or VDYP value is outside the BEC-unit/species envelope; the mean is retained as descriptive provenance.
The 2013 approximation and 2014 addendum are both supported. The addendum is a smaller supplement (224 usable rows in the public workbook); the 2013 table is the broad base.
AU-level TSA SI
femic.site_index.au.load_au_site_index reads
03_input-<tsa>.csv at the analysis-unit/species grain. It reports:
au_id(thefeature_idin the TSA input);bec_zoneandbec_subzone;planted_species,natural_species, andleading_species;species/species_keyandsi_au; andis_leadingfor the leading species.
summarize_au_site_index states the grain explicitly
(analysis_unit_species), counts AUs, rows, species, and BEC zones, and
summarizes the leading-species SI. The AU table has no BEC variant in the TSA
input, so it is not joined to the VRI polygon table. It is written as a
separate CSV and JSON summary.
Reconciliation Rules
Species matching
The VRI leading species and the VDYP site-index species are compared separately. A VRI-versus-VDYP delta is only calculated when both species keys are present and equal. When they differ:
species_matchisfalse;delta_vri_vdypis null; andthe SIBEC values for each species are still reported separately.
This avoids comparing a VRI value for one species with a VDYP value for another species.
Pairwise deltas
The following differences are reported:
delta_vri_vdyp= VDYP - VRI, only when species match;delta_vri_sibec= SIBEC mean - VRI (descriptive);delta_vdyp_sibec= SIBEC mean - VDYP (descriptive);delta_vri_sibec_range= distance of VRI outside the SIBEC min/max range, or0when VRI is inside the range;delta_vdyp_sibec_range= distance of VDYP outside the SIBEC min/max range, or0when VDYP is inside the range; anddelta_abs_max= the largest absolute value among the species-matched VRI/VDYP delta and the two SIBEC range exceedances.
delta_abs_max > delta_threshold marks the row as a conflict. The default
threshold is 2.0 m. A conflict means “look here”; it does not mean that one
source is wrong.
Status and reference
si_status is one of:
complete: VRISITE_INDEX, VDYP, and SIBEC for the VRI species are all present, and no comparable difference exceeds the threshold;conflict: a comparable difference exceeds the threshold;partial: some source values are present but the triple is incomplete; ormissing: no source value is present.
si_reference and si_reference_source use the precedence below. The
reference is a comparison value, not an overwrite:
VRI
SITE_INDEXwhen present (sourcevri);SIBEC mean when the VRI value is absent and the SIBEC plot count meets
min_sibec_plot_count(sourcesibec);VDYP when the first two are absent (source
vdyp);VRI
EST_SITE_INDEXas the final fallback (sourcevri_estimate).
delta_reference_curve is si_reference - si_vdyp. It shows how far the
reference is from the VDYP value the current curve uses.
Output Columns
Column |
Meaning |
|---|---|
|
VRI feature identifier. |
|
Composed BEC unit, such as |
|
VRI leading species. |
|
Species named by the VDYP site-index field. |
|
Whether the two species keys are present and equal. |
|
VRI field site index. |
|
VRI estimated site index. |
|
VDYP primary-layer estimated site index. |
|
SIBEC mean for the VRI species and BEC unit. |
|
SIBEC site-series range for the VRI species. |
|
Mean SIBEC standard error for the VRI species. |
|
Total SIBEC plot count for the VRI species; |
|
Number of SIBEC site series behind the VRI-species aggregate. |
|
Selected SIBEC source for the VRI species ( |
|
SIBEC values for the VDYP species. |
|
Selected SIBEC source for the VDYP species. |
|
VDYP - VRI when species match. |
|
Descriptive difference from the SIBEC mean. |
|
Distance outside the SIBEC range. |
|
Largest comparable absolute difference. |
|
Number of non-null values among VRI, VDYP, and SIBEC/VRI. |
|
|
|
Documented comparison value and its source. |
|
Reference minus VDYP. |
|
VRI projection attributes carried for review. |
CLI
Run the reconciliation after installing FEMIC:
python -m femic.site_index \
--vri data/vri_vclr1p_checkpoint8.feather \
--vdyp data/vdyp_lyr-tsa46.feather \
--sibec data/sibec2013approx_final.xlsx \
--sibec-addendum data/2013sisuaddendum_jul2014.xlsx \
--au-input data/03_input-tsa46.csv \
--out-csv out/tsa46_si_reconciliation.csv \
--out-json out/tsa46_si_summary.json \
--out-au-csv out/tsa46_au_site_index.csv \
--out-au-json out/tsa46_au_summary.json \
--delta-threshold 2.0
Use --sibec-sheet to select a non-default worksheet. Use
--sibec-addendum to combine the 2014 addendum with the 2013 base; the
addendum is preferred for duplicate BEC-unit/species keys and the selected
source is written to the CSV. Use --au-input plus the AU output paths for
the separate analysis-unit report. The command prints the polygon JSON summary
and writes the feature-level and AU-level files when paths are provided.
TSA46 Pilot (26 October 2026)
Inputs:
VRI checkpoint 8, 171,826 features;
VDYP layer table, primary layer only;
SIBEC 2013 approximation, 4,023 source rows; and
SIBEC 2014 addendum, 224 usable rows.
Polygon results:
si_vripresent: 171,826 (100%);si_vri_estpresent: 5,966 (3.5%);si_vdyppresent: 3,384 (2.0%);si_sibec_vripresent: 136,807 (79.6%);SIBEC VRI-species source: 136,659 from 2013 and 148 from the addendum;
complete triple: 2,285 (1.3%);
conflicts at 2.0 m: 25,559 (14.9%);
partial: 143,982 (83.8%); and
missing: 0.
The high partial count is driven by sparse VDYP layer site index, not by a missing VRI value. The SIBEC range test is the main polygon-level consistency check in this pilot. The VDYP layer field is too sparse to support a complete three-way comparison.
AU-level TSA46 report:
21 analysis units;
462 AU/species rows;
22 species columns;
BEC zones: CWH and MH;
leading species: HW 8, CW 3, FD 3, YC 3, BA 3, HM 1; and
leading-species SI: min 6.3, median 10.9, mean 11.43, max 22.5 m.
The AU table has no BEC variant and is not joined to the polygon table. It is a separate grain and a separate output.
Known Limits
SIBEC 2013 is the broad base; the 2014 addendum is a 224-row supplement. The addendum is preferred for duplicate BEC-unit/species keys, and the selected source is explicit in the output.
SIBEC is aggregated to BEC unit + species because VRI has no site series. The range check is a screening test, not a site-series assignment.
The AU-level TSA table has no BEC variant and is not joined to the polygon table. Treat its summary as the current curve-input grain, not a polygon estimate.
VRI
SITE_INDEXis a provincial inventory value, not a newly measured ground plot.VDYP layer coverage depends on the instance and layer export; do not assume every VRI feature has a VDYP layer value.
Species aliases are explicit. Unknown species are retained but do not match.
The reconciliation does not change curves, AAC, THLB, or schedules.