spatiocoexistence.inventory package

class spatiocoexistence.inventory.Inventory

Bases: object

This inventory class stores forest data from the simulation and the ForestGEO network. Instance methods offer statistics for analyzing the data directly. Some statistics require crowding indices, which is why they are calculated if they are not provided in the data. :no-index:

property CI_C

Conspecific crowding index (unweighted).

property CI_CS

Conspecific crowding index.

property CI_CS_d

Conspecific crowding index (distance-weighted).

property CI_C_d

Conspecific crowding index (distance-weighted, unweighted).

property CI_H

Heterospecific crowding index (unweighted).

property CI_HS

Heterospecific crowding index.

property CI_HS_d

Heterospecific crowding index (distance-weighted).

property CI_H_d

Heterospecific crowding index (distance-weighted, unweighted).

apply_focus(focus=None, reproductive_size=1.0)

Filter this Inventory in-place to a subset of trees based on focus.

• “rep”: reproductive trees, dbh >= reproductive_size

• “rec”: recruits, status == 1

• “sap”: saplings, dbh < reproductive_size

• “dead”: dead trees, status == -1

• None: no filtering; do nothing.

The inventory’s internal data array is updated in-place; no new Inventory instance is created.

Parameters:

• focus (str | None) – Which trees to focus on (“rep”, “rec”, “sap”, “dead” or None).

• reproductive_size (float) – DBH threshold separating saplings from reproductives.

Raises:

ValueError – if focus is not one of the allowed values.

Returns:

None.

Return type:

None

count_reproductives(reproductive_size)

Count the number of reproductive trees.

All individuals are checked to be alive and larger or equally large than reproductive_size.

Parameters:

reproductive_size (float) – The size upon which an individual can reproduce.

Returns:

Amount of reproductives per species, indices of reproductive trees.

Return type:

tuple[ndarray[int32], ndarray[int32]]

count_saplings(reproductive_size)

Count the number of saplings.

All individuals are checked to be alive and smaller than reproductive_size.

Parameters:

reproductive_size (float) – The size upon which an individual can reproduce.

Returns:

The total amount of saplings.

Return type:

int

property data: ndarray

The full structured numpy array representing the inventory. Read-only: do not assign directly, use field setters or methods.

property dbh

Diameter at breast height (np.ndarray, dtype float64). This property can be updated/set. Setting it will automatically recalculate all crowding indices.

extend_inventory(other)

Extend the current inventory by appending another inventory’s data.

This method concatenates all fields from the other inventory to the current one and recalculates all crowding indices for the combined dataset.

Parameters:

other (Inventory | ndarray) – Another Inventory object or structured numpy array to append.

Raises:

• TypeError – If other is not an Inventory or compatible structured array.

• ValueError – If the data structures are incompatible.

classmethod from_data(data, radius=10.0)

Create an Inventory instance from existing data, a file path, or another Inventory.

If an Inventory is provided, its data and radius are copied. If a Path is provided, the file is read and validated. If a numpy array is provided, it is validated for correct structure and types.

Parameters:

• data (ndarray | Path | Inventory) – Structured numpy array, file path, or Inventory to initialize from.

• radius (float) – Neighborhood radius for crowding indices (default: 10.0).

• returns – A new Inventory instance initialized from the provided data.

classmethod from_random(n_species, dim_x, dim_y, radius=10.0, num_threads=1)

Create an Inventory instance from randomly spread trees. These trees will have the same density as trees in the BCI plot.

Parameters:

• n_species (int) – Number of different species to include in the inventory.

• dim_x (float) – Width of the plot area.

• dim_y (float) – Height of the plot area.

• radius (float) – Neighborhood radius for crowding indices (default: 10.0).

• num_threads (int) – Number of threads to use for inventory creation (default: 1).

Returns:

A new Inventory instance with randomly generated data.

get_BA_and_k()

Calculates summary statistics for BA and k using inventory data.

BA stands for basal area, and k represents aggregation. ff is for comparing a focal species with conspecifics. fh is for comparing a focal species with heterospecifics.

Returns:

Tuple of arrays (BA_ff, BA_fh, n_BA_ff, n_BA_fh, k_ff, k_fh, abundance_con, abundance_het).

Return type:

tuple

get_BA_distribution()

Return the mean basal area (BA) per size class. Only size classes that contain at least one individual are returned.

Returns:

A tuple (centers, counts) where centers are the log-transformed midpoints of the occupied size classes and counts are the mean basal area per occupied size class.

Return type:

tuple[ndarray, ndarray]

get_CI_CS_distribution(bins)

Get distribution counts for conspecific crowding index (CI_CS).

Parameters:

bins (ndarray) – Array of bin edges for distribution.

Returns:

Distribution of CI_CS.

Return type:

ndarray

get_CI_HS_distribution(bins)

Get distribution counts for heterospecific crowding index (CI_HS).

