femic.efi.biomass Module

The femic.efi.biomass module loads published RSYC biomass and volume curves, evaluates the nonlinear form, checks the age domain, and applies a declared carbon fraction.

Use this page when you need an independently selectable biomass curve, a paired volume curve, or an aboveground-biomass carbon conversion.

Start Here If…

Use this page first if you are trying to:

  • load a femic.efi.biomass_curve.v1 document;

  • select a species/ecodistrict curve;

  • evaluate aboveground biomass, volume, or carbon at a stand age; or

  • verify that a carbon fraction and its source travel with the curve.

Typical Usage

from femic.efi.biomass import load_biomass_curves

family = load_biomass_curves("config/efi/biomass/rsyc_cariboo_pilot.json")
curve = family.select_one(species="PSEU.MEN")
print(curve.agb_t_ha(50))
print(curve.volume_m3_ha(50))
print(curve.carbon_t_c_ha(50))

Key Entry Surfaces

  • load_biomass_curves() Load and validate a curve family.

  • BiomassCurveFamily Select curves by species, region, or ecodistrict.

  • BiomassCurve One curve with agb_t_ha, volume_m3_ha, and carbon_t_c_ha.

  • RSYCCurve The published equation parameters and response unit.

Cross-References

Remote-sensing biomass yield curves and declared carbon conversion.

This module carries published RSYC curves (Tompalski et al. 2024, 2025) as data. It evaluates the published nonlinear form, checks the age domain, and applies an explicit carbon fraction. It does not fit a new model and does not copy the R package code.

The curve form is:

AGB = b1 * exp(-b4 * age) * (1 - exp(-b2 * age)) ** b3

where AGB is aboveground dry biomass in tonnes per hectare. The optional volume curve uses the same form and is kept separate so biomass and volume are never summed into the same account.

class femic.efi.biomass.BiomassCurve(curve_id, species, region, ecodistrict, age_min, age_max, agb, volume, carbon_fraction, carbon_fraction_source, source_id, source_url, licence_id, validation_note=None)[source]

Bases: object

One species/ecodistrict biomass curve with a declared carbon fraction.

Parameters:
  • curve_id (str)

  • species (str)

  • region (str)

  • ecodistrict (str)

  • age_min (float)

  • age_max (float)

  • agb (RSYCCurve)

  • volume (RSYCCurve | None)

  • carbon_fraction (float)

  • carbon_fraction_source (str)

  • source_id (str)

  • source_url (str)

  • licence_id (str)

  • validation_note (str | None)

curve_id

Stable curve identifier.

Type:

str

species

Species code, for example PSEU.MEN.

Type:

str

region

Broad region.

Type:

str

ecodistrict

Ecodistrict name.

Type:

str

age_min, age_max

Accepted stand-age domain.

Type:

float

agb

Aboveground biomass curve in t_ha.

Type:

RSYCCurve

volume

Optional volume curve in m3_ha for comparison.

Type:

RSYCCurve or None

carbon_fraction

Declared dry-biomass carbon fraction in [0, 1].

Type:

float

carbon_fraction_source

Source for the carbon fraction.

Type:

str

source_id, source_url, licence_id

Family provenance.

Type:

str

validation_note

Optional validation note.

Type:

str or None

agb_t_ha(age)[source]

Return aboveground biomass in tonnes per hectare.

Parameters:

age (float)

Return type:

float

carbon_t_c_ha(age)[source]

Return biomass carbon in tonnes of carbon per hectare.

Parameters:

age (float)

Return type:

float

to_dict()[source]

Return a JSON-friendly curve record.

Return type:

dict[str, object]

volume_m3_ha(age)[source]

Return volume in cubic metres per hectare, or None when absent.

Parameters:

age (float)

Return type:

float | None

exception femic.efi.biomass.BiomassCurveError[source]

Bases: ValueError

Raised when a biomass curve document or evaluation is invalid.

class femic.efi.biomass.BiomassCurveFamily(source_id, source_url, licence_id, curves)[source]

Bases: object

A validated family of RSYC biomass curves.

Parameters:
  • source_id (str)

  • source_url (str)

  • licence_id (str)

  • curves (tuple[BiomassCurve, ...])

select(*, species=None, region=None, ecodistrict=None)[source]

Select curves by species, region, and ecodistrict.

Returns:

Matching curves. Empty when nothing matches.

Return type:

tuple of BiomassCurve

Parameters:
  • species (str | None)

  • region (str | None)

  • ecodistrict (str | None)

select_one(*, species=None, region=None, ecodistrict=None)[source]

Select exactly one curve or raise a clear error.

Parameters:
  • species (str | None)

  • region (str | None)

  • ecodistrict (str | None)

Return type:

BiomassCurve

class femic.efi.biomass.RSYCCurve(model_id, model_version, response, unit, b1, b2, b3, b4)[source]

Bases: object

One published RSYC response curve.

Parameters:
  • model_id (str)

  • model_version (str)

  • response (str)

  • unit (str)

  • b1 (float)

  • b2 (float)

  • b3 (float)

  • b4 (float)

model_id

Stable model identifier.

Type:

str

model_version

Published model version.

Type:

str

response

agb or volume.

Type:

str

unit

t_ha for AGB or m3_ha for volume.

Type:

str

b1, b2, b3, b4

Published equation parameters.

Type:

float

evaluate(age)[source]

Evaluate the curve at a stand age.

Parameters:

age (float) – Stand age in years. Must be finite and greater than zero.

Returns:

Response in the curve unit.

Return type:

float

Raises:

BiomassCurveError – If the age is not finite or not positive.

femic.efi.biomass.load_biomass_curves(path)[source]

Load and validate a femic.efi.biomass_curve.v1 document.

Parameters:

path (str or Path) – JSON curve document.

Returns:

Validated curves and family provenance.

Return type:

BiomassCurveFamily

Raises:

BiomassCurveError – If the document is malformed, a required field is missing, a curve has an invalid domain, or the carbon fraction/source is absent.