2.2.3.20. 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:
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:
Return type:

ndarray

to_dict(*args, **kwargs)

Delegate to DataFrame.to_dict by default.

Parameters:
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:
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:
Return type:

Any

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

Return collection dataframe output, wrapped by default.

Parameters:
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:
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
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.ProgressAPIConfig

Bases: object

Package-wide policy for ProgressBar.

Variables:

  • default_verbose – Verbosity used when a call site’s own verbose argument is None. Does not override an explicit verbose=True/False passed by the caller — use force_verbose for that.

  • force_verbose – When set (0, 1, or 2), overrides every call site’s verbose argument, explicit or not. None (default) leaves callers in control.

  • style – Bar glyph set — "ascii" (default, safe on legacy Windows console code pages) or "unicode".

  • min_interval – Minimum seconds between bar redraws.

  • log_every – Default line-throttle for log-mode (verbose level 2) progress. None auto-computes ~10 lines per run.

configure(**kw)

Set one or more configuration attributes by keyword.

Parameters:

kw (Any)

Return type:

None

context(**kw)

Temporarily override progress config, then restore it.

Parameters:

kw (Any)

Return type:

Generator[ProgressAPIConfig, None, None]

reset()

Reset to package defaults.

Return type:

None

resolve(verbose=None)

Resolve a call site’s verbose argument to 0/1/2.

Parameters:

verbose (bool | int | str | None)

Return type:

int

summary()

Return a human-readable configuration summary.

Return type:

str

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 = '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:
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.configure_progress(**kw)

Configure PYCSAMT_PROGRESS with keyword arguments.

Parameters:

kw (Any)

Return type:

None

pycsamt.api.view.get_progress_bar(total=None, *, desc=None, unit='it', verbose=None, leave=False, log_every=None)

Build a ProgressBar honouring PYCSAMT_PROGRESS (style, throttle, forced verbosity).

This is the recommended entry point for AI-inversion agents, dataset generation, and realization loops — it lets a user silence or reshape progress output package-wide via configure_progress() without touching every function’s verbose default.

Parameters:
Return type:

ProgressBar

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

Yield items, optionally wrapped by a ProgressBar.

Parameters:
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:
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:
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:
Return type:

APISurvey

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

Alias for read_edis().

Parameters:
Return type:

APISurvey

pycsamt.api.view.reset_api_view()

Reset the global API view backend.

Return type:

None

pycsamt.api.view.reset_progress()

Reset PYCSAMT_PROGRESS to package defaults.

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:
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:
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:
Return type:

Any