Parameters:

bins (ndarray) – Array of bin edges for distribution.

Returns:

Distribution of CI_HS.

Return type:

ndarray

get_SAD_distribution(bins)

Get distribution counts for species abundance distribution (SAD).

Parameters:

bins (ndarray) – Array of bin edges for abundance classes.

Returns:

Distribution of SAD.

Return type:

ndarray

get_recruitment_distribution(bins)

Get distribution counts for recruitment probabilities.

Parameters:

bins (ndarray) – Array of bin edges for distribution.

Returns:

Distribution of recruitment probabilities.

Return type:

ndarray

get_reduced_growth_distribution(bins, beta_gr=0.084)

Get distribution counts for reduced growth values.

Parameters:

• bins (ndarray) – Array of bin edges for distribution.

• beta_gr (float) – Growth reduction parameter.

Returns:

Distribution of reduced growth.

Return type:

ndarray

get_size_distribution()

Return counts of individuals per DBH size class.

Returns:

The midpoints of the size classes, and the counts of individuals per size class.

Return type:

tuple[ndarray, ndarray]

get_survival_distribution(bins)

Get distribution counts for survival probabilities.

Parameters:

bins (ndarray) – Array of bin edges for distribution.

Returns:

Distribution of survival probabilities.

Return type:

ndarray

plot(threshold=50, filter=1.0, scale=7.5, focus=None, show=False, figsize=(22, 10), reference_inventory=None, save=False, filename='inventory_overview.png')

Plot the current state of the inventory.

Parameters:

• threshold (int) – Minimum abundance of conspecifics for summary statistics.

• filter (float) – Filter out all trees below that size for inventory plot.

• scale (float) – Scaling factor for point size based on DBH (default 7.5).

• figsize (tuple) – Figure size tuple (width, height).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose statistics are plotted as reference (in red) where applicable.

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_BA_distribution(reference_inventory=None, figsize=None, show=False, save=False, filename='BA_distribution.png')

Plot mean basal area (BA) per size class for this inventory.

Parameters:

• reference_inventory (Inventory | None) – Optional inventory whose BA per size class is overlaid as a reference curve (in red) using the same size-class bins.

• figsize (tuple[float, float] | None) – Optional figure size used. If None, a default size is used.

• show (bool) – If True, immediately display the figure.

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_CI_CS_distribution(figsize=None, show=False, reference_inventory=None, save=False, filename='CI_CS_distribution.png')

Plot CI_CS distribution as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose CI_CS distribution is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

plot_CI_HS_distribution(figsize=None, show=False, reference_inventory=None, save=False, filename='CI_HS_distribution.png')

Plot CI_HS distribution as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose CI_HS distribution is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

plot_SAD(figsize=None, show=False, reference_inventory=None, save=False, filename='SAD.png')

Plot the species abundance distribution (SAD) as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose SAD is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_k_vs_abundance(threshold=50, figsize=None, show=False, reference_inventory=None, save=False, filename='k_vs_abundance.png')

Plot conspecific aggregation (k_ff) against species abundance as a standalone figure.

Parameters:

• threshold (int) – Minimum abundance threshold for plotting (default 50).

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose k_ff vs abundance relationship is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_map(filter=1.0, scale=7.5, figsize=None, show_axes=True, show=False, save=False, filename='inventory_map.png', title='Inventory')

Plot only the spatial map of the inventory (trees as scatter plot).

Parameters:

• filter (float) – Minimum DBH of trees to be plotted.

• scale (float) – Scaling factor for point size based on DBH.

• figsize (tuple | None) – Figure size tuple (width, height). If None, auto-calculated based on plot dimensions.

• show_axes (bool) – If False, hide axis frame, ticks, labels and grid for clean map-only plot (default True).

• show (bool) – Whether to display the plot (default True).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

• title (str) – Title of the plot, default = ‘Inventory’.

plot_rank_abundance_distribution(figsize=None, show=False, reference_inventory=None, save=False, filename='rank_abundance.png')

Plot the rank–abundance distribution as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose rank–abundance distribution is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_reduced_growth(figsize=None, show=False, reference_inventory=None, save=False, filename='reduced_growth.png')

Plot the reduced growth histogram as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose reduced growth distribution is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_reduced_recruitment(figsize=None, show=False, reference_inventory=None, save=False, filename='reduced_recruitment.png')

Plot the reduced recruitment histogram as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose reduced recruitment distribution is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_reduced_survival(figsize=None, show=False, reference_inventory=None, save=False, filename='reduced_survival.png')

Plot the reduced survival histogram as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose reduced survival distribution is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_saving_path: Path | str | None = None

plot_size_distribution(reference_inventory=None, figsize=None, show=False, save=False, filename='size_distribution.png')

