API configuration#

pycsamt.api is the front door of the package. It is a single import point that gathers three things every workflow needs:

Readers that turn field data into survey objects — read_edis(), read_edi(), read_sites().
Views that present tabular results for interactive work — the opt-in APIFrame / APIResult layer behind api=True.
Configuration for every runtime behaviour of the package — output directories, plot styles, axis conventions, CLI defaults, agent budgets — through one consistent configure_* / reset_* pattern.

Everything documented here is importable directly from pycsamt.api:

from pycsamt.api import (
    read_edis,            # data in
    configure_api_view,   # what api=True returns
    configure_pipe,       # where pipeline outputs go
    use_style,            # how figures look
)

configure_api_view(backend="pycsamt")
configure_pipe(output_root="results/run01", plot_dpi=200)
use_style("publication")

survey = read_edis("data/edi/", progress="auto")
print(survey.summary())        # APIFrame: compact, metadata-rich

One Pattern Everywhere#

Each behaviour family follows the same contract, so learning one family teaches you all of them:

Entry point	Role
`PYCSAMT_<FAMILY>`	Module-level singleton holding the current settings. Print it to see the active configuration.
`configure_<family>(**kw)`	Update settings with dotted-path keywords, e.g. `configure_style(mt__xy__color="#003f88")`.
`reset_<family>()`	Restore package defaults for the current session.
`use_<family>(preset)`	Where presets exist (styles, interpretation), apply a named preset in one call, e.g. `use_style("publication")`.

Configuration Families#

Family	Entry points	Controls
View layer	`configure_api_view()`, `PYCSAMT_API_VIEW`	What `api=True` returns: pyCSAMT views, pandas, or a custom wrapper.
Pipeline	`configure_pipe()`, `PYCSAMT_PIPE`	Output roots, plot DPI/format, progress display, step-error policy.
CLI	`configure_cli()`, `PYCSAMT_CLI`	Logging level, output format and directory, parallel build jobs.
Plot styles	`configure_style()`, `use_style()`, `PYCSAMT_STYLE`	MT component colours, multiline gradients, correction, rose, and phase-tensor ellipse styles. Presets: `pycsamt`, `publication`, `dark`.
Figure output	`save_fig()`, `set_dpi()`, `set_fmt()`, `set_savedir()`, `PLOT_CONFIG`	Global figure saving defaults: DPI, formats, output directory.
View controls	`configure_control()`, `wrap_phase()`, `PYCSAMT_CONTROL`	Apparent-resistivity and phase axis behaviour, frequency-axis direction, phase wrapping.
Sections	`configure_section()`, `PYCSAMT_SECTION`	Resistivity-section figure, axis, and colourbar styling.
Station rendering	`configure_station_rendering()`, `PYCSAMT_STATION_RENDERING`	Station map markers and axis styling.
Interpretation	`configure_interp()`, `use_interp()`, `PYCSAMT_INTERP`	Hydrogeological profile and section styles.
Topography	`configure_topo()`, `PYCSAMT_TOPO`	Topography handling and depth/frequency y-axis conventions.
Agents	`configure_agents()`, `AGENT_CONFIG`	LLM provider selection and spending budget for AI agents.

Besides the families above, pycsamt.api also exposes shared axis-label constants (STATION_LABEL, FREQUENCY_LABEL, PERIOD_LABEL, …) and the base objects (PyCSAMTObject, MetadataMixin) that carry metadata through workflows. To build your own classes on these bases — and inherit the MT math and EDI interop that come with them — see Extending pyCSAMT.

In This Section#

API Views: The opt-in view layer: api=True, APIFrame, multi-table APIResult containers, global backend policy, custom wrappers, and the public readers.
Configuration: The configuration system in depth: the dotted-path convention, worked examples for each family, recommended setups, environment variables, and how to reset everything.