Skip to content

Python API

Reference for the main public classes and functions, generated from the source docstrings. For usage, see the User Guide and Data pages.

Entry points and configuration

sopran.config.use(*, store=None, data_root=None, cache_root=None, project=None, project_root=None, artifact_root=None, download=None, frame=None, cache=None, backends=None)

Set process-local defaults for spn.kaguya, spn.view(), and Store().

sopran.config.using(*, store=None, data_root=None, cache_root=None, project=None, project_root=None, artifact_root=None, download=None, frame=None, cache=None, backends=None)

Temporarily set process-local defaults inside a with block.

sopran.config.save_user(*, store=None, data_root=None, cache_root=None, project=None, project_root=None, artifact_root=None, download=None, frame=None, cache=None, backends=None)

Persist user-level defaults to the SOPRAN config file.

sopran.core.config.resolve_store_roots(root=None, cache_root=None, *, project_root=None)

Resolve the Store data root and cache root for every entry point in one order.

Each root is taken from the argument, the session (spn.config.use), the environment (SOPRAN_DATA_ROOT / SOPRAN_CACHE_ROOT), the project [store] table, and the user [store] table, in that order. The data root falls back to <project root>/sopran_data and the cache root to <data root>/cache. project_root defaults to :func:default_project_root, so Store() and spn.kaguya resolve to the same Store.

sopran.core.config.resolve_download_mode(value=None, *, case_value=None, project_root=None)

Resolve the download policy for every entry point in one order.

An explicit value wins, then spn.config.use(download=...), then the environment (SOPRAN_OFFLINE forces never, else SOPRAN_DOWNLOAD_MODE), then file settings: a project case, the project [defaults], and the user [defaults]. The fallback is missing. Environment variables outrank files so that an offline compute node stays offline whatever a config says. project_root defaults to :func:default_project_root.

sopran.core.config.default_project_root()

Root of the default project used by spn.kaguya, spn.view() and Store().

The session project= wins, then the nearest sopran.toml above the current directory, then [project].root in the user config, then the current directory.

sopran.core.view.view(**parameters)

sopran.core.loaders.load(dataset_id, time, *, store=None, **kwargs)

Load a dataset by stable string ID.

The ID is the attribute path below a registered source, so load("kaguya.esa1.counts", time) equals spn.kaguya.esa1.counts.load(time). The object API remains the primary interface; this helper is for CLI, batch, and power-user dispatch.

Time ranges

sopran.core.time.TimeRange dataclass

Half-open UTC time range used by SOPRAN public APIs.

days()

Return UTC day labels touched by this half-open interval.

sopran.core.time.period(start, stop)

Create a half-open UTC period [start, stop).

sopran.core.time.day(value)

sopran.core.time.month(value)

sopran.core.time.year(value)

Analysis conditions

sopran.core.view.View dataclass

A lightweight lens that binds selection and context to the data tree.

view.kaguya and the other registered sources are real mission objects whose endpoints default to this view's time, region, download policy and SPICE kernels.

source(name)

Return the registered source name bound to this view's time and context.

sopran.core.view.ViewSelection dataclass

Scientific subset selected by a SOPRAN view.

sopran.core.view.ViewContext dataclass

Execution context for delegated libraries and derived products.

sopran.core.project.Project

Analysis workspace that supplies case context to mission objects.

kaguya property

KAGUYA bound to the project defaults (no time); see view(time=...).

sopran.core.project.Case

view property

The case as a view; its sources are reused across attribute access.

sopran.core.project.ProjectArtifact dataclass

sopran.core.project.ProjectCaseRecord dataclass

Data

sopran.core.data.SopranArray dataclass

Thin variable object for loaded SOPRAN data.

sopran.missions.kaguya.mission.Kaguya

Object-oriented entry point for KAGUYA/SELENE public data.

from_view(view) classmethod

Build a mission whose endpoints default to the view's time and context.

sopran.missions.kaguya.data.KaguyaPaceData dataclass

ion_distribution(*, count_correction='none', angles='info', efficiency=PACE_DEFAULT_EFFICIENCY)

IMA/IEA 3-D distributions per record type.

Returns :class:~sopran.missions.kaguya.ion3d.PaceIon3D keyed by record type.

Load with calibration=kg.ima.load_calibration() (or kg.iea) first.

