ergodicDocs
Products: switch from ergodic to another product
Get started

ReferenceData

Data

Typed datasets: the data objects discovery and inference read. Import from ergodic.data.

Each shape embeds a column Schema (continuous, categorical, ordinal, datetime, or excluded) and shares the accessors on Dataset. The shapes are tabular, time-series, panel, and hierarchical time-series; the event log follows.

Build a dataset with tabular(), timeseries(), panel(), or hts(), each of which takes a pandas or polars dataframe, a dict of columns, or a numpy array.

Also exported from ergodic: Dataset, EventLog, HierarchicalTSData, Hierarchy, Ordinal, PanelData, Schema, SchemaInferenceWarning, TabularData, TimeSeriesData, VariableType, event_log, hts, panel, tabular, timeseries.

ColumnType#

python
class ColumnType(
    name: str,
    kind: VariableType,
    categories: tuple[Any, ...] | None = None,
    inferred: bool = True,
) -> None

The type of one column: its kind, and the categories when it is discrete.

Field Type Default
name str required
kind VariableType required
categories tuple[Any, ...] | None None
inferred bool True

ColumnType.ordered#

python
property ColumnType.ordered: bool

Whether the categories have an order (the column is ordinal).

ColumnType.is_continuous#

python
property ColumnType.is_continuous: bool

Whether the column is continuous.

ColumnType.is_categorical#

python
property ColumnType.is_categorical: bool

Whether the column is categorical (unordered).

ColumnType.is_ordinal#

python
property ColumnType.is_ordinal: bool

Whether the column is ordinal.

ColumnType.is_datetime#

python
property ColumnType.is_datetime: bool

Whether the column holds timestamps.

ColumnType.is_excluded#

python
property ColumnType.is_excluded: bool

Whether the column is excluded from modeling.

ColumnType.is_discrete#

python
property ColumnType.is_discrete: bool

Categorical or ordinal: backed by a finite set of categories.

ColumnType.cardinality#

python
property ColumnType.cardinality: int | None

The number of categories, or None when the column has none.

ColumnType.is_binary#

python
property ColumnType.is_binary: bool

Whether the column is discrete with exactly two categories.

Dataset#

python
class Dataset(
    schema: Schema,
    n_rows: int,
    _store: Mapping[str, npt.NDArray[Any]],
) -> None

A typed column store. Built through the shape factories, not directly.

Field Type Default
schema Schema required
n_rows int required

Dataset.names#

python
property Dataset.names: tuple[str, ...]

The column names, in schema order (index and excluded columns included).

Dataset.n_columns#

python
property Dataset.n_columns: int

The number of columns, index and excluded columns included.

Dataset.shape#

python
property Dataset.shape: tuple[int, int]

(n_rows, n_columns).

Dataset.index_columns#

python
property Dataset.index_columns: tuple[str, ...]

Columns that index the rows (time, entity, case), not modeled variables.

Dataset.variables#

python
property Dataset.variables: tuple[str, ...]

Column names the algorithms see: not the excluded ones, not the index.

Dataset.column#

python
def Dataset.column(name: str) -> npt.NDArray[Any]

A read-only copy of one column's raw values.

Dataset.codes#

python
def Dataset.codes(name: str) -> npt.NDArray[np.int64]

Integer category codes for a categorical or ordinal column, -1 for missing.

A non-missing value outside the column's categories raises a ValueError.

Dataset.categories#

python
def Dataset.categories(name: str) -> tuple[Any, ...] | None

Return the categories of a discrete column, or None for any other column.

Raises Description
KeyError The column is not in the dataset.

Dataset.matrix#

python
def Dataset.matrix(
    names: Sequence[str] | None = None,
) -> npt.NDArray[np.float64]

A float matrix of the named columns. Discrete columns become their codes, and a missing value (an NA category or NaT) becomes NaN.

Dataset.to_numpy#

python
def Dataset.to_numpy() -> npt.NDArray[np.float64]

Return the modeled variables as a float matrix, one column per variable.

The same as matrix() with no names: index and excluded columns are left out, discrete columns become their codes, and a missing value becomes NaN.

Dataset.to_pandas#

python
def Dataset.to_pandas() -> pd.DataFrame

Return every column as a pandas.DataFrame, with the raw values.

Index and excluded columns are included. Needs pandas.

Dataset.missing#

python
def Dataset.missing() -> dict[str, int]

