API Reference¶

This page contains the API reference for the nuee package.

nuee Package¶

nuee: Community Ecology Analysis in Python¶

nuee is a comprehensive Python implementation of the popular R package vegan for community ecology analysis. It provides tools for ordination, diversity analysis, dissimilarity measures, and statistical testing commonly used in ecological research.

Modules¶

ordinationmodule: Ordination methods including NMDS, RDA, CCA, PCA, and environmental fitting
diversitymodule: Diversity indices and rarefaction analysis
dissimilaritymodule: Distance measures and dissimilarity-based tests (PERMANOVA, ANOSIM, etc.)
permutationmodule: Permutation-based statistical tests
plottingmodule: Visualization functions for ecological data
compositionmodule: Compositional data analysis utilities (CLR/ILR/ALR transforms, closure, etc.)
datasetsmodule: Sample datasets for testing and examples

Examples

Basic NMDS ordination:

>>> import nuee
>>> species_data = nuee.datasets.varespec()
>>> nmds_result = nuee.metaMDS(species_data, k=2, distance="bray")
>>> print(f"NMDS Stress: {nmds_result.stress:.3f}")
NMDS Stress: 0.133

Calculate diversity indices:

>>> shannon_div = nuee.shannon(species_data)
>>> simpson_div = nuee.simpson(species_data)
>>> richness = nuee.specnumber(species_data)

Perform PERMANOVA test:

>>> distances = nuee.vegdist(species_data, method="bray")
>>> env_data = nuee.datasets.varechem()
>>> permanova_result = nuee.adonis2(distances, env_data)

Notes

nuee is inspired by the R package vegan developed by Jari Oksanen and the vegan development team. It aims to provide similar functionality in a Pythonic interface while leveraging the scientific Python ecosystem (NumPy, SciPy, pandas, matplotlib).

References

nuee.metaMDS(X: ndarray | DataFrame, k: int = 2, distance: str = 'bray', trymax: int = 20, maxit: int = 1000, trace: bool = False, autotransform: bool = True, wascores: bool = True, expand: bool = True, random_state: int | None = None, **kwargs) → OrdinationResult[source]¶

Non-metric Multidimensional Scaling with automatic transformation.

This function provides a high-level interface for NMDS ordination, following the conventions of the R vegan package’s metaMDS function. It automatically handles data transformation and uses multiple random starts to find the best ordination solution.

Parameters:

X (np.ndarray or pd.DataFrame) – Community data matrix with samples in rows and species in columns. Values should be non-negative abundances or counts.
k (int, default=2) – Number of dimensions for the ordination. Common choices are 2 or 3.
distance (str, default="bray") – Distance metric to use for calculating dissimilarities. See nuee.vegdist() for available options.
trymax (int, default=20) – Maximum number of random starts to find the best solution. Higher values increase computation time but may find better solutions.
maxit (int, default=1000) – Maximum number of iterations for each random start.
trace (bool, default=False) – If True, print progress information including stress values.
autotransform (bool, default=True) – If True, automatically apply square root transformation to abundance data (values > 1) to reduce the influence of dominant species.
wascores (bool, default=True) – If True, calculate weighted average species scores based on site scores and species abundances.
expand (bool, default=True) – If True, expand the result to include additional information.
random_state (int, optional) – Seed used for reproducible random starts. If None, each run is initialised independently.
**kwargs (dict) – Additional parameters passed to the NMDS class.

Returns:

Result object containing:

pointspd.DataFrame
Site (sample) scores in the ordination space
speciespd.DataFrame, optional
Species scores (if wascores=True)
stressfloat
Final stress value (lower is better)
convergedbool
Whether the solution converged

Return type:

OrdinationResult

Notes

NMDS is a rank-based ordination method that attempts to preserve the rank order of dissimilarities between samples. Unlike metric methods like PCA, NMDS makes no assumptions about the linearity of relationships.

Stress values provide a measure of fit: - < 0.05: excellent - 0.05 - 0.10: good - 0.10 - 0.20: acceptable - > 0.20: poor (consider increasing k or using a different method)

The function uses multiple random starts (trymax) because NMDS can get stuck in local optima. The solution with the lowest stress is returned.

Examples

Basic NMDS ordination:

