pycsamt.api.view

User-facing result views for pyCSAMT public APIs.

class pycsamt.api.view.APIFrame(data=None, *, name=None, kind=None, source=None, units=None, meta=None, description=None, copy=False, **frame_kwargs)

Bases: PyCSAMTObject

A pyCSAMT dataframe view that keeps pandas behavior intact.

APIFrame is a thin wrapper around pandas.DataFrame. The dataframe remains available as df; pyCSAMT adds compact display, metadata, units, statistics, and convenient conversion helpers.

Parameters:

• data (Any)

• name (str | None)

• kind (str | None)

• source (Any)

• units (Mapping[str, str] | None)

• meta (Mapping[str, Any] | None)

• description (str | None)

• copy (bool)

• frame_kwargs (Any)

classmethod from_records(records, *, columns=None, **kwargs)

Build an APIFrame from record dictionaries.

Parameters:

• records (Iterable[Mapping[str, Any]])

• columns (Sequence[str] | None)

• kwargs (Any)

Return type:

APIFrame

property df: DataFrame

Return the underlying pandas dataframe.

property data: ndarray

Return dataframe values as a NumPy array.

property shape: tuple[int, int]

Return dataframe shape.

property columns: Index

Return dataframe columns.

property stats: FrameProfile

Return a compact dataframe profile.

property schema: dict[str, str]

Return column dtype names keyed by column name.

summary(*, max_columns=8)

Return a static display summary for printing.

Parameters:

max_columns (int)

Return type:

str

profile()

Return the same object as stats.

Return type:

FrameProfile

missing()

Return missing value counts by column.

Return type:

Series

numeric_stats(**kwargs)

Return pandas describe for numeric columns.

Parameters:

kwargs (Any)

Return type:

DataFrame

to_pandas(*, copy=False)

Return the underlying dataframe, optionally copied.

Parameters:

copy (bool)

Return type:

DataFrame

to_numpy(*args, **kwargs)

Return dataframe values as a NumPy array.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

ndarray

to_dict(*args, **kwargs)

Delegate to DataFrame.to_dict by default.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

dict

copy(*, deep=True)

Return a copied view preserving metadata.

Parameters:

deep (bool)

Return type:

APIFrame

with_df(df, **overrides)

Return a new APIFrame with another dataframe.

Parameters:

• df (Any)

• overrides (Any)

Return type:

APIFrame

update_meta(**kwargs)

Update metadata in-place and return self.

Parameters:

kwargs (Any)

Return type:

APIFrame

set_units(**kwargs)

Update column units in-place and return self.

Parameters:

kwargs (str)

Return type:

APIFrame

class pycsamt.api.view.APIResult(**items)

Bases: PyCSAMTObject

Container for named result parts, including one or more tables.

Parameters:

items (Any)

property keys: tuple[str, ...]

Return stored item names.

items()

Return (name, value) pairs.

tables()

Return only table-like result parts.

Return type:

dict[str, APIFrame]

update_meta(**kwargs)

Update metadata in-place and return self.

Parameters:

kwargs (Any)

Return type:

APIResult

class pycsamt.api.view.APISurvey(collection=None, *, name=None, source=None, parser=None, meta=None)

Bases: PyCSAMTObject

Friendly public facade over an EDICollection.

Parameters:

• collection (Any)

• name (str | None)

• source (Any)

• parser (Any)

• meta (Mapping[str, Any] | None)

property n_sites: int

Return number of loaded sites.

property stations: list[str]

Return station names.

property paths: list[str]

Return source paths for loaded stations.

property df: APIFrame

Return the default summary table.

property data: Any

Return the underlying EDI collection.

summary(*, fields=None)

Return an editable APIFrame summary of loaded EDI files.

Parameters:

fields (Sequence[str] | None)

Return type:

APIFrame

errors()

Return parser errors from the last read operation.

Return type:

list[tuple[Any, BaseException]]

get_site(site, default=None)

Return one site by station, stem, filename, or path.

Parameters:

• site (str)

• default (Any)

Return type:

Any

to_dataframe(*args, api=True, **kwargs)

Return collection dataframe output, wrapped by default.

Parameters:

• args (Any)

• api (bool)

• kwargs (Any)

to_collection()

Return the underlying collection.

Return type:

Any

update_meta(**kwargs)

Update metadata in-place and return self.

Parameters:

kwargs (Any)

Return type:

APISurvey

summary_text()

Return a compact survey display.

Return type:

str

class pycsamt.api.view.APIViewConfig

Bases: object

Package-wide policy for dataframe-like public API views.

The backend controls what pycsamt.api.view.wrap_frame() returns:

• "pycsamt" / True: return the built-in APIFrame.

• "pandas" / False: return the original dataframe-like object.

• callable: call wrapper(data, **metadata) and return its result.

configure(**kw)

Configure the view policy.

Parameters:

kw (Any)

Return type:

None

context(**kw)

Temporarily override API view settings.

Parameters:

kw (Any)

Return type:

Generator[APIViewConfig, None, None]

reset()

Reset to defaults.

Return type:

None

wrap_frame(data, **metadata)

Apply the configured dataframe wrapper.

Parameters:

• data (Any)

• metadata (Any)

Return type:

Any

enabled()

Return whether API view wrapping is enabled.

Return type:

bool

summary()

Return a compact configuration summary.

Return type:

str

class pycsamt.api.view.FrameProfile(rows, columns, column_names, numeric_columns, missing_cells, missing_fraction, memory_bytes)

Bases: object

Small immutable profile describing a dataframe.

Parameters:

• rows (int)

• columns (int)

• column_names (tuple[str, ...])

