swc.aeon.io.api#

API for reading Aeon data from disk.

swc.aeon.io.api.CHUNK_DURATION = 1#

The duration of each acquisition chunk, in whole hours.

swc.aeon.io.api.REFERENCE_EPOCH = datetime.datetime(1904, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)#

The reference epoch for UTC harp time.

class swc.aeon.io.api.Reader(pattern, columns, extension)[source]#

Bases: object

Extracts data from raw files in an Aeon dataset.

columns: SequenceNotStr[str]#

Column labels to use for the data.

extension: str#

Extension of data file pathnames.

pattern: str#

Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Reads data from the specified file.

Parameters:

path (Path) – Path to the data file.

Return type:

DataFrame

Returns:

A DataFrame representing the data extracted from the specified file.

swc.aeon.io.api.aeon(seconds)[source]#

Converts a Harp timestamp, in seconds, to a datetime object.

Deprecated since version 0.2.0: This function is deprecated and will be removed in a future release. Use to_datetime() instead.

Return type:

datetime | DatetimeIndex | Series

swc.aeon.io.api.chunk(time)[source]#
Overloads:

  • time (datetime.datetime) → pd.Timestamp

  • time (pd.DatetimeIndex) → pd.DatetimeIndex

  • time (pd.Series[pd.Timestamp]) → pd.Series

Returns the whole hour acquisition chunk for a measurement timestamp.

Parameters:

time – The object for which to retrieve the acquisition chunk.

Returns:

Return type depends on input.

  • datetime: Timestamp representing the acquisition chunk

  • DatetimeIndex: DatetimeIndex of decoded acquisition chunks

  • Series: Series of decoded acquisition chunks

swc.aeon.io.api.chunk_key(path)[source]#

Returns the acquisition chunk key for the specified file.

Parameters:

path (Path) – The path to the file for which to retrieve the acquisition chunk key.

Return type:

tuple[str, datetime]

Returns:

A tuple containing the epoch string and the acquisition chunk datetime.

swc.aeon.io.api.chunk_range(start, end)[source]#

Returns a fixed frequency DatetimeIndex of acquisition chunk dates.

Parameters:

  • start (datetime) – The left bound for generating chunk dates.

  • end (datetime) – The right bound for generating chunk dates.

Return type:

DatetimeIndex

Returns:

The acquisition chunk range.

swc.aeon.io.api.load(root, reader, start=None, end=None, inclusive='both', time=None, tolerance=None, epoch=None, **kwargs)[source]#

Extracts chunk data from the root path of an Aeon dataset.

Reads all chunk data using the specified data stream reader. A subset of the data can be loaded by specifying an optional time range, or a list of timestamps used to index the data on file. Returned data will be sorted chronologically.

Note

Any timezone-naive values in start, end, and time will be treated as UTC.

Parameters:

  • root (str | PathLike | list[str] | list[PathLike]) – The root path, or prioritised sequence of paths, where data is stored.

  • reader (Reader) – A data stream reader object used to read chunk data from the dataset.

  • start (datetime | None) – The left bound of the time range to extract.

  • end (datetime | None) – The right bound of the time range to extract.

  • inclusive (Literal['both', 'neither', 'left', 'right']) – Specifies whether the start and end bounds are inclusive or exclusive. This argument is only applicable when start and/or end bounds are provided. Options are “both”, “left”, “right”, or “neither”.

  • time (datetime | list[datetime] | DatetimeIndex | DataFrame | None) – A single timestamp, list of timestamps, DatetimeIndex, or a DataFrame with DatetimeIndex specifying the timestamps to extract.

  • tolerance (Timedelta | None) – The maximum distance between original and new timestamps for inexact matches.

  • epoch (str | None) – A wildcard pattern to use when searching epoch data.

  • **kwargs – Optional keyword arguments to forward to reader when reading chunk data.

Return type:

DataFrame

Returns:

A DataFrame containing extracted chunk data, sorted by time.

swc.aeon.io.api.to_datetime(seconds)[source]#
Overloads:

  • seconds (float) → datetime.datetime

  • seconds (pd.Index) → pd.DatetimeIndex

  • seconds (pd.Series) → pd.Series

Converts a UTC Harp timestamp to datetime.

This function converts a scalar, Index or Series into a datetime type.

Parameters:

seconds (float | Index | Series) – The Harp timestamp data, in fractional seconds, to convert to datetime.

Returns:

The decoded UTC Harp timestamp data. Return type depends on input.

  • scalar: datetime object

  • Index: DatetimeIndex of datetime64 dtype

  • Series: Series of datetime64 dtype

swc.aeon.io.api.to_seconds(time)[source]#
Overloads:

  • time (datetime.datetime) → float

  • time (pd.DatetimeIndex) → pd.Index

  • time (pd.Series) → pd.Series

Converts datetime to UTC Harp timestamp.

This function converts a datetime object, DatetimeIndex or Series into a UTC Harp timestamp type.

Parameters:

time (datetime | DatetimeIndex | Series) – The object to convert to a UTC Harp timestamp type.

Returns:

The UTC Harp timestamp data, in fractional seconds. Return type depends on input.

  • datetime: scalar

  • DatetimeIndex: Index

  • Series: Series