BayeSpace

Bayesian regression and Gaussian-process inference for spatial environmental models, built on NumPyro and JAX. Write the forward model as an equation, attach priors parameterised by their modes, sample with NUTS, and get every run saved with its configuration so it can be reloaded rather than repeated.

BayeSpace was written for the PhD thesis BayeSpace: applying Bayesian statistics to environmental and ecological phenomena (S. Davis, University of Sydney, 2025). Its two case studies are the inference of Gaussian-plume dispersion coefficients from drone transects of a marine cloud brightening plume, and Gaussian-process species-distribution models. Release v0.1.0 is the commit used for the dispersion paper; v0.2.0 adds packaging, tests and the fixes listed in the changelog.

Install

pip install git+https://github.com/cradsdavis-cell/BayeSpace.git

or, for development:

git clone https://github.com/cradsdavis-cell/BayeSpace.git
cd BayeSpace
pip install -e ".[test]"
pytest

Python 3.10 or later. CPU JAX is installed by default; follow the JAX instructions for GPU builds. Data and results are written under data/ and results/ in the current working directory.

Quickstart

Simulate a noisy line, infer its slope and intercept, and plot the diagnostics.

import pandas as pd
from regression_toolbox.model import Model
from regression_toolbox.likelihood import Likelihood
from regression_toolbox.parameter import Parameter
from regression_toolbox.sampler import Sampler
from visualisation_toolbox.domain import Domain
from visualisation_toolbox.visualiser import RegressionVisualiser
from data_processing.sim_data_processor import SimDataProcessor

# a forward model is an equation string registered in models.json ('line' is y = a*x + b)
truth = Model('line').add_fixed_model_param('a', 1).add_fixed_model_param('b', 1)
domain = Domain(1, 'linear').add_domain_param('min', 0).add_domain_param('max', 100).add_domain_param('n_points', 50)
domain.build_domain()
data = SimDataProcessor('linear_example', truth, domain, noise_dist='gaussian', noise_level=1)

a = Parameter(name='a', prior_select='gaussian').add_prior_param('mu', 1).add_prior_param('sigma', 1)
b = Parameter(name='b', prior_select='gaussian').add_prior_param('mu', 1).add_prior_param('sigma', 1)
sigma = Parameter(name='sigma', prior_select='uniform').add_prior_param('low', 0.0001).add_prior_param('high', 5)

sampler = Sampler(pd.Series({'a': a, 'b': b, 'sigma': sigma}), Model('line'), Likelihood('gaussian'), data,
                  n_samples=10000, n_chains=3)
samples, chain_samples, fields = sampler.sample_all()   # reloads if this exact configuration has run before

vis = RegressionVisualiser(sampler)
vis.get_traceplots(); vis.get_autocorrelations()
vis.plot_posterior('a', [-2, 2]); vis.show_predictions(domain, 'predictions', '1D')

Register your own model with add_model(name, expression, independent_variables, dependent_variable, parameters) from regression_toolbox.model; expressions are parsed by SymPy and compiled to JAX. Multivariate and mixture priors (for example a log-normal mixture with one mode per Pasquill-Gifford class) are built with Parameter(name=[...], prior_select='log_norm', multi_mode=True); see the plume notebook.

Notebooks

• notebooks/Bayesian Regression example.ipynb: lines, polynomials, planes and a nonlinear surface.
• notebooks/Gaussian Process Regression example.ipynb: kernels and transformations.
• notebooks/Case study 1 - Gaussian Plume Modeling.ipynb: the marine cloud brightening inference.
• notebooks/Case study 2 - Species Distributions.ipynb, Case study 3 - Source Detection of Plume.ipynb.

The plume case study needs the Great Barrier Reef drone data, which are not distributed with this repository; its RawDataProcessor call expects data/raw_data/GBR_data.csv and GBR_data_summary.csv.

Docker

run_bayespace.ps1 builds a container with the repository and a conda environment and mounts data/ and results/; attach VS Code with Dev Containers: Attach to Running Container. This is the route the thesis work used and is kept for that reason; pip install is the simpler path.

Layout

Package	Holds
regression_toolbox	Model (equation strings to JAX), Parameter (priors), Likelihood, Sampler (NUTS, save and reload)
gaussian_process_toolbox	GP, Kernel, Transformation on scikit-learn kernels
data_processing	SimDataProcessor, RawDataProcessor, BoxGridder (cuboid averaging of field points)
visualisation_toolbox	Domain builders and the RegressionVisualiser / GPVisualiser plotting

Citing

Davis, S. (2025). BayeSpace: applying Bayesian statistics to environmental and ecological phenomena. PhD thesis, University of Sydney. Software: https://github.com/cradsdavis-cell/BayeSpace (moved from samcd22/BayeSpace in September 2026), release v0.1.0 for the dispersion analysis.

Licence

MIT. See LICENSE.