API Reference

API Reference

This page summarizes the current public Python API exported by DAVINCI modules.

Configuration API

from davinci_monet.config import load_config, load_yaml

cfg = load_config("config.yaml")         # returns MonetConfig
raw = load_yaml("config.yaml")           # raw dict

Also available:

• validate_config, dump_config, config_to_yaml, merge_configs
• migrate_config, detect_config_version
• Schema models: MonetConfig, AnalysisConfig, ModelConfig, ObservationConfig, PlotGroupConfig, StatsConfig

Pipeline API

from davinci_monet.pipeline import run_analysis

result = run_analysis("config.yaml", show_progress=True)
print(result.success, result.total_duration_seconds)

Lower-level runner:

from davinci_monet.pipeline import PipelineRunner, PipelineContext

runner = PipelineRunner(show_progress=True)
context = PipelineContext(config=cfg.model_dump())
result = runner.run(context)

Models API

from davinci_monet.models import open_model, open_cmaq, open_wrfchem, open_ufs, open_cesm

m = open_model("/path/to/model/*.nc", mod_type="generic")

CESM helper:

from davinci_monet.models.cesm import compute_tropospheric_column

Observations API

from davinci_monet.observations import (
    # Surface
    open_airnow, open_aqs, open_aeronet, open_openaq, open_pandora,
    # Aircraft / Sonde
    open_icartt, open_ozonesonde,
    # Satellite L2 (validated)
    open_modis_l2_aod,
    # Lightning
    open_lma,
)

In development (readers exist, not yet validated — need averaging kernel support):

from davinci_monet.observations import (
    open_tropomi, open_tempo_l2_no2,                    # Satellite L2
    open_goes_l3_aod, open_mopitt_l3_co, open_omps_l3_o3,  # Satellite L3
    open_satellite_l2, open_satellite_l3,               # Generic
)

MODIS L2 reader

The MODISL2Reader reads HDF4 granules via monetio and bins them onto a target grid:

from davinci_monet.observations.satellite.modis_l2 import MODISL2Reader

reader = MODISL2Reader()
ds = reader.read_and_grid(files, variable_dict, lat_centers, lon_centers, start_time, end_time)

LMA reader

from davinci_monet.observations.lightning.lma import LMAReader, open_lma

obs = open_lma("/path/to/oklma/*.nc", variables=["flash_extent_density"], network="oklma")

Supported networks: oklma, colma, nalma (auto-detected from filename if not specified).

Pairing API

from davinci_monet.pairing import PairingEngine, PairingConfig

engine = PairingEngine()
cfg = PairingConfig(radius_of_influence=12000, time_tolerance="1h")
paired = engine.pair(model_ds, obs_ds, obs_vars=["o3"], model_vars=["O3"], config=cfg)

Swath-to-grid strategy

from davinci_monet.pairing.strategies.swath_grid import SwathGridStrategy

strategy = SwathGridStrategy()
paired = strategy.pair(model_data, satellite_data, grid_mode="match_model", time_resolution="1D")

Grid modes: match_model (default), resolution (uniform degrees), explicit (nlat/nlon).

Grid binning utilities

from davinci_monet.pairing.grid_binning import bin_swath_to_grid, edges_from_centers, normalize_grid

Numba-accelerated functions for binning 2D swath pixels into (time, lon, lat) grids.

Statistics API

from davinci_monet.stats import calculate_statistics, quick_stats, list_metrics

stats_df = calculate_statistics(paired_ds, "obs_o3", "model_o3")
available = list_metrics()

Additional classes/functions:

• StatisticsCalculator, StatisticsConfig
• compute_metric, get_metric
• write_statistics_csv, write_statistics_table, format_stats_summary

Plotting API

from davinci_monet.plots import get_plotter, list_plotters

plotter = get_plotter("scatter")
fig = plotter.plot(paired_ds, "obs_o3", "model_o3")

You can also use convenience functions like plot_scatter, plot_timeseries, plot_spatial_bias, etc.

Observation-only plotters

from davinci_monet.plots.renderers.obs import (
    FlightTrackMapPlotter,     # obs_flight_track: 2D Cartopy flight path maps
    VerticalProfilePlotter,    # obs_vertical_profile: altitude vs. concentration
    ObsTimeSeriesPlotter,      # obs_timeseries: variable vs. time
    ObsHistogramPlotter,       # obs_histogram: distribution with summary stats
    ObsLMADensityPlotter,      # obs_lma_density: gridded flash density maps
)

Obs-only plotters inherit from ObsPlotter (plots/obs_base.py) and accept a single xr.Dataset + variable name instead of paired data.

I/O API

from davinci_monet.io import read_dataset, read_mfdataset, write_dataset

Available readers include NetCDF, CSV, pickle, and ICARTT helpers.

Logging API

from davinci_monet.logging import configure_logging, get_logger

configure_logging(level="INFO")
logger = get_logger(__name__)

Note: current logging setup function is configure_logging (not setup_logging).