Missing-value count per column.

Dataset.has_missing#

python
property Dataset.has_missing: bool

Whether any column has at least one missing value.

Dataset.dropna#

python
def Dataset.dropna() -> Self

Drop every row with a missing value in any column.

Dataset.take#

python
def Dataset.take(rows: Sequence[int] | npt.NDArray[np.int64]) -> Self

A new dataset with the rows at the given positions, in the given order.

Positions may repeat (a bootstrap resample) and may be negative (Python indexing). Row identity is all this knows about; shapes with row semantics (time series, panel) keep their index columns but it is the caller's job to resample in a way their structure survives.

Dataset.select#

python
def Dataset.select(names: Iterable[str]) -> Self

A new dataset with the named columns, plus any index columns, in order.

Dataset.with_type#

python
def Dataset.with_type(
    name: str,
    kind: VariableType | str | Ordinal,
    categories: Sequence[Any] | None = None,
) -> Self

A new dataset with name retyped, categories read from data when needed.

Dataset.exclude#

python
def Dataset.exclude(*names: str) -> Self

A new dataset with the named columns marked excluded.

Dataset.alignment#

python
def Dataset.alignment(graph: MixedGraph) -> list[str]

Where the variables and the graph's nodes disagree, empty when they match.

Dataset.aligns_with#

python
def Dataset.aligns_with(graph: MixedGraph) -> bool

True when the variables are exactly the graph's nodes.

EventLog#

python
class EventLog(
    schema: Schema,
    n_rows: int,
    _store: Mapping[str, npt.NDArray[Any]],
    case: str,
    activity: str,
    timestamp: str,
) -> None

Events keyed by case, activity, and timestamp; one row per event.

Field Type Default
schema Schema required
n_rows int required
case str required
activity str required
timestamp str required

EventLog.index_columns#

python
property EventLog.index_columns: tuple[str, ...]

Columns that index the rows (time, entity, case), not modeled variables.

EventLog.cases#

python
property EventLog.cases: tuple[Any, ...]

The distinct case identifiers, sorted.

EventLog.n_cases#

python
property EventLog.n_cases: int

The number of distinct cases.

EventLog.activities#

python
property EventLog.activities: tuple[str, ...]

The distinct activity names, sorted.

EventLog.n_activities#

python
property EventLog.n_activities: int

The number of distinct activities.

EventLog.traces#

python
def EventLog.traces() -> dict[Any, tuple[str, ...]]

The ordered activity sequence per case.

EventLog.variants#

python
def EventLog.variants() -> Counter[tuple[str, ...]]

How many cases follow each distinct activity sequence.

EventLog.directly_follows#

python
def EventLog.directly_follows() -> Counter[tuple[str, str]]

Counts of each (a, b) where b immediately follows a in a case.

EventLog.names#

python
property EventLog.names: tuple[str, ...]

The column names, in schema order (index and excluded columns included).

EventLog.n_columns#

python
property EventLog.n_columns: int

The number of columns, index and excluded columns included.

EventLog.shape#

python
property EventLog.shape: tuple[int, int]

(n_rows, n_columns).

EventLog.variables#

python
property EventLog.variables: tuple[str, ...]

Column names the algorithms see: not the excluded ones, not the index.

EventLog.column#

python
def EventLog.column(name: str) -> npt.NDArray[Any]

A read-only copy of one column's raw values.

EventLog.codes#

python
def EventLog.codes(name: str) -> npt.NDArray[np.int64]

Integer category codes for a categorical or ordinal column, -1 for missing.

A non-missing value outside the column's categories raises a ValueError.

EventLog.categories#

python
def EventLog.categories(name: str) -> tuple[Any, ...] | None

Return the categories of a discrete column, or None for any other column.

Raises Description
KeyError The column is not in the dataset.

EventLog.matrix#

python
def EventLog.matrix(
    names: Sequence[str] | None = None,
) -> npt.NDArray[np.float64]

A float matrix of the named columns. Discrete columns become their codes, and a missing value (an NA category or NaT) becomes NaN.

EventLog.to_numpy#

python
def EventLog.to_numpy() -> npt.NDArray[np.float64]

Return the modeled variables as a float matrix, one column per variable.

The same as matrix() with no names: index and excluded columns are left out, discrete columns become their codes, and a missing value becomes NaN.

EventLog.to_pandas#

python
def EventLog.to_pandas() -> pd.DataFrame

