MODULE REFERENCE

dataset

anomx.data.dataset

Lightweight datasets for time series, generic sequences, and independent samples.

Public exports

Import these names directly from anomx.data.dataset.

DatasetClient

Resolve versioned datasets and load channels without a specific host.

Dataset

Dataset(reference: str | None = None, *, anomx_reference: str | None = None, data: pd.DataFrame | None = None, kind: DatasetKind = 'independent_samples', mode: DatasetMode = 'fixed', name: str = '', metadata: Mapping[str, Any] | None = None, client: DatasetClient | PlatformClient | None = None, cache: bool | str | Path = True, cache_ttl: float | None = 0, progress: bool = True)

Local observations or a lazy, versioned platform dataset reference.

Dataset("data_dataset-...") resolves through the active work context or an explicit PlatformClient (falling back to ANOMX_URL/ANOMX_TOKEN). Dataset(anomx_reference="data_dataset-...", client=client) makes the remote identity explicit. HTTP endpoint details live in the data source. iter_batches bounds memory; to_dataframe deliberately materializes the whole dataset. Fixed external sources are references, never copied.

Signature parameters
ParameterTypeDefault
referencestr | NoneNone
anomx_referencekeyword onlystr | NoneNone
datakeyword onlypd.DataFrame | NoneNone
kindkeyword onlyDatasetKind'independent_samples'
modekeyword onlyDatasetMode'fixed'
namekeyword onlystr''
metadatakeyword onlyMapping[str, Any] | NoneNone
clientkeyword onlyDatasetClient | PlatformClient | NoneNone
cachekeyword onlybool | str | PathTrue
cache_ttlkeyword onlyfloat | None0
progresskeyword onlyboolTrue

Members

anomx_referenceproperty
anomx_reference: str | None

The remote dataset identity, or None for local observations.

Returns str | None

selectmethod
select(*, start: TimeBound | None = None, end: TimeBound | None = None) -> Dataset

Return a lazy time window, including start and excluding end.

Strings and datetimes are accepted; timezone-free bounds mean UTC. Explicit bounds replace those on this view. Remote selection happens on the server and requires its dataset selection capability.

Signature parameters
ParameterTypeDefault
startkeyword onlyTimeBound | NoneNone
endkeyword onlyTimeBound | NoneNone

Returns Dataset

downsamplemethod
downsample(frequency: str, *, aggregation: str = 'mean') -> Dataset

Return a lazy view aggregated into fixed UTC-epoch bins.

Supported reducers are mean, first, last, min, max, sum, and count. Time filtering precedes aggregation; missing bins are omitted and no values are forward-filled. Bin labels are their left edges, which can precede a selection's start. Remote aggregation reduces transferred rows and requires a platform with dataset selection support.

Signature parameters
ParameterTypeDefault
frequencystrrequired
aggregationkeyword onlystr'mean'

Returns Dataset

select_filesmethod
select_files(*, variables: Sequence[str] | None = None, columns: Sequence[str] | None = None, path_prefix: str | None = None, path_start: str | None = None, path_end: str | None = None, row_start: int | None = None, row_end: int | None = None, row_step: int | None = None, sample_start: int | None = None, sample_end: int | None = None, sample_step: int | None = None) -> Dataset

Select indexed files and bounded observations without materialization.

Variables are filename stems reported by the source catalog. Path bounds are lexical integration paths; row bounds are per file. Sample bounds slice the first array dimension inside each observation, preserving all remaining dimensions. End bounds are exclusive. Steps subsample by stride; they do not average, filter or invent timestamps.

Signature parameters
ParameterTypeDefault
variableskeyword onlySequence[str] | NoneNone
columnskeyword onlySequence[str] | NoneNone
path_prefixkeyword onlystr | NoneNone
path_startkeyword onlystr | NoneNone
path_endkeyword onlystr | NoneNone
row_startkeyword onlyint | NoneNone
row_endkeyword onlyint | NoneNone
row_stepkeyword onlyint | NoneNone
sample_startkeyword onlyint | NoneNone
sample_endkeyword onlyint | NoneNone
sample_stepkeyword onlyint | NoneNone

Returns Dataset

source_entriesmethod
source_entries(*, page_size: int = 100) -> Iterator[dict[str, Any]]

Iterate immutable source fingerprints without loading their contents.

Signature parameters
ParameterTypeDefault
page_sizekeyword onlyint100

Returns Iterator[dict[str, Any]]

describemethod
describe(*, refresh: bool = False) -> dict[str, Any]

Resolve source identity and schema without loading all observations.

Signature parameters
ParameterTypeDefault
refreshkeyword onlyboolFalse

Returns dict[str, Any]

iter_batchesmethod
iter_batches(batch_size: int = 5000, *, progress: bool | None = None, refresh: bool = False) -> Iterator[pd.DataFrame]

Yield bounded, ordered batches pinned to one resolved source version.

Each remote page is checkpointed before yielding. A new iterator replays saved pages, then resumes at the saved cursor. Close the iterator when stopping early to release the download lock. progress=False silences tqdm in applications and automated jobs.

Signature parameters
ParameterTypeDefault
batch_sizeint5000
progresskeyword onlybool | NoneNone
refreshkeyword onlyboolFalse

