Dataset

class dataset.dataset_object.DatasetObject(path, **kwargs)

Bases: ABC

Base class for a tabular dataset and its feature metadata.

A dataset is created in a mutable state holding a raw, non-encoded, non-scaled dataframe (including the target column). Preprocessing steps mutate it through snapshot()/update(). Once freeze() is called the object becomes immutable and the read interface (get(), ordered_features(), __len__(), __getitem__()) becomes available while the mutation interface is locked. This freeze/mutable state machine prevents recourse methods and evaluations from accidentally mutating finalized data.

Parameters:

path (str)

target_column

Name of the label column inside the dataframe.

Type:

str

raw_feature_type

Maps each feature name to its semantic type (e.g. "continuous", "categorical").

Type:

dict[str, str]

raw_feature_mutability

Maps each feature name to whether it may be changed by a method.

Type:

dict[str, bool]

raw_feature_actionability

Maps each feature name to its allowed direction of change.

Type:

dict[str, str]

snapshot()

Return a deep copy of the current raw dataframe.

Only available while the dataset is mutable. Preprocessing steps should edit this copy and write it back with update().

Returns:

A deep copy of the underlying dataframe.

Return type:

pandas.DataFrame

Raises:

RuntimeError – If the dataset is frozen.

update(flag, value, df=None)

Set an attribute (and optionally swap the dataframe) on a mutable dataset.

Parameters:

• flag (str) – Name of the attribute to set. Commonly a boolean preprocessing flag (to guard against double application) or a metadata key.

• value (object) – Value to store; deep-copied before assignment.

• df (pandas.DataFrame, optional) – If provided, replaces the underlying dataframe (deep-copied).

Returns:

True on success.

Return type:

bool

Raises:

• RuntimeError – If the dataset is frozen.

• ValueError – If flag is None.

attr(flag)

Return a deep copy of a public attribute (flag or metadata).

Parameters:

flag (str) – Public attribute name. Names starting with _ are forbidden.

Returns:

Deep copy of the stored attribute value.

Return type:

object

Raises:

AttributeError – If flag is protected or unknown.

freeze()

Lock the dataset, enabling the read interface and disabling mutation.

get(target=False)

Return the feature columns, or the target column.

Only available once the dataset is frozen.

Parameters:

target (bool, default False) – If False return all feature columns (target excluded). If True return a single-column dataframe with the target.

Returns:

A deep copy of the requested columns.

Return type:

pandas.DataFrame

Raises:

• RuntimeError – If the dataset is not frozen.

• KeyError – If the target column is missing.

ordered_features()

Return all column names (features and target) in dataframe order.

Returns:

Column names. Only available once frozen.

Return type:

list[str]

__len__()

Return the number of rows (frozen datasets only).

Return type:

int

__getitem__(key)

Index a frozen dataset by row (int/slice) or column name (str).

Parameters:

key (int or slice or str) – int/slice select rows; str selects a single column.

Returns:

A deep copy of the selected rows or column.

Return type:

pandas.DataFrame

clone()

Return a deep, unfrozen copy of this dataset.

The clone is always mutable regardless of this object’s freeze state, so further preprocessing can be applied to it.

Returns:

A deep copy with _freeze reset to False.

Return type:

DatasetObject