1.1. 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
...     configure_ordering,   # how survey stations are ordered
...     use_style,            # how figures look
... )

>>> configure_api_view(backend="pycsamt")
>>> _ = configure_pipe(output_root="results/run01", plot_dpi=200)
>>> _ = configure_ordering(mode="auto")
>>> use_style("publication")

>>> survey = read_edis("data/AMT/WILLY_DATA/L18PLT", progress="auto")
>>> print(survey.summary())        # APIFrame: compact, metadata-rich
APIFrame: edi_survey_summary
kind: edi.summary
shape: 28 rows x 6 columns
columns: station, path, n_freq, tipper, spectra, ts
numeric: 1 columns
missing: 0.0%
source: data/AMT/WILLY_DATA/L18PLT

1.1.1. 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")`.

1.1.2. 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.
Site ordering	`configure_ordering()`, `PYCSAMT_ORDERING`	Package-wide station order: validated coordinate chainage, input, natural station name, latitude, or longitude.
CLI	`configure_cli()`, `PYCSAMT_CLI`	Logging level, output format and directory, parallel build jobs.
Plot styles	`configure_style()`, `use_style()`, `PYCSAMT_STYLE` – Plot Styles	MT component colours, multiline gradients, correction, rose, and phase-tensor ellipse styles. Presets: `pycsamt`, `publication`, `dark`, `modem`.
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` – View Controls	Apparent-resistivity and phase axis behaviour, frequency-axis direction, phase wrapping.
Sections	`configure_section()`, `PYCSAMT_SECTION` – Section Plot Layout	Resistivity-section figure, axis, and colourbar styling.
Station rendering	`configure_station_rendering()`, `PYCSAMT_STATION_RENDERING` – Station Rendering	Station map markers and axis styling.
Interpretation	`configure_interp()`, `use_interp()`, `PYCSAMT_INTERP` – Interpretation Plot Styles	Hydrogeological profile and section styles.
Topography	`configure_topo()`, `PYCSAMT_TOPO` – Terrain-Following Coordinates	Topography handling and depth/frequency y-axis conventions.
Mesh display	`configure_mesh()`, `draw_mesh()`, `draw_tri_mesh()`, `PYCSAMT_MESH` – Mesh Display	Rectilinear and triangular mesh rendering: filled, reviewed (fill + edges), or diagram (edges only) presets, shared by both mesh families.
Agents	`configure_agents()`, `AGENT_CONFIG` – Agent Configuration	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.

1.1.3. 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.
Mesh Display: Rendering computational and inversion meshes: the shared "filled"/ "review"/"diagram" preset system, rectilinear vs. triangular mesh drawing, and dotted-path style configuration.
Plot Styles: Plot styles in depth: MT component colours, multiline gradients, correction pairs, raw-data style, phase-tensor ellipses, rose diagrams, and the four named presets.
Interpretation Plot Styles: Hydrogeophysical plot styles: section and profile colours, the four presets, and why these plot classes track live configuration changes without an explicit style hand-off.
Agent Configuration: AGENT_CONFIG in the family lineup, with a fast quick-reference; points to Agent And LLM Configuration for the full guide.
Section Plot Layout: Section-plot figure sizing, axis direction, and the topography- awareness gate shared by every pseudosection and inversion section.
Station Rendering: Station tick marks, the adaptive label-thinning algorithm, and terrain-following marker placement.
View Controls: Apparent-resistivity scale, phase wrapping, and the frequency/period axis convention read by most pycsamt.emtools plotting functions.
Configuration: The configuration system in depth: the dotted-path convention, worked examples for each family, recommended setups, environment variables, and how to reset everything.