Returns Iterator[pd.DataFrame]

clear_cachemethod
clear_cache(*, max_rows: int | None = None) -> None

Clear this selection's saved pages without contacting the host.

Pages are shared by all prefix lengths. max_rows also selects an old-format materialized prefix entry to remove, when one exists.

Signature parameters
ParameterTypeDefault
max_rowskeyword onlyint | NoneNone

Returns None

to_dataframemethod
to_dataframe(*, batch_size: int = 5000, progress: bool | None = None, refresh: bool = False, max_rows: int | None = None) -> pd.DataFrame

Materialize a dataset or view, resuming saved pages automatically.

Every load resolves current metadata and permissions. Interrupted downloads resume at a pinned source version, even beyond cache_ttl. Without a content validator this is a resumable local snapshot, not a guarantee against upstream corrections. Completed downloads require a matching content token or an explicit TTL; cache_ttl=None opts into snapshot reuse until refresh or a source version change.

refresh=True restarts the download. max_rows caps output rows after selection/aggregation; whole downloaded pages are retained so a later larger request can reuse their tails. iter_batches uses the same checkpoints without materializing the full dataset in memory.

Signature parameters
ParameterTypeDefault
batch_sizekeyword onlyint5000
progresskeyword onlybool | NoneNone
refreshkeyword onlyboolFalse
max_rowskeyword onlyint | NoneNone

Returns pd.DataFrame

to_timeseriesmethod
to_timeseries(*, frequency: str | None = None, aggregation: str = 'mean', fill: Literal['ffill', 'interpolate'] | None = None, value_columns: Sequence[str] | None = None, progress: bool | None = None) -> TimeSeries

Create an Anomx TimeSeries, optionally resampling irregular observations.

The native forecasting container uses regular, timezone-free indices; aware times are normalized to UTC and their original timezone is stored in metadata. Resampling leaves empty bins as NaN unless fill is explicitly selected. Without a frequency, irregular data is rejected by TimeSeries; the original observations remain available as a frame.

Signature parameters
ParameterTypeDefault
frequencykeyword onlystr | NoneNone
aggregationkeyword onlystr'mean'
fillkeyword onlyLiteral['ffill', 'interpolate'] | NoneNone
value_columnskeyword onlySequence[str] | NoneNone
progresskeyword onlybool | NoneNone

Returns TimeSeries

plotmethod
plot(*, ax: Any = None, **kwargs: Any) -> Any

Plot observations on a Matplotlib axes and return that axes.

Signature parameters
ParameterTypeDefault
axkeyword onlyAnyNone
**kwargsAny—

Returns Any

dataproperty
data: pd.DataFrame

Load and return the observations as a DataFrame.

Returns pd.DataFrame

valuesmethod
values() -> NDArray[Any]

Return observations as a NumPy array.

Returns NDArray[Any]

from_dataframeclassmethod
from_dataframe(frame: pd.DataFrame, *, time_column: str | None = None, kind: DatasetKind | None = None, mode: DatasetMode = 'fixed', name: str = '', metadata: Mapping[str, Any] | None = None) -> Dataset

Create a local dataset, preserving a supplied temporal index.

Signature parameters
ParameterTypeDefault
framepd.DataFramerequired
time_columnkeyword onlystr | NoneNone
kindkeyword onlyDatasetKind | NoneNone
modekeyword onlyDatasetMode'fixed'
namekeyword onlystr''
metadatakeyword onlyMapping[str, Any] | NoneNone

Returns Dataset

from_valuesclassmethod
from_values(values: ArrayLike, *, columns: Sequence[str] | None = None, kind: DatasetKind = 'time_series', name: str = '', metadata: Mapping[str, Any] | None = None) -> Dataset

Create a regularly indexed time series from a 1D or 2D array.

Signature parameters
ParameterTypeDefault
valuesArrayLikerequired
columnskeyword onlySequence[str] | NoneNone
kindkeyword onlyDatasetKind'time_series'
namekeyword onlystr''
metadatakeyword onlyMapping[str, Any] | NoneNone

Returns Dataset

from_channelsclassmethod
from_channels(channels: Sequence[str], *, client: DatasetClient | PlatformClient | None = None, loader: Callable[..., object] | None = None, start: str | None = None, end: str | None = None, frequency: str | None = None) -> Dataset

Resolve recorded channels through an API connection or host loader.

Signature parameters
ParameterTypeDefault
channelsSequence[str]required
clientkeyword onlyDatasetClient | PlatformClient | NoneNone
loaderkeyword onlyCallable[..., object] | NoneNone
startkeyword onlystr | NoneNone
endkeyword onlystr | NoneNone
frequencykeyword onlystr | NoneNone

Returns Dataset

start_timemethod
start_time() -> object

Return the first temporal index value; materializes a remote selection.

Returns object

end_timemethod
end_time() -> object

Return the last temporal index value; materializes a remote selection.

Returns object

to_dartsmethod
to_darts() -> DartsDataset

Convert temporal data for optional Darts models without a core dependency.

Returns DartsDataset

DatasetKind

DatasetKind = Literal['time_series', 'sequence', 'independent_samples']

DatasetMode

DatasetMode = Literal['fixed', 'automatic']