slv.inversion.config.InversionConfig

class slv.inversion.config.InversionConfig(tstart='2015-06-01', tend='2025-02-01', flux_freq='MS', utc_offset=-7, subset_hours=<factory>, xmin=-112.2, xmax=-111.75, ymin=40.45, ymax=40.93, dx=0.05, dy=0.05, sites=<factory>, mobile_obs=None, filter_pcaps=True, filter_spikes=False, spike_percentile=0.9, background='rolling', background_kwargs=<factory>, aggregate_obs=False, location_site_map=<factory>, prior='epa', prior_kwargs=<factory>, stilt_project=<factory>, variant=None, sparse_jacobian=True, prior_base_std=0.019, prior_std_frac=0.5, prior_time_scale='32d', prior_spatial_scale=5.0, mdm_config=<factory>, bias_std=None, bias_grouping=None, jacobian_coverage_percentile=None, min_obs_per_interval=60, gamma=None, cache=False, cache_overwrite=<factory>, num_processes=8, plot_inputs=True, plot_results=True, plot_diagnostics=False, output_units='Gg/m2/s', tiler=<factory>, tiler_zoom=10)

Settings for one inversion (run()).

Invalid choices (flux_freq, background, prior, bias_grouping, MDM component names, an empty domain, tstart or tend off the flux_freq boundaries) raise ValueError at construction. Cached components are keyed on the fields each one depends on (see slv.inversion.cache), so changing a field’s default spelling forces a rebuild.

Parameters:

• tstart (str or pd.Timestamp) – Inversion period; flux intervals start at tstart and the last one ends at tend, so both must be on flux_freq boundaries (see flux_time_bins).

• tend (str or pd.Timestamp) – Inversion period; flux intervals start at tstart and the last one ends at tend, so both must be on flux_freq boundaries (see flux_time_bins).

• flux_freq (str) – Flux interval: "YS", "QS", "MS", "2W" or "D".

• utc_offset (int) – Hours from UTC to local standard time, for subset_hours.

• subset_hours (list of int) – Local hours of obs to keep (default 12-16, a well-mixed afternoon boundary layer).

• xmin (float) – Domain in degrees (default slv.domain). Snapped outward to whole cells, see state_grid.

• xmax (float) – Domain in degrees (default slv.domain). Snapped outward to whole cells, see state_grid.

• ymin (float) – Domain in degrees (default slv.domain). Snapped outward to whole cells, see state_grid.

• ymax (float) – Domain in degrees (default slv.domain). Snapped outward to whole cells, see state_grid.

• dx (float) – Cell size in degrees.

• dy (float) – Cell size in degrees.

• sites (list of str) – Sites from the site config. A mobile site (e.g. "trx01") takes its obs per TRAX receptor.

• mobile_obs (str or Path, optional) – Receptor-paired obs for the mobile sites (parquet indexed (obs_location, obs_time), from trax_receptor_observations()).

• filter_pcaps (bool) – Drop obs during persistent cold-air pool events.

• filter_spikes (bool) – Drop days whose within-hour CH4 std is above spike_percentile. Superseded by the subhour MDM term, which keeps those days and down-weights them.

• spike_percentile (float) – Percentile threshold for filter_spikes.

• background (str) – "rolling" (baseline from the stationary sites), "gml" or "ct_stilt".

• background_kwargs (dict) – Passed to the background loader (e.g. csv_path for ct_stilt).

• aggregate_obs (bool or str) – False, or a frequency (e.g. "1D") to average obs and Jacobian rows to.

• location_site_map (dict) – STILT location id -> site. Empty: matched from the site config coordinates.

• prior (str) – "epa", "edgar" or "constant", see get_slv_prior().

• prior_kwargs (dict) – Passed to the prior loader (e.g. {"express": True}).

• stilt_project (str, Path, or list of str or Path) – PYSTILT project(s) holding the footprints ($SLV_STILT_DIR, else DEFAULT_STILT_PROJECT). A list builds one Jacobian from several projects, e.g. the paper-1 project (UOU, DAQ) and the TRAX project: each contributes the rows for the obs it has footprints for (stilt_projects).

• variant (str, optional) – PYSTILT variant whose footprints make the Jacobian ("hrrr"); every project in stilt_project must define it. None takes each project’s one variant with a footprint. The cache key sees this value, not what None resolved to, so set it explicitly.

• sparse_jacobian (bool) – Keep the Jacobian sparse.

• prior_base_std (float) – Prior error std per cell, prior_base_std + prior_std_frac * prior (umol/m2/s).

• prior_std_frac (float) – Prior error std per cell, prior_base_std + prior_std_frac * prior (umol/m2/s).

• prior_time_scale (str) – e-folding time of the prior error correlation (e.g. "32d").

• prior_spatial_scale (float) – e-folding distance of the prior error correlation, km.

• mdm_config (dict) – Overrides of DEFAULT_MDM_CONFIG, by component name.

• bias_std (float, optional) – Prior std of the bias states (ppm); None leaves the bias block out.

• bias_grouping (str, optional) – None / "time" (one bias per interval), "site" or "site_group" (per interval and site or organization).

• jacobian_coverage_percentile (float, optional) – Hold the least-constrained cells (below this percentile of mean Jacobian sensitivity) at the prior. None keeps every cell.

• min_obs_per_interval (int) – Drop flux intervals with fewer obs.

• gamma (float, optional) – Divides the obs error (> 1 fits the data more closely).

• cache (bool, str or Path) – False: no cache; True: the working directory; else that directory.

• cache_overwrite (str or list of str) – Components to rebuild (e.g. ["obs"]), or "all".

• num_processes (int) – Workers for obs loading and the Jacobian build.

• plot_inputs (bool) – Which plots run() draws.

• plot_results (bool) – Which plots run() draws.

• plot_diagnostics (bool) – Which plots run() draws.

• output_units (str) – Flux units for domain totals (e.g. "Gg/m2/s" gives Gg per interval).

• tiler (GoogleTiles) – Map tiles for the plots.

• tiler_zoom (int) – Map tiles for the plots.

Attributes

background_kwargs_key	a csv_path (the ct_stilt product) is replaced by its path plus size and mtime.
bbox	(xmin, ymin, xmax, ymax).
extent	(xmin, xmax, ymin, ymax), cartopy's order.
flux_time_bins	whole flux_freq periods from tstart to tend.
flux_times	Returns the left edges of the flux time bins, which represent the time points for flux estimation.
grid	the prior's regrid target.
grid_coords	Every cell centre as a (lon, lat) tuple.
map_extent	extent padded by 0.05 degrees, for maps.
mdm_components	Build MDM components from config (merges with defaults).
mobile_obs_key	its path plus size and mtime.
resolution	Cell size as "{dx}x{dy}".
site_config	The packaged site config (load_site_config()).
state_grid	the domain snapped outward to whole cells.
stilt_projects	stilt_project as a list of paths, whether one project or several was given.
subset_hours_utc	Dynamically converts local afternoon hours to UTC for data subsetting.
time_range	(tstart, tend) as timestamps.