API for the `exporter` module#

The exporter module provides the AnimalExportConfig, which is used to control the output of animal cohort data at each time step. An instance of the class is required by the AnimalCohort, which calls the dump() method within the setup and update steps to export data continuously during the model run.

Classes:

`AnimalCohortDataExporter`(output_directory[, ...])	Exporter for detailed animal cohort data.
`ResourcePoolDataExporter`(output_directory[, ...])	Exporter for resource pool state data.

class virtual_ecosystem.models.animal.exporter.AnimalCohortDataExporter(output_directory: Path, cohort_attributes: set[str] | None = None, float_format: str = '%0.5f')[source]#

Exporter for detailed animal cohort data.

This class writes one CSV file containing a row for every cohort at every time step. The file is opened in write mode on the first call to dump (including the header) and subsequently appended to.

The exporter mirrors the design of virtual_ecosystem.models.plants.exporter.CommunityDataExporter but is simplified to a single cohorts output stream.

Parameters:

output_directory – Directory where the CSV file will be created.
cohort_attributes – Optional subset of cohort attributes to export. If an empty set is provided, all available attributes are written.
float_format – Float format string used when writing numeric data.

Attributes:

`available_attributes`	The set of valid attribute names that can be selected for cohort export.
`cohort_attributes`	The set of animal cohort attributes to be exported.
`float_format`	The float format for data export.
`output_directory`	The directory in which to save animal cohort data.
`required_attributes`	A set of output fields that are always included in cohort export.

Methods:

`dump`(cohorts, time, time_index)	Write animal cohort and trophic interaction data to CSV.
`from_config`(output_directory, config)	Create an exporter from an AnimalExportConfig instance.

available_attributes: ClassVar[set[str]] = {'age', 'centroid_key', 'development_type', 'diet_type', 'functional_group', 'individuals', 'is_alive', 'is_mature', 'largest_mass_achieved', 'location_status', 'mass_carbon', 'mass_nitrogen', 'mass_phosphorus', 'occupancy_proportion', 'reproductive_environment', 'reproductive_mass_carbon', 'reproductive_mass_nitrogen', 'reproductive_mass_phosphorus', 'territory', 'territory_size', 'time_since_maturity', 'time_to_maturity'}#: The set of valid attribute names that can be selected for cohort export.

cohort_attributes: set[str]#: The set of animal cohort attributes to be exported.

dump(cohorts: Iterable[AnimalCohort], time: datetime64, time_index: int) → None[source]#

Write animal cohort and trophic interaction data to CSV.

Parameters:

cohorts – List of animal cohort objects.
time – Timestamp to associate with this snapshot.
time_index – The index of the datatime within the model updates.

float_format: str#: The float format for data export.

classmethod from_config(output_directory: Path, config: AnimalExportConfig) → AnimalCohortDataExporter[source]#

Create an exporter from an AnimalExportConfig instance.

Parameters:

output_directory – Directory where the CSV file will be created.
config – Configuration section controlling animal cohort export.

Returns:

Initialised AnimalCohortDataExporter instance.

output_directory: Path#: The directory in which to save animal cohort data.

required_attributes: ClassVar[tuple[str, ...]] = ('cohort_id', 'time', 'time_index')#: A set of output fields that are always included in cohort export.

class virtual_ecosystem.models.animal.exporter.ResourcePoolDataExporter(output_directory: Path, float_format: str = '%0.5f')[source]#

Exporter for resource pool state data.

Writes one CSV file containing a row for every resource pool sub-pool at every time step. The file is opened in write mode on the first call to dump (including the header) and subsequently appended to.

The exporter covers all animal-model resource pools: carcass, excrement, fungal fruiting body, soil, and plant/litter array pools. Each row identifies the pool by pool_type, pool_name, sub_pool, pft, and cell_id, and records the carbon, nitrogen, and phosphorus masses at the time of the snapshot.

For plant and litter array pools the snapshot reflects the pre-foraging available masses, because ResourcePool.elemental_masses is populated by set_resources at the start of each update step and is not modified in-place during foraging.

Parameters:

output_directory – Directory where the CSV file will be created.
float_format – Float format string used when writing numeric data.

Methods:

`dump`(carcass_pools, excrement_pools, ...)	Write resource pool state data to CSV.
`from_config`(output_directory, config)	Create an exporter from a ResourcePoolExportConfig instance.

Attributes:

`float_format`	The float format for data export.
`output_directory`	The directory in which to save resource pool data.

dump(carcass_pools: dict[int, list[CarcassPool]], excrement_pools: dict[int, list[ExcrementPool]], fungal_fruiting_pools: dict[int, FungalFruitPool], soil_pools: dict[int, dict[str, SoilPool]], resource_pools: list[ResourcePool], time: datetime64, time_index: int) → None[source]#

Write resource pool state data to CSV.

This method is a no-op if the exporter is inactive.

Parameters:

carcass_pools – Carcass pools keyed by cell id, each containing one or more CarcassPool instances.
excrement_pools – Excrement pools keyed by cell id, each containing one or more ExcrementPool instances.
fungal_fruiting_pools – Fungal fruiting body pools keyed by cell id.
soil_pools – Soil pools keyed by cell id and then by pool-type string (e.g. "bacteria", "saprotrophic_fungi").
resource_pools – Flat list of plant and litter ResourcePool instances. Each pool’s elemental_masses array holds pre-foraging available masses set by the most recent set_resources call.
time – Timestamp to associate with this snapshot.
time_index – The index of the datetime within the model updates.

float_format: str#: The float format for data export.

classmethod from_config(output_directory: Path, config: ResourcePoolExportConfig) → ResourcePoolDataExporter[source]#

Create an exporter from a ResourcePoolExportConfig instance.

If the config has enabled=False, returns an inactive exporter that silently no-ops on all dump calls.

Parameters:

output_directory – Directory where the CSV file will be created.
config – Configuration section controlling resource pool export.

Returns:

Initialised ResourcePoolDataExporter instance.

output_directory: Path#: The directory in which to save resource pool data.

API for the exporter module#

API for the `exporter` module#