Return every column as a pandas.DataFrame, with the raw values.

Index and excluded columns are included. Needs pandas.

EventLog.missing#

python
def EventLog.missing() -> dict[str, int]

Missing-value count per column.

EventLog.has_missing#

python
property EventLog.has_missing: bool

Whether any column has at least one missing value.

EventLog.dropna#

python
def EventLog.dropna() -> Self

Drop every row with a missing value in any column.

EventLog.take#

python
def EventLog.take(rows: Sequence[int] | npt.NDArray[np.int64]) -> Self

A new dataset with the rows at the given positions, in the given order.

Positions may repeat (a bootstrap resample) and may be negative (Python indexing). Row identity is all this knows about; shapes with row semantics (time series, panel) keep their index columns but it is the caller's job to resample in a way their structure survives.

EventLog.select#

python
def EventLog.select(names: Iterable[str]) -> Self

A new dataset with the named columns, plus any index columns, in order.

EventLog.with_type#

python
def EventLog.with_type(
    name: str,
    kind: VariableType | str | Ordinal,
    categories: Sequence[Any] | None = None,
) -> Self

A new dataset with name retyped, categories read from data when needed.

EventLog.exclude#

python
def EventLog.exclude(*names: str) -> Self

A new dataset with the named columns marked excluded.

EventLog.alignment#

python
def EventLog.alignment(graph: MixedGraph) -> list[str]

Where the variables and the graph's nodes disagree, empty when they match.

EventLog.aligns_with#

python
def EventLog.aligns_with(graph: MixedGraph) -> bool

True when the variables are exactly the graph's nodes.

HierarchicalTSData#

python
class HierarchicalTSData(
    schema: Schema,
    n_rows: int,
    _store: Mapping[str, npt.NDArray[Any]],
    time: str,
    freq: str | None,
    hierarchy: Hierarchy,
) -> None

A time-series whose columns form an aggregation hierarchy.

Field Type Default
schema Schema required
n_rows int required
time str required
freq str | None required
hierarchy Hierarchy required

HierarchicalTSData.aggregate#

python
def HierarchicalTSData.aggregate(node: str) -> npt.NDArray[np.float64]

Build a node's series from its direct children, recursively.

A child contributes its own column when it has one, else its aggregate, and the parent is the sum or mean of those child series. This is the same definition coherence() checks, so the two cannot disagree.

HierarchicalTSData.coherence#

python
def HierarchicalTSData.coherence(
    rtol: float = 1e-05,
    atol: float = 1e-08,
) -> list[str]

Where a present parent column does not match aggregate() of its children.

HierarchicalTSData.is_coherent#

python
def HierarchicalTSData.is_coherent(
    rtol: float = 1e-05,
    atol: float = 1e-08,
) -> bool

True when every present parent equals the aggregate of its children.

HierarchicalTSData.index_columns#

python
property HierarchicalTSData.index_columns: tuple[str, ...]

Columns that index the rows (time, entity, case), not modeled variables.

HierarchicalTSData.times#

python
property HierarchicalTSData.times: npt.NDArray[Any]

The time index, in ascending order.

HierarchicalTSData.names#

python
property HierarchicalTSData.names: tuple[str, ...]

The column names, in schema order (index and excluded columns included).

HierarchicalTSData.n_columns#

python
property HierarchicalTSData.n_columns: int

The number of columns, index and excluded columns included.

HierarchicalTSData.shape#

python
property HierarchicalTSData.shape: tuple[int, int]

(n_rows, n_columns).

HierarchicalTSData.variables#

python
property HierarchicalTSData.variables: tuple[str, ...]

Column names the algorithms see: not the excluded ones, not the index.

HierarchicalTSData.column#

python
def HierarchicalTSData.column(name: str) -> npt.NDArray[Any]

A read-only copy of one column's raw values.

HierarchicalTSData.codes#

python
def HierarchicalTSData.codes(name: str) -> npt.NDArray[np.int64]

Integer category codes for a categorical or ordinal column, -1 for missing.

A non-missing value outside the column's categories raises a ValueError.

HierarchicalTSData.categories#

python
def HierarchicalTSData.categories(name: str) -> tuple[Any, ...] | None

Return the categories of a discrete column, or None for any other column.

Raises Description
KeyError The column is not in the dataset.

HierarchicalTSData.matrix#