>>> import nuee
>>> species = nuee.datasets.varespec()
>>> nmds = nuee.metaMDS(species, k=2, distance="bray")
>>> print(f"Stress: {nmds.stress:.3f}")
Stress: 0.133

With custom parameters:

>>> nmds = nuee.metaMDS(species, k=3, distance="bray", trymax=50, trace=True)
Applying square root transformation
Applying Wisconsin double standardization
NMDS stress: 0.0869
NMDS converged

Visualize the ordination:

>>> import matplotlib.pyplot as plt
>>> fig = nuee.plot_ordination(nmds, display="sites")
>>> plt.show()

See also

NMDS: Lower-level NMDS class
rda: Redundancy Analysis (constrained ordination)
cca: Canonical Correspondence Analysis
pca: Principal Component Analysis

References

Redundancy Analysis (RDA).

RDA is a constrained ordination method that finds linear combinations of explanatory variables that best explain the variation in the response matrix.

Supplying Z fits a partial RDA: the effect of the conditioning variables is removed from both the response and the explanatory matrix before the constrained decomposition, and the inertia it accounts for is reported separately as partial_chi.

Parameters:

X – Response matrix (samples x species)
Y – Explanatory matrix (samples x variables)
Z – Conditioning matrix for partial RDA (optional)
formula – Formula string (e.g., “~ var1 + var2”)
data – DataFrame containing variables for formula
scale – Whether to scale species to unit variance
center – Whether to centre species column-wise
**kwargs – Additional parameters

Returns:

ConstrainedOrdinationResult with RDA results. Inertia is expressed as variance, and every component shares that scale, so partial_chi + sum(constrained_eig) + sum(unconstrained_eig) equals tot_chi (partial_chi being None for a non-partial fit). See inertia_partition() for the decomposition as a table.

Examples

# Simple RDA result = rda(species_data, environmental_data)

# RDA with formula result = rda(species_data, formula=”~ pH + temperature”, data=env_data)

# Partial RDA, conditioning on covariates result = rda(species_data, environmental_data, Z=conditioning_data) result.inertia_partition()

Canonical Correspondence Analysis (or CA when X is None).

Parameters:

Y – Species data matrix (sites x species).
X – Environmental data matrix (sites x variables) or DataFrame for formula evaluation. When None and no formula is given, an unconstrained Correspondence Analysis (CA) is performed.
formula – R-style formula string referencing columns in X.

Return type:

ConstrainedOrdinationResult (CCA) or OrdinationResult (CA).

nuee.ca(Y: ndarray | DataFrame, **kwargs) → OrdinationResult[source]¶

Correspondence Analysis (unconstrained).

Parameters:: Y – Species data matrix (sites x species).
Return type:: OrdinationResult with CA results.

nuee.pca(X: ndarray | DataFrame, n_components: int | None = None, scale: bool = True, center: bool = True, **kwargs) → OrdinationResult[source]¶

Principal Component Analysis.

Parameters:

X – Data matrix (samples x variables).
n_components – Number of components to keep.
scale – Whether to scale variables (unit variance) prior to analysis.
center – Whether to subtract column means prior to analysis.

Return type:

OrdinationResult with PCA results.

nuee.lda(X: ndarray | DataFrame, y: ndarray | Series, n_components: int | None = None, solver: str = 'svd', **kwargs) → OrdinationResult[source]¶

Linear Discriminant Analysis.

Parameters:

X (array-like) – Data matrix (samples x variables).
y (array-like) – Group labels for each sample.
n_components (int, optional) – Number of discriminant axes to keep. Defaults to min(n_classes - 1, n_features).
solver ({"svd", "eigen"}) – Solver for sklearn LDA. Default "svd". sklearn’s "lsqr" is rejected: it provides neither a transform nor discriminant scalings, so it cannot produce an ordination.

Returns:

points holds the discriminant scores and species the loadings, rescaled onto the score extent so biplot arrows stay visible whatever the units of X (the unscaled coefficients remain on result.raw_loadings). proportion_explained gives each retained axis’ share of the between-group variance across all axes, so it sums to less than 1 when n_components truncates the set.

Return type:

OrdinationResult

Fit environmental vectors to an ordination configuration.

Parameters:

ordination – OrdinationResult providing site scores.
env – Environmental data matrix (matching site order).
permutations – Number of permutations used for significance testing.
scaling – Scaling option passed to ordination.get_scores.
choices – Optional 1-based axis indices to include; defaults to all axes.
random_state – Seed for the permutation generator.

Returns:

Dictionary mirroring vegan’s envfit output layout with a vectors entry containing scores, r, r², and p-values.

Return type:

dict

nuee.ordistep(ordination: OrdinationResult, env: ndarray | DataFrame, direction: str = 'both', permutations: int = 199, p_enter: float = 0.05, p_remove: float = 0.1, max_steps: int = 50, random_state: int | None = None, **kwargs) → Dict[str, Any][source]¶

Stepwise model selection for constrained ordination.

Terms are added and/or dropped one at a time using permutation tests, in the manner of vegan’s ordistep. A candidate is tested as a constraint conditioned on the terms already retained, so each test is marginal.

Parameters:

ordination – A fitted constrained ordination (e.g. from nuee.rda()), used as the source of the response matrix.
env – Candidate explanatory variables, one per column.
direction – "forward" only adds terms, "backward" starts from the full set and only drops them, "both" alternates.
permutations – Permutations per test.
p_enter – A term is added when its p-value is at or below this.
p_remove – A retained term is dropped when its p-value rises above this.
max_steps – Safety bound on the number of add/drop rounds.
random_state – Seed, for reproducible selection.

Returns:

selected_variables (in the order chosen), p_values for those terms, the direction used, and the steps taken.

Return type:

dict

Raises:

ValueError – If direction is not one of the three accepted values, or the ordination carries no response matrix to select against.

nuee.procrustes(X: ndarray | DataFrame, Y: ndarray | DataFrame, scale: bool = True) → dict[source]¶

Procrustes analysis to compare two ordinations.

Parameters:

X – First ordination matrix
Y – Second ordination matrix
scale – Whether to scale configurations

Returns:

Dictionary with Procrustes results

Calculate diversity indices for community data.

This function provides a unified interface for calculating various diversity indices commonly used in ecology. It can calculate diversity for individual samples or for pooled groups.

Parameters:

x (np.ndarray or pd.DataFrame) – Community data matrix with samples in rows and species in columns. Values should be non-negative abundances or counts. Can also be a 1D array for a single sample.
index ({'shannon', 'simpson', 'invsimpson', 'fisher'}, default='shannon') – Diversity index to calculate: - ‘shannon’: Shannon entropy H’ = -sum(p_i * log(p_i)) - ‘simpson’: Gini-Simpson index 1 - sum(p_i^2) - ‘invsimpson’: Inverse Simpson 1 / sum(p_i^2) - ‘fisher’: Fisher’s alpha
groups (np.ndarray or pd.Series, optional) – Grouping factor for calculating pooled diversities. If provided, samples are pooled within each group before calculating diversity.
base (float, default=e) – Base of logarithm for Shannon index. Common choices: - e (natural log): nats - 2: bits - 10: dits

Returns:

Diversity values for each sample (or group if groups is provided). If input is a DataFrame, returns a pd.Series with sample/group names.

Return type:

float, np.ndarray, or pd.Series

Notes

Shannon diversity (H’) measures both richness and evenness: - Higher values indicate more diverse communities - Ranges from 0 (single species) to log(S) where S is species richness - Most common diversity index in ecology

Simpson’s index measures dominance: - We report the Gini-Simpson form (1 - sum(p_i^2)), matching vegan::diversity - Larger values indicate greater diversity - The inverse Simpson (1 / sum(p_i^2)) is available via index='invsimpson'

Fisher’s alpha assumes a log-series distribution: - Useful for abundance data - Less sensitive to sample size than richness - Can be slow for large datasets

Examples

Calculate Shannon diversity:

>>> import nuee
>>> species = nuee.datasets.varespec()
>>> div = nuee.diversity(species, index="shannon")
>>> print(f"Mean diversity: {div.mean():.3f}")
Mean diversity: 1.754

Calculate Simpson diversity:

>>> div_simp = nuee.diversity(species, index="simpson")

Calculate diversity for grouped samples:

>>> import numpy as np
>>> groups = np.array(['A', 'A', 'B', 'B', 'C', 'C'])
>>> div_grouped = nuee.diversity(species[:6], index="shannon", groups=groups)

Use different logarithm bases:

>>> div_bits = nuee.diversity(species, index="shannon", base=2)
>>> print("Diversity in bits:", div_bits.mean())
Diversity in bits: 2.5300454694165375

See also

adonis2: PERMANOVA using distance matrices
betadisper: Test for homogeneity of dispersions
mantel: Mantel test for matrix correlation

References

Convenience wrapper for distance-based PERMANOVA.

Parameters:

distance_matrix – Square or condensed distance matrix.
factors – Predictor variables supplied as a DataFrame/Series/array.
permutations – Number of permutations for the significance test.
random_state – Seed or Generator controlling permutation reproducibility.

Returns:

Same payload as permanova().

Return type:

dict

Analysis of similarities (ANOSIM).

Parameters:

distance_matrix – Square or condensed distance matrix.
grouping – Group assignments for each observation.
permutations – Number of permutations used to estimate the p-value. Set to 0 to skip.
random_state – Seed controlling permutation reproducibility.

Returns:

Dictionary with r_statistic, p_value and permutations.

Return type:

dict

Multi-Response Permutation Procedure (MRPP).

Parameters:

distance_matrix – Square or condensed distance matrix.
grouping – Group assignments for each observation.
permutations – Number of permutations for p-value estimation. Set to 0 to skip permutations.
random_state – Seed controlling permutation reproducibility.

Returns:

Contains delta (observed within-group distance), expected_delta (mean delta under permutations), a_statistic (chance-corrected agreement), p_value, and permutations.

Return type:

dict

Multivariate homogeneity of group dispersions.

Parameters:

distance_matrix – Square or condensed distance matrix, or original data matrix which will be converted via vegdist.
grouping – Group assignments for each observation.
permutations – Number of permutations for the ANOVA-like dispersion test (default: 999). Set to 0 to skip the permutation test.
random_state – Seed controlling permutation reproducibility.
distance_method – Distance metric when converting from raw data (default bray).

Returns:

distances: Series of distances to group centroids.
centroids: DataFrame of group centroids in PCoA space.
f_statistic / p_value: results of the dispersion test.
group_means: within-group mean distances.
permutations: number of permutations performed.

Return type:

dict

nuee.mantel(x: ndarray | DataFrame | Series, y: ndarray | DataFrame | Series, method: str = 'pearson', permutations: int = 999, random_state: int | Generator | None = None, **kwargs) → Dict[str, float | int | str][source]¶

nuee.mantel_partial(x: ndarray | DataFrame | Series, y: ndarray | DataFrame | Series, z: ndarray | DataFrame | Series, method: str = 'pearson', permutations: int = 999, random_state: int | Generator | None = None, **kwargs) → Dict[str, float | int | str][source]¶

Perform a Procrustean randomization test (PROTEST) between two ordinations.

Parameters:

x – Configuration matrices with matched observations (rows) and axes (columns).
y – Configuration matrices with matched observations (rows) and axes (columns).
permutations – Number of row permutations applied to y to approximate the null distribution. Set to 0 to skip permutation testing.
random_state – Seed or numpy RNG used for the permutation stream. When None the global numpy RNG is used.
scale – Forwarded to nuee.procrustes() to control symmetric scaling.

Returns:

Dictionary capturing the observed correlation, permutation p-value, number of permutations, and Procrustes transformation details.

Return type:

dict

Distance-based PERMANOVA (sequential sums of squares).

Parameters:

distance_matrix – Square or condensed distance matrix.
factors – DataFrame, Series, or array of predictor variables. Each column is treated as a separate term evaluated sequentially.
permutations – Number of permutations for significance testing. Set to 0 or None to skip permutation p-values.
random_state – Seed or Generator for reproducible permutations.

Returns:

Dictionary containing a result table (table), the total sum of squares, and the permutation F-statistics.

Return type:

dict

nuee.permtest(statistic_func: Callable, data: ndarray, permutations: int = 999, random_state: int | Generator | None = None, **kwargs) → dict[source]¶

General permutation test.

Parameters:

statistic_func – Function to calculate test statistic
data – Data array
permutations – Number of permutations
random_state – Seed or Generator, for a reproducible null distribution
**kwargs – Additional parameters

Returns:

Dictionary with test results

Permutation test for constrained ordination (RDA/CCA).

Partial ordinations are supported: the conditioning matrix is held fixed across permutations, and the degrees of freedom it consumes are removed from the residual, so the residual Df is n_samples - 1 - rank(constraints) - rank(conditioning).

Parameters:

ordination_result – Constrained ordination result (e.g., from nuee.rda()).
permutations – Number of permutations used to build the null distribution.
random_state – Optional random seed or Generator for reproducible results.

Returns:

Dictionary containing the ANOVA-style table and permutation details.

Return type:

dict

Permutation ANOVA for constrained ordination results.

Parameters:

ordination_result – Result object returned by nuee.rda() or nuee.cca().
permutations – Number of permutations used to approximate the null distribution.
random_state – Optional seed/Generator for reproducible permutations.

Returns:

Dictionary containing the ANOVA table and permutation metadata.

Return type:

dict

nuee.plot_ordination(result: OrdinationResult, axes: Tuple[int, int] = (0, 1), display: str = 'sites', choices: List[int] | None = None, type: str = 'points', groups: ndarray | Series | None = None, colors: List[str] | None = None, figsize: Tuple[int, int] = (8, 6), scaling: int | str | None = None, title: str | None = None, **kwargs) → Figure[source]¶

Plot ordination results.

Parameters:

result – OrdinationResult object
axes – Which axes to plot
display – What to display (“sites”, “species”, “both”)
choices – Alternative way to specify axes
type – Plot type (“points”, “text”, “none”)
groups – Grouping factor for coloring points
colors – Colors for groups
figsize – Figure size
**kwargs – Additional plotting arguments

Returns:

matplotlib Figure object

nuee.plot_diversity(diversity_data: ndarray | Series | DataFrame | DiversityResult, figsize: tuple = (8, 6), **kwargs) → Figure[source]¶

Plot diversity indices.

Parameters:

diversity_data – Diversity values
figsize – Figure size
**kwargs – Additional plotting arguments

Returns:

matplotlib Figure object

nuee.plot_dissimilarity(distance_matrix: ndarray | DataFrame, figsize: tuple = (8, 6), **kwargs) → Figure[source]¶

Plot dissimilarity matrix as heatmap.

Parameters:

distance_matrix – Distance/dissimilarity matrix
figsize – Figure size
**kwargs – Additional plotting arguments

Returns:

matplotlib Figure object

nuee.biplot(result: OrdinationResult, axes: Tuple[int, int] = (0, 1), scaling: str | int = 'species', correlation: bool = False, figsize: Tuple[int, int] = (10, 8), title: str | None = None, arrow_mul: float | None = None, n_species: int | None = 15, show_site_labels: bool = True, show_species_labels: bool = True, repel: bool = True, fontsize: int = 8, site_kw: Dict[str, Any] | None = None, species_kw: Dict[str, Any] | None = None, env_kw: Dict[str, Any] | None = None, groups: ndarray | Series | list | None = None, color_by: ndarray | Series | list | None = None, cmap: str | None = None, **kwargs) → Figure[source]¶

Create a biplot for ordination results.

For unconstrained ordination (PCA, CA, LDA), species loadings are drawn as arrows from the origin. For constrained ordination (RDA / CCA), species are shown as points and environmental variables as arrows.

Parameters:

result (OrdinationResult) – Ordination result object.
axes (tuple of int) – Which ordination axes to plot (0-indexed).
scaling (str or int) – Scaling mode: 1/”sites”, 2/”species”, 3/”symmetric”.
correlation (bool) – If True, use raw correlation values without auto-scaling.
figsize (tuple of int) – Figure size in inches.
title (str, optional) – Plot title.
arrow_mul (float, optional) – Manual multiplier for arrow length.
n_species (int or None) – Show only the top n_species by loading magnitude. None shows all species.
show_site_labels (bool) – Whether to display site name labels.
show_species_labels (bool) – Whether to display species name labels.
repel (bool) – Use adjustText for ggrepel-style label placement.
fontsize (int) – Base font size for labels.
site_kw (dict, optional) – Extra keyword arguments for site scatter points.
species_kw (dict, optional) – Extra keyword arguments for species scatter/arrows.
env_kw (dict, optional) – Extra keyword arguments for environmental arrows.
groups (array-like, optional) – Categorical group labels (one per site) for coloured scatter. Auto-detected from LDA results.
color_by (array-like, optional) – Continuous values (one per site) for colour-mapped scatter with a colourbar. Mutually exclusive with groups.
cmap (str, optional) – Matplotlib colormap name. Default is the colour cycle for groups (up to 10) and "viridis" for color_by.
**kwargs – Additional keyword arguments passed to site scatter.