Plot size-class frequency distribution as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose size-class distribution is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_size_mean_CI_CS(figsize=None, show=False, reference_inventory=None, save=False, filename='size_mean_CI_CS.png')

Plot mean CI_CS per size class as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True)

• reference_inventory (Inventory | None) – Optional inventory whose mean CI_CS per size class is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_size_mean_CI_HS(figsize=None, show=False, reference_inventory=None, save=False, filename='size_mean_CI_HS.png')

Plot mean CI_HS per size class as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose mean CI_HS per size class is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_size_mortality(figsize=None, show=False, reference_inventory=None, save=False, filename='size_mortality.png')

Plot mortality vs size class as a standalone figure.

Parameters:

• figsize (tuple[float, float] | None) – Figure size tuple (width, height). If None, defaults to (6, 4).

• show (bool) – Whether to display the plot (default True).

• reference_inventory (Inventory | None) – Optional inventory whose mortality vs size-class relationship is plotted as reference (in red).

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

plot_species_area_relationship(cell_size, n_steps=50, n_repeats=100, reference_inventory=None, loglog=True, figsize=None, show=False, save=False, filename='species_area_relationship.png')

Plot the species–area relationship (SAR) for this inventory.

The SAR is obtained from species_area_relationship() and plotted as species richness versus area. Optionally, a reference inventory can be overlaid for comparison.

Parameters:

• cell_size (float) – Grid cell size passed to species_area_relationship().

• n_steps (int) – Number of different box areas to evaluate (default: 50).

• n_repeats (int) – Number of random boxes per area size (default: 100).

• reference_inventory (Inventory | None) – Optional second inventory whose SAR is plotted as a reference curve using the same parameters (drawn in red).

• loglog (bool) – If True (default), use log–log axes for the SAR plot; if False, use linear axes.

• figsize (tuple[float, float] | None) – Optional figure size passed to matplotlib.pyplot.subplots(). If None, a default of (6.0, 4.0) is used.

• show (bool) – If True, immediately display the figure using matplotlib.pyplot.show().

• save (bool) – If True, save the figure to self.plot_saving_path / filename (if plot_saving_path is set) or to filename in the current working directory.

• filename (str) – File name used when save is True.

Returns:

None.

Return type:

None

reduced_growth(beta_gr=None)

Calculate the reduced growth using the formula from Cython. Reduced means, to only account for the exponential part of the growth function.

Parameters:

beta_gr (float | None) – Growth reduction parameter.

Returns:

Array of reduced growth values.

Return type:

NDArray[np.float64]

reduced_recruitment()

Calculate the recruitment probability using the formula from recruitment in cython. Reduced means, to only account for the exponential part of the recruitment probability.

Returns:

Array of recruitment probabilities.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

reduced_survival(reduced=True)

Calculate the reduced survival probabilities using the formula from mortality in cython. Reduced means, to only account for the exponential part of the survival probability.

Parameters:

reduced (bool) – If True, calculate reduced survival; if False, apply background mortality.

Returns:

Array of survival probabilities.

Return type:

NDArray[np.float64]

property species

Species IDs (np.ndarray, dtype int64). This property can be updated/set. Setting it will automatically recalculate all crowding indices.

species_abundance()

Count the amount of individuals per species.

Returns:

Array of individual counts per species.

Return type:

ndarray[int32]

species_abundance_distribution(abundance_class)

Get the amount of species per abundance class.

Parameters:

abundance_class (ndarray) – Array of abundance class boundaries (bins).

Returns:

Distribution of species counts per abundance class.

Return type:

tuple

species_area_relationship(cell_size, n_steps=50, n_repeats=100)

Compute the species–area relationship (SAR) for this inventory.

The species–area relationship is estimated by repeatedly sampling square boxes of increasing side length over the plot under periodic boundary conditions, and counting the number of species present in each box.

The implementation delegates the heavy computation to the Cython helper _species_area_relationship(), which uses the spatial grid built by cy_create_grid().

Parameters:

• cell_size (float) – Grid cell size used for the internal spatial index. A value on the order of the typical inter-tree distance is usually a good choice.

• n_steps (int) – Number of different box side lengths (area sizes) to evaluate (default: 50).

• n_repeats (int) – Number of random box placements per side length used to estimate mean and standard deviation of species richness (default: 100).

Returns:

A tuple (area, sar_mean, sar_std) where area is the sampled box area, sar_mean is the mean species richness, and sar_std the standard deviation of richness across repeats for each area.

Return type:

tuple[ndarray, ndarray, ndarray]

property status

Status codes (np.ndarray, dtype int32). This property can be updated/set. Setting it will automatically recalculate all crowding indices.

property x

X-coordinates of individuals (np.ndarray, dtype float64). This property can be updated/set. Setting it will automatically recalculate all crowding indices.

property y

Y-coordinates of individuals (np.ndarray, dtype float64). This property can be updated/set. Setting it will automatically recalculate all crowding indices.