python
def HierarchicalTSData.matrix(
    names: Sequence[str] | None = None,
) -> npt.NDArray[np.float64]

A float matrix of the named columns. Discrete columns become their codes, and a missing value (an NA category or NaT) becomes NaN.

HierarchicalTSData.to_numpy#

python
def HierarchicalTSData.to_numpy() -> npt.NDArray[np.float64]

Return the modeled variables as a float matrix, one column per variable.

The same as matrix() with no names: index and excluded columns are left out, discrete columns become their codes, and a missing value becomes NaN.

HierarchicalTSData.to_pandas#

python
def HierarchicalTSData.to_pandas() -> pd.DataFrame

Return every column as a pandas.DataFrame, with the raw values.

Index and excluded columns are included. Needs pandas.

HierarchicalTSData.missing#

python
def HierarchicalTSData.missing() -> dict[str, int]

Missing-value count per column.

HierarchicalTSData.has_missing#

python
property HierarchicalTSData.has_missing: bool

Whether any column has at least one missing value.

HierarchicalTSData.dropna#

python
def HierarchicalTSData.dropna() -> Self

Drop every row with a missing value in any column.

HierarchicalTSData.take#

python
def HierarchicalTSData.take(
    rows: Sequence[int] | npt.NDArray[np.int64],
) -> Self

A new dataset with the rows at the given positions, in the given order.

Positions may repeat (a bootstrap resample) and may be negative (Python indexing). Row identity is all this knows about; shapes with row semantics (time series, panel) keep their index columns but it is the caller's job to resample in a way their structure survives.

HierarchicalTSData.select#

python
def HierarchicalTSData.select(names: Iterable[str]) -> Self

A new dataset with the named columns, plus any index columns, in order.

HierarchicalTSData.with_type#

python
def HierarchicalTSData.with_type(
    name: str,
    kind: VariableType | str | Ordinal,
    categories: Sequence[Any] | None = None,
) -> Self

A new dataset with name retyped, categories read from data when needed.

HierarchicalTSData.exclude#

python
def HierarchicalTSData.exclude(*names: str) -> Self

A new dataset with the named columns marked excluded.

HierarchicalTSData.alignment#

python
def HierarchicalTSData.alignment(graph: MixedGraph) -> list[str]

Where the variables and the graph's nodes disagree, empty when they match.

HierarchicalTSData.aligns_with#

python
def HierarchicalTSData.aligns_with(graph: MixedGraph) -> bool

True when the variables are exactly the graph's nodes.

Hierarchy#

python
class Hierarchy(
    edges: frozenset[tuple[str, str]],
    aggregation: str = 'sum',
) -> None

A tree of named series, with edges running parent to child, and an aggregation rule.

Field Type Default
edges frozenset[tuple[str, str]] required
aggregation str 'sum'

Hierarchy.tree#

python
classmethod Hierarchy.tree(
    adjacency: Mapping[str, Iterable[str]],
    aggregation: str = 'sum',
) -> Hierarchy

Build from a parent-to-children mapping, for example {"total": ["a", "b"]}.

Hierarchy.children_of#

python
def Hierarchy.children_of(node: str) -> tuple[str, ...]

Return the children of node, sorted; empty for a leaf.

Raises ValueError when node is not in the hierarchy.

Hierarchy.parent_of#

python
def Hierarchy.parent_of(node: str) -> str | None

Return the parent of node, or None for a root.

Raises ValueError when node is not in the hierarchy.

Hierarchy.is_leaf#

python
def Hierarchy.is_leaf(node: str) -> bool

Return True when node has no children.

Raises ValueError when node is not in the hierarchy.

Hierarchy.roots#

python
property Hierarchy.roots: tuple[str, ...]

Nodes with no parent.

Hierarchy.leaves#

python
property Hierarchy.leaves: tuple[str, ...]

Nodes with no children: the base series.

Hierarchy.internal_nodes#

python
property Hierarchy.internal_nodes: tuple[str, ...]

Nodes with children: the aggregates.

Hierarchy.leaf_descendants#

python
def Hierarchy.leaf_descendants(node: str) -> tuple[str, ...]

The base series that aggregate up to node (node itself when it is a leaf).

Hierarchy.levels#

python
def Hierarchy.levels() -> dict[str, int]

Depth of each node, with roots at 0.

Ordinal#

python
class Ordinal(levels: Sequence[Any]) -> None

Mark a column ordinal, listing its categories in increasing order.

