2.4. Configure a first session#

pyCSAMT works with its defaults, so configuration is not a prerequisite for loading a first survey. For a reproducible project, however, make three choices explicit near the beginning of the script or notebook:

  • how stations are ordered;

  • where generated figures are written;

  • which visual style is used.

These settings are process-local. They affect subsequent calls in the current Python process but do not rewrite the field data. The complete configuration system—including views, pipelines, meshes, sections, interpretation, CLI, and agents—is documented in Configuration.

2.4.1. Start with a small explicit setup#

The following setup preserves the loader’s station order and gives figures a predictable destination and appearance:

>>> from pycsamt.api import (
...     PLOT_CONFIG,
...     PYCSAMT_ORDERING,
...     configure_ordering,
...     set_dpi,
...     set_savedir,
...     use_style,
... )
>>> configure_ordering(mode="input")
SiteOrderingConfig(mode='input', min_linearity=0.95, max_cross_track_ratio=0.15, min_coordinate_fraction=0.6)
>>> use_style("pycsamt")
>>> set_savedir("results/figures")
>>> set_dpi(200)
>>> PYCSAMT_ORDERING.mode
'input'
>>> PLOT_CONFIG.savedir, PLOT_CONFIG.dpi
('results/figures', 200)

mode="input" is a conservative first-survey choice because the returned row order follows file discovery. It is reproducible only when the input file list itself is reproducible. When filenames do not reflect profile position, use the ordering modes described below after validating the coordinates.

set_savedir establishes a default for plotting functions that honor the global figure configuration. It does not create a scientific project layout or force every third-party Matplotlib call into that directory. Pass an explicit output path when a function documents one.

2.4.2. Choose station ordering deliberately#

Station order controls how survey rows and profile plots correspond to physical locations. The main choices are:

Mode

Use it when

"input"

The supplied file or object sequence already has the required order.

"station"

Station identifiers encode the desired numeric order, such as S2 before S10.

"latitude" or "longitude"

A cardinal coordinate direction represents the profile adequately.

"chainage"

Valid coordinates define a survey line and order should follow distance projected along it.

"auto"

pyCSAMT may use coordinate-derived chainage when the geometry passes its single-line checks, otherwise preserving input order.

Automatic ordering is convenient, but it cannot detect every coordinate or survey-layout error. Compare the resulting station sequence with the field manifest before using row position as profile distance. See pycsamt.emtools.ensure_sites() and Loading electromagnetic data for the processing boundary where ordering is applied.

2.4.3. Choose a plotting preset#

Named styles provide consistent colors and line conventions without requiring new users to configure individual components:

>>> from pycsamt.api import use_style
>>> use_style("publication")

Use "pycsamt" for the normal project appearance, "publication" for print-oriented figures, and "dark" only when the surrounding medium also uses a dark background. Plot style changes presentation, not the underlying resistivity, phase, uncertainty, or inversion result.

For multi-format output, set the formats and resolution together:

>>> from pycsamt.api import set_dpi, set_fmt, set_savedir
>>> set_fmt("png", "pdf")
>>> set_dpi(300)
>>> set_savedir("results/publication")

PNG is convenient for web pages and notebooks; PDF preserves vector content for publication when the plotting elements support it. Higher DPI improves raster resolution but does not add information absent from the data.

2.4.4. Keep API result views at their default initially#

Public table-producing functions normally return pyCSAMT view objects such as APIFrame. These retain metadata and provide readable summaries while still allowing conversion to pandas:

>>> from pycsamt.api import read_edis
>>> survey = read_edis(
...     "data/AMT/WILLY_DATA/L18PLT",
...     recursive=False,
...     progress=False,
... )
>>> summary = survey.summary()
>>> type(summary).__name__
'APIFrame'
>>> summary.to_pandas(copy=True).shape
(28, 6)

There is usually no reason to change this setting during Getting Started. If an integration requires raw pandas outputs globally, use pycsamt.api.configure_api_view() as described in API Views.

2.4.5. Use temporary settings for isolated work#

Configuration singletons provide context managers when one block needs a temporary override. The previous values are restored even if the block raises an exception:

>>> from pycsamt.api import PYCSAMT_ORDERING
>>> before = PYCSAMT_ORDERING.mode
>>> with PYCSAMT_ORDERING.context(mode="station"):
...     print(PYCSAMT_ORDERING.mode)
station
>>> PYCSAMT_ORDERING.mode == before
True

This is safer in notebooks and reusable libraries than changing a global setting for one operation and relying on a later cell to restore it.

2.4.6. Reset the settings you changed#

Reset helpers restore package defaults for the current process:

>>> from pycsamt.api import (
...     reset_ordering,
...     reset_plot_config,
...     reset_style,
... )
>>> reset_ordering()
>>> reset_plot_config()
>>> reset_style()

Resetting does not remove output files and does not undo transformations already applied to data objects.

2.4.7. Configuration that can wait#

Do not configure every subsystem before the first survey. Add settings when a workflow actually needs them:

Important

Never place provider API keys in documentation, notebooks committed to version control, pipeline configuration files, or command history. Use the provider’s supported environment variable or a local secret store.

With input format and session defaults established, continue to Inspect a first survey to load and inspect the first survey line.