nuee.ordiplot(result: OrdinationResult, axes: Tuple[int, int] = (0, 1), display: str = 'sites', figsize: Tuple[int, int] = (8, 6), scaling: int | str | None = None, **kwargs) → Figure[source]¶

Basic ordination plot.

Parameters:

result – OrdinationResult object
axes – Which axes to plot
display – What to display (“sites”, “species”, “both”)
figsize – Figure size
**kwargs – Additional plotting arguments

Returns:

matplotlib Figure object

nuee.plot_rarecurve(rarecurve_data: Dict[str, Dict[str, ndarray]], figsize: tuple = (10, 6), **kwargs) → Figure[source]¶

Plot rarefaction curves.

Parameters:

rarecurve_data – Rarefaction curve data
figsize – Figure size
**kwargs – Additional plotting arguments

Returns:

matplotlib Figure object

nuee.plot_specaccum(specaccum_data: Dict[str, ndarray], figsize: tuple = (8, 6), **kwargs) → Figure[source]¶

Plot species accumulation curves.

Parameters:

specaccum_data – Species accumulation data
figsize – Figure size
**kwargs – Additional plotting arguments

Returns:

matplotlib Figure object

nuee.ordiellipse(result: OrdinationResult, groups: ndarray | Series, axes: Tuple[int, int] = (0, 1), conf: float = 0.95, figsize: Tuple[int, int] = (8, 6), scaling: int | str | None = None, **kwargs) → Figure[source]¶

Add confidence ellipses to ordination plot.

Parameters:

result – OrdinationResult object
groups – Grouping factor
axes – Which axes to plot
conf – Confidence level for ellipses
figsize – Figure size
**kwargs – Additional plotting arguments

Returns:

matplotlib Figure object

nuee.ordispider(result: OrdinationResult, groups: ndarray | Series, axes: Tuple[int, int] = (0, 1), figsize: Tuple[int, int] = (8, 6), scaling: int | str | None = None, **kwargs) → Figure[source]¶

Add spider plots (lines from centroid to points) to ordination.

Parameters:

result – OrdinationResult object
groups – Grouping factor
axes – Which axes to plot
figsize – Figure size
**kwargs – Additional plotting arguments

Returns:

matplotlib Figure object

nuee.plot_betadisper(betadisper_result: dict, figsize: tuple = (8, 6), **kwargs) → Figure[source]¶

Plot beta dispersion results.

Draws one box per group of the distances to the group centroid, the same view as vegan’s boxplot.betadisper, with the group means marked and the permutation test reported in the title.

Parameters:

betadisper_result – Beta dispersion results, from nuee.betadisper()
figsize – Figure size
**kwargs – Additional arguments passed to Axes.boxplot

Returns:

matplotlib Figure object

Raises:

ValueError – if the result carries no per-observation grouping.

nuee.closure(mat: ndarray, *, out: ndarray | None = None) → ndarray[source]¶

Perform closure so that each composition sums to 1.

Parameters:

mat – A matrix where rows are compositions and columns are components.
out – Optional array where the result is stored.

Returns:

Matrix of proportions with non-negative entries that sum to 1 per row.

Return type:

numpy.ndarray

nuee.multiplicative_replacement(mat: ndarray, delta: float | None = None) → ndarray[source]¶: Replace structural zeros with a small non-zero value.

nuee.power(x: ndarray, a: float) → ndarray[source]¶: Raise each component to a power and renormalise via closure.

nuee.clr(mat: ndarray, ignore_zero: bool = False) → ndarray[source]¶: Compute the centred log-ratio transformation.