Use it in a type override: types={"stage": Ordinal(["I", "II", "III"])}.

Field Type Default
levels Sequence[Any] required

PanelData#

python
class PanelData(
    schema: Schema,
    n_rows: int,
    _store: Mapping[str, npt.NDArray[Any]],
    entity: str,
    time: str,
    freq: str | None = None,
) -> None

Entities observed over time, keyed by a unique (entity, time) pair.

Field Type Default
schema Schema required
n_rows int required
entity str required
time str required
freq str | None None

PanelData.index_columns#

python
property PanelData.index_columns: tuple[str, ...]

Columns that index the rows (time, entity, case), not modeled variables.

PanelData.entities#

python
property PanelData.entities: tuple[Any, ...]

The distinct entity identifiers, sorted.

PanelData.periods#

python
property PanelData.periods: tuple[Any, ...]

The distinct time values, sorted.

PanelData.n_entities#

python
property PanelData.n_entities: int

The number of distinct entities.

PanelData.n_periods#

python
property PanelData.n_periods: int

The number of distinct time values.

PanelData.is_balanced#

python
property PanelData.is_balanced: bool

True when every entity is seen in every period (a full grid).

PanelData.time_invariant#

python
def PanelData.time_invariant() -> tuple[str, ...]

Variables whose value never changes within an entity.

PanelData.names#

python
property PanelData.names: tuple[str, ...]

The column names, in schema order (index and excluded columns included).

PanelData.n_columns#

python
property PanelData.n_columns: int

The number of columns, index and excluded columns included.

PanelData.shape#

python
property PanelData.shape: tuple[int, int]

(n_rows, n_columns).

PanelData.variables#

python
property PanelData.variables: tuple[str, ...]

Column names the algorithms see: not the excluded ones, not the index.

PanelData.column#

python
def PanelData.column(name: str) -> npt.NDArray[Any]

A read-only copy of one column's raw values.

PanelData.codes#

python
def PanelData.codes(name: str) -> npt.NDArray[np.int64]

Integer category codes for a categorical or ordinal column, -1 for missing.

A non-missing value outside the column's categories raises a ValueError.

PanelData.categories#

python
def PanelData.categories(name: str) -> tuple[Any, ...] | None

Return the categories of a discrete column, or None for any other column.

Raises Description
KeyError The column is not in the dataset.

PanelData.matrix#

python
def PanelData.matrix(
    names: Sequence[str] | None = None,
) -> npt.NDArray[np.float64]

A float matrix of the named columns. Discrete columns become their codes, and a missing value (an NA category or NaT) becomes NaN.

PanelData.to_numpy#

python
def PanelData.to_numpy() -> npt.NDArray[np.float64]

Return the modeled variables as a float matrix, one column per variable.

The same as matrix() with no names: index and excluded columns are left out, discrete columns become their codes, and a missing value becomes NaN.

PanelData.to_pandas#

python
def PanelData.to_pandas() -> pd.DataFrame

Return every column as a pandas.DataFrame, with the raw values.

Index and excluded columns are included. Needs pandas.

PanelData.missing#

python
def PanelData.missing() -> dict[str, int]

Missing-value count per column.

PanelData.has_missing#

python
property PanelData.has_missing: bool

Whether any column has at least one missing value.

PanelData.dropna#

python
def PanelData.dropna() -> Self

Drop every row with a missing value in any column.

PanelData.take#

python
def PanelData.take(rows: Sequence[int] | npt.NDArray[np.int64]) -> Self

A new dataset with the rows at the given positions, in the given order.

Positions may repeat (a bootstrap resample) and may be negative (Python indexing). Row identity is all this knows about; shapes with row semantics (time series, panel) keep their index columns but it is the caller's job to resample in a way their structure survives.

PanelData.select#

python
def PanelData.select(names: Iterable[str]) -> Self

A new dataset with the named columns, plus any index columns, in order.

PanelData.with_type#

python
def PanelData.with_type(
    name: str,
    kind: VariableType | str | Ordinal,
    categories: Sequence[Any] | None = None,
) -> Self

A new dataset with name retyped, categories read from data when needed.

PanelData.exclude#

python
def PanelData.exclude(*names: str) -> Self

A new dataset with the named columns marked excluded.

PanelData.alignment#

python
def PanelData.alignment(graph: MixedGraph) -> list[str]

