pycsamt.api.view.frame#

Pandas-friendly dataframe result objects for public pyCSAMT APIs.

Functions

`api_frame`([_func, name, kind, source, ...])	Decorate a function so dataframe-like returns become `APIFrame`.
`maybe_wrap_frame`(data, *[, api, name, kind, ...])	Conditionally wrap data as an `APIFrame`.
`wrap_frame`(data, *[, name, kind, source, ...])	Wrap dataframe-like data using the configured API view backend.

Classes

`APIFrame`([data, name, kind, source, units, ...])	A pyCSAMT dataframe view that keeps pandas behavior intact.
`FrameProfile`(rows, columns, column_names, ...)	Small immutable profile describing a dataframe.

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

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)[source]#

Build an APIFrame from record dictionaries.

Parameters:

records (Iterable[Mapping[str, Any]])
columns (Sequence[str] | None)
kwargs (Any)

Return type:

APIFrame

property df: DataFrame[source]#: Return the underlying pandas dataframe.

property data: ndarray[source]#: Return dataframe values as a NumPy array.

property shape: tuple[int, int][source]#: Return dataframe shape.

property columns: Index[source]#: Return dataframe columns.

property stats: FrameProfile[source]#: Return a compact dataframe profile.

property schema: dict[str, str][source]#: Return column dtype names keyed by column name.

summary(*, max_columns=8)[source]#

Return a static display summary for printing.

Parameters:: max_columns (int)
Return type:: str

profile()[source]#

Return the same object as stats.

Return type:: FrameProfile

missing()[source]#

Return missing value counts by column.

Return type:: Series

numeric_stats(**kwargs)[source]#

Return pandas describe for numeric columns.

Parameters:: kwargs (Any)
Return type:: DataFrame

to_pandas(*, copy=False)[source]#

Return the underlying dataframe, optionally copied.

Parameters:: copy (bool)
Return type:: DataFrame

to_numpy(*args, **kwargs)[source]#

Return dataframe values as a NumPy array.

Parameters:

args (Any)
kwargs (Any)

Return type:

ndarray

to_dict(*args, **kwargs)[source]#

Delegate to DataFrame.to_dict by default.

Parameters:

args (Any)
kwargs (Any)

Return type:

dict

copy(*, deep=True)[source]#

Return a copied view preserving metadata.

Parameters:: deep (bool)
Return type:: APIFrame

with_df(df, **overrides)[source]#

Return a new APIFrame with another dataframe.

Parameters:

df (Any)
overrides (Any)

Return type:

APIFrame

update_meta(**kwargs)[source]#

Update metadata in-place and return self.

Parameters:: kwargs (Any)
Return type:: APIFrame

set_units(**kwargs)[source]#

Update column units in-place and return self.

Parameters:: kwargs (str)
Return type:: APIFrame

class pycsamt.api.view.frame.FrameProfile(rows, columns, column_names, numeric_columns, missing_cells, missing_fraction, memory_bytes)[source]#

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)[source]#

Parameters:: df (DataFrame)
Return type:: FrameProfile

property shape: tuple[int, int][source]#: Return (rows, columns).

to_dict()[source]#

Return a JSON-friendly profile dictionary.

Return type:: dict[str, Any]

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

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.frame.maybe_wrap_frame(data, *, api=None, name=None, kind=None, source=None, units=None, meta=None, description=None, copy=False, **frame_kwargs)[source]#

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.frame.wrap_frame(data, *, name=None, kind=None, source=None, units=None, meta=None, description=None, copy=False, **frame_kwargs)[source]#

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