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

ndarray

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

Delegate to DataFrame.to_dict by default.

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

Any