Where the variables and the graph's nodes disagree, empty when they match.

PanelData.aligns_with#

python
def PanelData.aligns_with(graph: MixedGraph) -> bool

True when the variables are exactly the graph's nodes.

Schema#

python
class Schema(columns: tuple[ColumnType, ...]) -> None

An ordered set of column types, queryable by name and by kind.

Field Type Default
columns tuple[ColumnType, ...] required

Schema.get#

python
def Schema.get(name: str) -> ColumnType | None

Return the type of column name, or None when there is no such column.

Schema.names#

python
property Schema.names: tuple[str, ...]

The column names, in order.

Schema.of_kind#

python
def Schema.of_kind(kind: VariableType) -> tuple[str, ...]

Return the names of the columns of one kind, in schema order.

Schema.continuous#

python
property Schema.continuous: tuple[str, ...]

The names of the continuous columns.

Schema.categorical#

python
property Schema.categorical: tuple[str, ...]

The names of the categorical columns (ordinal columns are not included).

Schema.ordinal#

python
property Schema.ordinal: tuple[str, ...]

The names of the ordinal columns.

Schema.datetime#

python
property Schema.datetime: tuple[str, ...]

The names of the datetime columns.

Schema.excluded#

python
property Schema.excluded: tuple[str, ...]

The names of the excluded columns.

Schema.discrete#

python
property Schema.discrete: tuple[str, ...]

Categorical and ordinal columns together.

Schema.variables#

python
property Schema.variables: tuple[str, ...]

Every column the algorithms see: all but the excluded ones.

Schema.with_type#

python
def Schema.with_type(
    name: str,
    kind: VariableType | str | Ordinal,
    categories: Sequence[Any] | None = None,
) -> Schema

Return a new schema with name retyped. Marks the column user-set.

SchemaInferenceWarning#

A column type was guessed from ambiguous data (for example integer levels).

TabularData#

python
class TabularData(
    schema: Schema,
    n_rows: int,
    _store: Mapping[str, npt.NDArray[Any]],
) -> None

Cross-sectional data: rows are independent units, with no index column.

Field Type Default
schema Schema required
n_rows int required

TabularData.names#

python
property TabularData.names: tuple[str, ...]

The column names, in schema order (index and excluded columns included).

TabularData.n_columns#

python
property TabularData.n_columns: int

The number of columns, index and excluded columns included.

TabularData.shape#

python
property TabularData.shape: tuple[int, int]

(n_rows, n_columns).

TabularData.index_columns#

python
property TabularData.index_columns: tuple[str, ...]

Columns that index the rows (time, entity, case), not modeled variables.

TabularData.variables#

python
property TabularData.variables: tuple[str, ...]

Column names the algorithms see: not the excluded ones, not the index.

TabularData.column#

python
def TabularData.column(name: str) -> npt.NDArray[Any]

A read-only copy of one column's raw values.

TabularData.codes#

python
def TabularData.codes(name: str) -> npt.NDArray[np.int64]

Integer category codes for a categorical or ordinal column, -1 for missing.

A non-missing value outside the column's categories raises a ValueError.

TabularData.categories#

python
def TabularData.categories(name: str) -> tuple[Any, ...] | None

Return the categories of a discrete column, or None for any other column.

Raises Description
KeyError The column is not in the dataset.

TabularData.matrix#

python
def TabularData.matrix(
    names: Sequence[str] | None = None,
) -> npt.NDArray[np.float64]

A float matrix of the named columns. Discrete columns become their codes, and a missing value (an NA category or NaT) becomes NaN.

TabularData.to_numpy#

python
def TabularData.to_numpy() -> npt.NDArray[np.float64]

Return the modeled variables as a float matrix, one column per variable.

The same as matrix() with no names: index and excluded columns are left out, discrete columns become their codes, and a missing value becomes NaN.

TabularData.to_pandas#

python
def TabularData.to_pandas() -> pd.DataFrame

Return every column as a pandas.DataFrame, with the raw values.

Index and excluded columns are included. Needs pandas.

TabularData.missing#

python
def TabularData.missing() -> dict[str, int]

Missing-value count per column.

TabularData.has_missing#

python
property TabularData.has_missing: bool

Whether any column has at least one missing value.

TabularData.dropna#

python
def TabularData.dropna() -> Self

Drop every row with a missing value in any column.

TabularData.take#

python
def TabularData.take(rows: Sequence[int] | npt.NDArray[np.int64]) -> Self