nuee.clr_inv(mat: ndarray) → ndarray[source]¶: Inverse centred log-ratio transformation.

nuee.inner(mat: ndarray) → ndarray[source]¶

Compute the inner product matrix in the Aitchison simplex.

The Aitchison inner product is (1/D) * sum_{i<j} log(x_i/x_j) log(y_i/y_j), and the identity sum_{i<j} log(x_i/x_j) log(y_i/y_j) = D * clr(x) . clr(y) makes that exactly the ordinary dot product of the clr coordinates. Dividing by D on top of the clr product would deflate every entry by that factor.

nuee.ilr(mat: ndarray, basis: ndarray | None = None) → ndarray[source]¶: Perform the isometric log-ratio transformation.

nuee.ilr_inv(mat: ndarray, basis: ndarray | None = None) → ndarray[source]¶: Inverse isometric log-ratio transformation.

nuee.alr(mat: ndarray, denominator_idx: int = -1) → ndarray[source]¶: Perform the additive log-ratio transformation.

nuee.alr_inv(mat: ndarray, denominator_idx: int = -1) → ndarray[source]¶

Inverse additive log-ratio transformation.

denominator_idx indexes the restored composition, which has one more component than mat. Negative indices are resolved against that wider result: np.insert counts a negative position from the end of the input, so passing -1 straight through would place the denominator second-to-last instead of last, and the transform would not round-trip.

nuee.sbp_basis(sbp: ndarray) → ndarray[source]¶: Construct an orthonormal basis from a sequential binary partition.

nuee.center(mat: ndarray) → ndarray[source]¶: Alias for centralize() kept for API parity.

nuee.centralize(mat: ndarray) → ndarray[source]¶: Center compositions by their geometric mean.

nuee.replace_zeros(X: ndarray | DataFrame, detection_limits: ndarray | None = None, delta: float | None = None) → ndarray | DataFrame[source]¶

Multiplicative zero replacement for compositional data.

Replaces zeros with a small value proportional to the detection limit (or column minimum of non-zero values) and adjusts non-zero entries so that each row sum is preserved exactly.

Parameters:

X (array-like or DataFrame, shape (n, D)) – Compositional data matrix. Zeros mark below-detection-limit values.
detection_limits (array-like of shape (D,), optional) – Per-component detection limits. When None, the column-wise minimum of strictly positive values is used as a proxy.
delta (float, optional) – Fraction of the detection limit used as the replacement value. Default is 0.65 (Martín-Fernández et al. 2003).

Returns:

Data with zeros replaced. Row sums match the input exactly.

Return type:

numpy.ndarray or DataFrame

References

nuee.impute_missing(X: ndarray | DataFrame, method: str = 'lrEM', max_iter: int = 100, tol: float = 0.0001, random_state: int | None = None) → ndarray | DataFrame[source]¶

Impute missing values in compositional data using the lrEM algorithm.

Uses the ALR (additive log-ratio) EM algorithm of Palarea-Albaladejo & Martín-Fernández (2008), matching the approach in R’s zCompositions package. Observed values are preserved exactly in the output.

Ideally one column should be fully observed (no NaN values) to serve as the ALR denominator. When no column is complete, the column with the fewest missing values is chosen and its gaps are pre-filled using row-proportional estimation from column-mean ratios before running EM.

Parameters:

X (array-like or DataFrame, shape (n, D)) – Compositional data matrix. NaN marks missing components. Observed (non-NaN) values must be strictly positive.
method ({"lrEM", "lrDA"}, default "lrEM") – "lrEM" returns the conditional expectation (deterministic). "lrDA" adds noise from the conditional covariance for multiple imputation / data augmentation.
max_iter (int, default 100) – Maximum number of EM iterations.
tol (float, default 1e-4) – Convergence tolerance on the relative change of the log-likelihood.
random_state (int, optional) – Seed for the random number generator (only used when method=”lrDA”).

Returns:

Completed data. Observed values are unchanged; imputed values are scaled consistently with the original observed components.

Return type:

numpy.ndarray or DataFrame

References

API Reference¶

nuee Package¶

nuee: Community Ecology Analysis in Python¶

Modules¶

nuee

Navigation

Related Topics