pitch_angle_spectrum(magnetic_field, *, value='counts', pitch_bins='native', look_frame='SELENE_M_SPACECRAFT', magnetic_frame=None, min_look_bins=1, count_correction='none', frame_context=None, cache='never', store=None, variant_id=None, dataset_id=None, layer='features')

Return PACE spectra binned by pitch angle.

The result has dimensions time x energy x pitch_angle. look is resolved through the PACE angle calibration tables, not treated as a physical direction by itself.

sopran.missions.artemis.mission.Artemis

Object-oriented entry point for ARTEMIS probes (P1 = THEMIS-B, P2 = THEMIS-C).

from_view(view) classmethod

Build a mission whose endpoints default to the view's time, Store and policy.

sopran.missions.lunar_prospector.mission.LunarProspector

Entry point for Lunar Prospector MAG/ER Level 1B data (1998-01-16 to 1999-07-29).

from_view(view) classmethod

Build endpoints that default to the view's time, Store and download policy.

sopran.missions.omni.hourly.Omni

OMNI2 hourly access with Store caching and optional view-bound time.

hro property

5-minute HRO access (velocity vector in GSE) sharing this Store and download policy.

hro2 property

5-minute HRO2 access (definitive Wind/SWE plasma) sharing this Store.

hro2_1min property

1-minute HRO2 access (definitive Wind/SWE plasma) sharing this Store.

hro_1min property

1-minute HRO access sharing this Store and download policy.

at(times, *, download=None)

Match containing UTC hours, without interpolation or filling missing hours.

from_view(view) classmethod

Build OMNI access whose loads default to the view's time.

high_resolution(resolution='5min', *, product='hro')

HRO or HRO2 access at resolution ("1min" or "5min").

sopran.bodies.moon.Moon

Body-first entry point for Moon map products.

from_view(view) classmethod

Build Moon endpoints that default to the view's region, time, kernels and Store.

magnetic_anomalies(catalog='blewett2011', *, name=None, near=None, radius_deg=None)

List literature anomalies; near=(east longitude, latitude) in degrees.

Catalogs: 'blewett2011' (corrected), 'oliveira2017', or 'all'. Fields are regional peak nT at 30 km; radii are inversion domains. See magnetic_anomalies.magnetic_anomalies for columns and limitations.

sopran.maps.Region dataclass

Plotting

sopran.core.plotting.PlotItem dataclass

sopran.core.plotting.PlotStack dataclass

sopran.core.plotting.PlotResult dataclass

sopran.core.plotting.QuicklookResult dataclass

sopran.core.pages.InfoPage dataclass

sopran.core.pages.GuidePage dataclass

Time alignment

sopran.core.alignment.TimeBins dataclass

sopran.core.alignment.SampleTable dataclass

Build a feature table with product-specific time alignment rules.

sopran.core.alignment.SampleSpec dataclass

One input series and its alignment rule for a sampled feature table.

sopran.core.alignment.AlignmentResult dataclass

sopran.core.alignment.FeatureMatrix dataclass

Coordinate frames

sopran.frames.FrameContext dataclass

Coordinate-frame context for SOPRAN products.

This is intentionally a thin adapter boundary. Kernel-backed and model-backed transforms are delegated to established libraries in later implementations; the current implementation records provenance and supports identity transforms.

transform_vectors(vectors, *, times, source_frame, target_frame, backend=None, missing='error')

Transform one or more 3-D vectors between coordinate frames.

Non-identity transforms are delegated to SPICE through spiceypy. SPICE kernels must already be supplied through FrameContext(spice_kernels=...).

sopran.frames.FrameTransformPlan dataclass

sopran.frames.normalize_frame(frame)

Store

sopran.core.store.Store dataclass

Filesystem roots used by SOPRAN data discovery and products.

dataset_records(*, layer=None)

Every dataset (manifest) in the Store, optionally of one layer.

file_reference(path)

Portable reference to a file: Store-relative path when inside the Store, otherwise only an external hint; identity is the content checksum.

rebuild(*, layer=None)

Rebuild every dataset catalog from shard sidecars, then the registries.

Run after copying datasets between machines (e.g. with rsync).

register_dataset(*, dataset_id, layer, variant_id=None, variant=None, mission, instrument, product, schema, time_coverage, source_files=(), source_datasets=(), shards=(), producer='sopran', provenance=None, status='candidate', parameters=None, context=None, storage_layout=None, dataset_version='1', partitioning=(), managed=False, _prune_shard_sidecars=True)