A new dataset with the rows at the given positions, in the given order.

Positions may repeat (a bootstrap resample) and may be negative (Python indexing). Row identity is all this knows about; shapes with row semantics (time series, panel) keep their index columns but it is the caller's job to resample in a way their structure survives.

TabularData.select#

python
def TabularData.select(names: Iterable[str]) -> Self

A new dataset with the named columns, plus any index columns, in order.

TabularData.with_type#

python
def TabularData.with_type(
    name: str,
    kind: VariableType | str | Ordinal,
    categories: Sequence[Any] | None = None,
) -> Self

A new dataset with name retyped, categories read from data when needed.

TabularData.exclude#

python
def TabularData.exclude(*names: str) -> Self

A new dataset with the named columns marked excluded.

TabularData.alignment#

python
def TabularData.alignment(graph: MixedGraph) -> list[str]

Where the variables and the graph's nodes disagree, empty when they match.

TabularData.aligns_with#

python
def TabularData.aligns_with(graph: MixedGraph) -> bool

True when the variables are exactly the graph's nodes.

TimeSeriesData#

python
class TimeSeriesData(
    schema: Schema,
    n_rows: int,
    _store: Mapping[str, npt.NDArray[Any]],
    time: str,
    freq: str | None,
) -> None

Series ordered by a time column, with an optional sampling frequency.

Field Type Default
schema Schema required
n_rows int required
time str required
freq str | None required

TimeSeriesData.index_columns#

python
property TimeSeriesData.index_columns: tuple[str, ...]

Columns that index the rows (time, entity, case), not modeled variables.

TimeSeriesData.times#

python
property TimeSeriesData.times: npt.NDArray[Any]

The time index, in ascending order.

TimeSeriesData.names#

python
property TimeSeriesData.names: tuple[str, ...]

The column names, in schema order (index and excluded columns included).

TimeSeriesData.n_columns#

python
property TimeSeriesData.n_columns: int

The number of columns, index and excluded columns included.

TimeSeriesData.shape#

python
property TimeSeriesData.shape: tuple[int, int]

(n_rows, n_columns).

TimeSeriesData.variables#

python
property TimeSeriesData.variables: tuple[str, ...]

Column names the algorithms see: not the excluded ones, not the index.

TimeSeriesData.column#

python
def TimeSeriesData.column(name: str) -> npt.NDArray[Any]

A read-only copy of one column's raw values.

TimeSeriesData.codes#

python
def TimeSeriesData.codes(name: str) -> npt.NDArray[np.int64]

Integer category codes for a categorical or ordinal column, -1 for missing.

A non-missing value outside the column's categories raises a ValueError.

TimeSeriesData.categories#

python
def TimeSeriesData.categories(name: str) -> tuple[Any, ...] | None

Return the categories of a discrete column, or None for any other column.

Raises Description
KeyError The column is not in the dataset.

TimeSeriesData.matrix#

python
def TimeSeriesData.matrix(
    names: Sequence[str] | None = None,
) -> npt.NDArray[np.float64]

A float matrix of the named columns. Discrete columns become their codes, and a missing value (an NA category or NaT) becomes NaN.

TimeSeriesData.to_numpy#

python
def TimeSeriesData.to_numpy() -> npt.NDArray[np.float64]

Return the modeled variables as a float matrix, one column per variable.

The same as matrix() with no names: index and excluded columns are left out, discrete columns become their codes, and a missing value becomes NaN.

TimeSeriesData.to_pandas#

python
def TimeSeriesData.to_pandas() -> pd.DataFrame

Return every column as a pandas.DataFrame, with the raw values.

Index and excluded columns are included. Needs pandas.

TimeSeriesData.missing#

python
def TimeSeriesData.missing() -> dict[str, int]

Missing-value count per column.

TimeSeriesData.has_missing#

python
property TimeSeriesData.has_missing: bool

Whether any column has at least one missing value.

TimeSeriesData.dropna#

python
def TimeSeriesData.dropna() -> Self

Drop every row with a missing value in any column.

TimeSeriesData.take#

python
def TimeSeriesData.take(rows: Sequence[int] | npt.NDArray[np.int64]) -> Self

A new dataset with the rows at the given positions, in the given order.

Positions may repeat (a bootstrap resample) and may be negative (Python indexing). Row identity is all this knows about; shapes with row semantics (time series, panel) keep their index columns but it is the caller's job to resample in a way their structure survives.

