Tutorials

These tutorials provide step-by-step guides for common BING workflows.

Getting Started

If you’re new to BING, we recommend starting with these tutorials in order:

basic_fitting - Learn the fundamentals of fitting bio-optical models
pace_processing - Process PACE OCI data
argo_matching - Match satellite data with Argo floats
model_comparison - Compare different model formulations
uncertainty_analysis - Quantify uncertainties in retrieved parameters
visualization - Create publication-quality figures

Tutorial Format

Each tutorial includes:

Objectives - What you’ll learn
Prerequisites - Required knowledge and data
Code examples - Complete, runnable code
Expected output - What results to expect
Exercises - Practice problems to test understanding

Example Data

Tutorial data can be downloaded from:

PACE OCI sample data: NASA Earthdata
Argo BGC profiles: Argo Data Management
Loisel et al. (2023) synthetic dataset: Included in BING

Jupyter Notebooks

Interactive Jupyter notebooks for all tutorials are available in the BING repository.

To run the notebooks:

git clone https://github.com/yourusername/bing.git
cd bing/notebooks
jupyter notebook

Quick Examples

Basic Fitting Example

import numpy as np
from bing.parameters import standard
from bing.models import utils as model_utils
from bing.fitting import chisq_fit

# Setup
wavelengths = np.arange(400, 701, 10)
params = standard.expb_pow()
models = model_utils.init(params.model_names, wavelengths)

# Simulate data (replace with real data)
true_params = [0.01, 0.65, 0.015, 0.001]
Rrs_true = models[0].eval(true_params[:2]) + models[1].eval(true_params[2:])
Rrs_noise = Rrs_true + np.random.normal(0, 0.0005, len(wavelengths))
Rrs_unc = np.full_like(Rrs_noise, 0.0005)

# Fit
result = chisq_fit.fit(models, wavelengths, Rrs_noise, Rrs_unc)
print(f"Fitted: {result['x']}")
print(f"True:   {true_params}")

PACE Processing Example

from ocpy.pace import io as pace_io
import fitting as m_fitting
import pandas as pd

# Load matched data
matched = pd.read_csv('matched_argo_bgc_profiles.csv')

# Process first match
imatched = matched.iloc[0]
outfile = f"fits/{imatched.cruise}_{imatched.profile:03d}.npz"

# Run fitting
m_fitting.doit(imatched, outfile)

# Load results
results = np.load(outfile)
print(f"Available data: {list(results.keys())}")

Visualization Example

from bing import plotting
import matplotlib.pyplot as plt

# After fitting...
plotting.show_fits(
    models, chains,
    Chl=1.5, Y=443,
    Rrs_true={'wave': wavelengths, 'spec': Rrs_measured},
    perc=(16, 84),
    savefig='fit_results.png'
)
plt.show()

Common Issues

Memory errors with large datasets: Use data chunking or reduce MCMC steps
Convergence failures: Check initial parameters and adjust bounds
Missing dependencies: Ensure all required packages are installed
Authentication errors: Configure NASA Earthdata credentials

Support

For tutorial-specific questions:

Check the FAQ section in each tutorial
Post issues on GitHub
Contact the BING development team

Video Tutorials

Video walkthroughs of key tutorials are available on our YouTube channel.

Contributing Tutorials

We welcome community-contributed tutorials! See /contributing for guidelines on submitting new tutorials.