Write manifest, schema and catalog; shards is the complete shard list.

managed=True marks datasets that sopran creates and reuses on its own (caches and pipeline products with content-derived variants); they are synchronized by default. Shard sidecars not in shards are removed.

write_parquet_dataset(*, dataset_id, layer, variant_id=None, variant=None, mission, instrument, product, schema, time_coverage, frame, source_files=(), source_datasets=(), shard_path='shards/part-000.parquet', compression='zstd', overwrite=False, append=False, producer='sopran', provenance=None, parameters=None, context=None, status='candidate', dataset_version='1', partitioning=(), managed=False)

Write one shard; append keeps the other shards (catalog and sidecars).

Appends never delete other shards' sidecars, so concurrent writers of the same dataset lose at most catalog rows, which rebuild_catalog restores.

sopran.core.store.DatasetRecord dataclass

files()

Files of this dataset, excluding nested datasets, work/ and temporaries.

rebuild_catalog()

Rebuild catalog.parquet from shard sidecars merged with the catalog.

Sidecars win over catalog rows for the same path; catalog-only rows are kept and receive sidecars, so datasets written before sidecars existed are migrated. Use after copying shards from another machine or job.

verify_shards()

Compare complete shards of catalog and sidecars with the files on disk.

Returns lists of shard paths that are missing, have a different checksum, or are known only to the catalog or only to sidecars (rerun rebuild_catalog for the latter two, e.g. after a sync).

sopran.core.database.Database dataclass

sopran.core.database.ProductRef dataclass

sopran.core.events.EventCatalog dataclass

counts(*, freq, by=(), time=None)

Count event onsets, grouped into UTC calendar bins.

rates(exposure, *, freq, by=('phenomenon',), time=None, exposure_column='exposure_seconds', scale=3600.0)

Join event counts to detector-specific exposure bins.

exposure is a long table with bin_start, bin_stop, the requested grouping columns, and an exposure duration. Exposure rows are the left side of the join so bins with zero detected events are retained. Events are counted by time_start. When time is supplied it must cover complete calendar bins, because pre-aggregated exposure cannot be clipped safely to a partial bin.

Batch pipelines

sopran.core.pipeline.Pipeline dataclass

sopran.core.pipeline.PipelineBackend

Executes the pipelines of one data source.

A data endpoint's pipeline(time) attaches its backend. Subclasses override the operations their source supports; the rest raise :class:PipelineError. stream_pipeline falls back to splitting scan_pipeline by day.

sopran.core.pipeline.PipelineResult dataclass

Schemas

sopran.core.schema.InstrumentSchema dataclass

sopran.core.schema.VariableSchema dataclass

default_yscale(y)

Default axis scale for coordinate y: "log" when listed in log_dims.

sopran.core.schema.validate_schema(data, schema, *, variables=None)

Validate that data exposes the selected schema variables.

sopran.schema_docs.builtin_schemas()

sopran.schema_docs.schema_reference_markdown(schemas=None, *, language='ja')

Registering data sources

sopran.core.sources.register_source(name, factory)

Register factory ("module:attribute.path") as the source name.

The factory is imported on first use and called as factory(view). It must return a source object bound to that view's time, region and context.

sopran.core.sources.source_names()

Names of the registered sources, in registration order.

Exceptions

sopran.core.errors

BackendError

Bases: SopranError, RuntimeError

Raised when an external or Rust backend stage fails.

ConfigError

Bases: SopranError, ValueError

Raised when configuration cannot be resolved or validated.

DatasetNotFoundError

Bases: SopranError, LookupError

Raised when a requested dataset or shard is not available.

DecodeError

Bases: SopranError, ValueError

Raised when mission data decoding fails.

DownloadError

Bases: SopranError, OSError

Raised when raw data download or local acquisition fails.

FrameTransformError

Bases: SopranError, ValueError

Raised when coordinate or frame transformation fails.

PipelineError

Bases: SopranError, RuntimeError

Raised when pipeline planning or execution fails.

SchemaError

Bases: SopranError, ValueError

Raised when data does not match a SOPRAN schema.

SopranError

Bases: Exception

Base class for SOPRAN public exceptions.