TimeSeriesData.select#

python
def TimeSeriesData.select(names: Iterable[str]) -> Self

A new dataset with the named columns, plus any index columns, in order.

TimeSeriesData.with_type#

python
def TimeSeriesData.with_type(
    name: str,
    kind: VariableType | str | Ordinal,
    categories: Sequence[Any] | None = None,
) -> Self

A new dataset with name retyped, categories read from data when needed.

TimeSeriesData.exclude#

python
def TimeSeriesData.exclude(*names: str) -> Self

A new dataset with the named columns marked excluded.

TimeSeriesData.alignment#

python
def TimeSeriesData.alignment(graph: MixedGraph) -> list[str]

Where the variables and the graph's nodes disagree, empty when they match.

TimeSeriesData.aligns_with#

python
def TimeSeriesData.aligns_with(graph: MixedGraph) -> bool

True when the variables are exactly the graph's nodes.

VariableType#

python
class VariableType(enum.Enum)

How a column is measured, which decides the methods that apply to it.

Member Value
CONTINUOUS 'continuous'
CATEGORICAL 'categorical'
ORDINAL 'ordinal'
DATETIME 'datetime'
EXCLUDED 'excluded'

event_log#

python
def event_log(
    data: Any,
    *,
    case: str,
    activity: str,
    timestamp: str,
    columns: Sequence[str] | None = None,
    types: Mapping[str, VariableType | str | Ordinal] | None = None,
    exclude: Iterable[str] | None = None,
    categorical_threshold: int = 10,
) -> EventLog

Build an EventLog, grouped by case and ordered by timestamp.

hts#

python
def hts(
    data: Any,
    *,
    time: str,
    hierarchy: Hierarchy | Mapping[str, Iterable[str]],
    freq: str | None = None,
    columns: Sequence[str] | None = None,
    types: Mapping[str, VariableType | str | Ordinal] | None = None,
    exclude: Iterable[str] | None = None,
    categorical_threshold: int = 10,
) -> HierarchicalTSData

Build a HierarchicalTSData from series columns and a hierarchy.

infer_schema#

python
def infer_schema(
    store: Mapping[str, npt.NDArray[Any]],
    *,
    n_rows: int,
    declared: Mapping[str, ColumnType] | None = None,
    overrides: Mapping[str, VariableType | str | Ordinal] | None = None,
    exclude: Iterable[str] | None = None,
    categorical_threshold: int = 10,
) -> Schema

Build a schema from columns: user overrides beat source-declared beat inferred.

panel#

python
def panel(
    data: Any,
    *,
    entity: str,
    time: str,
    freq: str | None = None,
    columns: Sequence[str] | None = None,
    types: Mapping[str, VariableType | str | Ordinal] | None = None,
    exclude: Iterable[str] | None = None,
    categorical_threshold: int = 10,
) -> PanelData

Build a PanelData, keyed and sorted by (entity, time).

tabular#

python
def tabular(
    data: Any,
    *,
    columns: Sequence[str] | None = None,
    types: Mapping[str, VariableType | str | Ordinal] | None = None,
    exclude: Iterable[str] | None = None,
    categorical_threshold: int = 10,
) -> TabularData

Build a TabularData from a dataframe, a dict of columns, or an array.

Parameter Description
data A pandas or polars dataframe, a mapping of name to column, or a 2-D numpy array (name the columns with columns).
columns Column names, used when data is a bare numpy array.
types Per-column type overrides, for example {"age": "continuous", "stage": Ordinal(["I", "II", "III"])}.
exclude Columns to mark excluded, so they are kept but not treated as variables (identifiers, free text).
categorical_threshold Integer columns with at most this many distinct values are inferred categorical, with a warning.

timeseries#

python
def timeseries(
    data: Any,
    *,
    time: str,
    freq: str | None = None,
    columns: Sequence[str] | None = None,
    types: Mapping[str, VariableType | str | Ordinal] | None = None,
    exclude: Iterable[str] | None = None,
    categorical_threshold: int = 10,
) -> TimeSeriesData

Build a TimeSeriesData, sorting rows by the time column.

The time column is typed from its data (datetime, else continuous) unless you override it, so an integer step index is not mistaken for a category.

Suggest an edit
Documentation
Get started

Search ergodic 0.2.0

Search ergodic by task, function or error.