• numeric_columns (tuple[str, ...])

• missing_cells (int)

• missing_fraction (float)

• memory_bytes (int)

rows: int

columns: int

column_names: tuple[str, ...]

numeric_columns: tuple[str, ...]

missing_cells: int

missing_fraction: float

memory_bytes: int

classmethod from_frame(df)

Parameters:

df (DataFrame)

Return type:

FrameProfile

property shape: tuple[int, int]

Return (rows, columns).

to_dict()

Return a JSON-friendly profile dictionary.

Return type:

dict[str, Any]

class pycsamt.api.view.ProgressConfig(enabled='auto', desc=None, leave=False, unit='it', total=None)

Bases: object

Configuration for terminal progress display.

Parameters:

• enabled (bool | str)

• desc (str | None)

• leave (bool)

• unit (str)

• total (int | None)

enabled: bool | str = 'auto'

desc: str | None = None

leave: bool = False

unit: str = 'it'

total: int | None = None

pycsamt.api.view.api_frame(_func=None, *, name=None, kind=None, source=None, units=None, meta=None, description=None, copy=False)

Decorate a function so dataframe-like returns become APIFrame.

Parameters:

• _func (Callable[[...], Any] | None)

• name (str | None)

• kind (str | None)

• source (Any)

• units (Mapping[str, str] | None)

• meta (Mapping[str, Any] | None)

• description (str | None)

• copy (bool)

Return type:

Callable[[…], Any]

pycsamt.api.view.configure_api_view(**kw)

Configure the global API view backend.

Parameters:

kw (Any)

Return type:

None

pycsamt.api.view.iter_progress(iterable, *, enabled='auto', desc=None, leave=False, unit='it', total=None)

Yield items, optionally wrapped by tqdm.

Parameters:

• iterable (Iterable[T])

• enabled (bool | str)

• desc (str | None)

• leave (bool)

• unit (str)

• total (int | None)

Return type:

Iterator[T]

pycsamt.api.view.maybe_wrap_frame(data, *, api=None, name=None, kind=None, source=None, units=None, meta=None, description=None, copy=False, **frame_kwargs)

Conditionally wrap data as an APIFrame.

When api is None (the default), the global PYCSAMT_API_VIEW configuration decides. Pass api=True to force wrapping, or api=False to always return the raw dataframe regardless of the global setting.

Parameters:

• data (Any)

• api (bool | None)

• name (str | None)

• kind (str | None)

• source (Any)

• units (Mapping[str, str] | None)

• meta (Mapping[str, Any] | None)

• description (str | None)

• copy (bool)

• frame_kwargs (Any)

Return type:

Any

pycsamt.api.view.progress_enabled(value='auto')

Return whether progress should be displayed.

Parameters:

value (bool | str)

Return type:

bool

pycsamt.api.view.read_edi(path, *, verbose=0, **kwargs)

Read one EDI file and return an EDIFile.

Parameters:

• path (Any)

• verbose (int)

• kwargs (Any)

Return type:

Any

pycsamt.api.view.read_edis(sources, *, recursive=True, strict=False, on_dup='replace', progress='auto', leave=False, verbose=0)

Read many EDI files and return a public survey view.

Parameters:

• sources (Any | Sequence[Any])

• recursive (bool)

• strict (bool)

• on_dup (str)

• progress (bool | str)

• leave (bool)

• verbose (int)

Return type:

APISurvey

pycsamt.api.view.read_sites(sources, **kwargs)

Alias for read_edis().

Parameters:

• sources (Any | Sequence[Any])

• kwargs (Any)

Return type:

APISurvey

pycsamt.api.view.reset_api_view()

Reset the global API view backend.

Return type:

None

pycsamt.api.view.wrap_frame(data, *, name=None, kind=None, source=None, units=None, meta=None, description=None, copy=False, **frame_kwargs)

Wrap dataframe-like data using the configured API view backend.

Parameters:

• data (Any)

• name (str | None)

• kind (str | None)

• source (Any)

• units (Mapping[str, str] | None)

• meta (Mapping[str, Any] | None)

• description (str | None)

• copy (bool)

• frame_kwargs (Any)

Return type:

Any

pycsamt.api.view.wrap_result(result, *, name='result', kind=None, meta=None, wrap_tables=True)

Wrap a mapping of result parts as an APIResult.

Parameters:

• result (Mapping[str, Any])

• name (str)

• kind (str | None)

• meta (Mapping[str, Any] | None)

• wrap_tables (bool)

Return type:

APIResult

pycsamt.api.view.geology_dataframe(catalog=None, *, name='geology_catalog')

Return a public APIFrame for a geology catalog.

Parameters:

• catalog (object, optional) – Object exposing to_dataframe(). If omitted, the package-level built-in geology catalog is used.

• name (str, default "geology_catalog") – Display name attached to the returned APIFrame.

Return type:

Any

pycsamt.api.view.geology_table(catalog=None)

Alias for geology_dataframe().

Parameters:

catalog (Any)

Return type:

Any

pycsamt.api.view.quality_dataframe(sites)

Return a public APIFrame wrapper around metadata quality rows.

Parameters:

sites (Any)

Return type:

Any

pycsamt.api.view.quality_table(sites)

Alias for quality_dataframe().

Parameters:

sites (Any)

Return type:

Any

pycsamt.api.view.sites_summary(sites, *, fields=('station', 'n_freq', 'has_tipper', 'period_min', 'period_max', 'lat', 'lon'), recursive=True, on_dup='replace', strict=False, verbose=0)

Return a public APIFrame wrapper around emtools site summary.

Parameters:

• sites (Any)

• fields (Sequence[str])

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

Return type:

Any