Cubes#

Classes and tools for working with data cubes, continuous regions of time series data.

class lkdata.datacube.Cube(data, time_indices=None, row_indices=None, col_indices=None, **kwargs)[source]#

A three-dimensional data structure representing time series of two-dimensional spatial data.

This class extends pandas.DataFrame to handle 3D data with time and spatial dimensions. It provides methods for data manipulation, indexing, and statistical operations.

Parameters:

dataarray-like: The input data for the Cube. Should be 2D or 3D array-like.
uncertaintyarray-like
time_indicesarray-like or dictionary of array-like, optional: Indices for the time dimension. If an array-like, the default name “time_index” will be assigned. If a dictionary, each entry will be added to the MultiIndex with the corresponding key. A default RangeIndex from 0 to the length of the given index (or data, when this argument is not provided) with the key “time_index” is added if the “time_index” key is not specified. If this argument and no keyword argument “index” or “ntime” are given, a RangeIndex from 0 to the size of the first dimension of the data is added as “time_index”.
row_indicesarray-like or dictionary of array-like, optional: Indices for the row dimension. If an array-like, the default name “row” will be assigned. If a dictionary, each entry will be added to the MultiIndex with the corresponding key. If this argument and “nrow” are not given, a default RangeIndex from 0 to the size of the second dimension of the given data is added as “row”.
col_indicesarray-like or dictionary of array-like, optional: Indices for the column dimension. If an array-like, the default name “col” will be assigned. If a dictionary, each entry will be added to the MultiIndex with the corresponding key. If this argument and “ncol” are not given, a default RangeIndex from 0 to the size of the third dimension of the given data is added as “col”.
**kwargs: Any keyword arguments for constructing a pandas DataFrame, like index and columns, will be treated appropriately. Any unrecognized keys are stored as class attributes. If the given data is flattened nrow and ncol must be specified. The class will use data.reshape((ntime, nrow, ncol)) to store the data and generate automatic indices based on nrow and ncol, unless otherwise specified.

Attributes:

array: Numpy array representation with shape (ntime, nrow, ncol)
nseries: Total number of time series contained in the cube
styler: The pandas.DataFrame styler for single cadence frames.
units: Data units, if any
values: Return a Numpy representation of the DataFrame.
nrowint, optional: Number of rows in the spatial dimensions.
ncolint, optional: Number of distinct columns in the data
row_nameslist of strings, optional: List of distinct row names
col_nameslist of strings, optional: List of distinct column names

Methods

describe_cube(printoptions)**	Prints a description of the Cube instance.
from_pandas(data: pd.DataFrame, kwargs)**	Converts a pd.DataFrame to a Cube.
make_cadence_label(cadence: int)	Creates a formatted cadence label for the HTML representation.
single_frame(cadence: int)	Creates a stylized single cadence frame of the cube.
to_seriescollection(row, col, kwargs)**	Converts the Cube to a DataSeriesCollection with given row and column indices.

property array#: Numpy array representation with shape (ntime, nrow, ncol)

property col_names: List[str]#

List of distinct column names

Note: this is distinct from pandas.Columns. The columns referred to here correspond to the columnal spatial portion of the given data rather than the tabular columns of the DataFrame.

property row_names: List[str]#

List of distinct row names

Note: The rows referred to here correspond to the row spatial portion of the given data rather than the tabular rows of the DataFrame (which correpsond to time indices).

property ncol#

Number of distinct columns in the data

Note: this is distinct from the number of pandas.Columns. The columns referred to here correspond to the columnal spatial portion of the given data rather than the tabular columns of the DataFrame.

property nseries#: Total number of time series contained in the cube

property styler#: The pandas.DataFrame styler for single cadence frames.

property units#: Data units, if any

describe_cube(**printoptions)[source]#

Print a description of the Cube instance.

This description prints information about the temporal and spatial indices available in the Cube. It also prints out any additional user-assigned properties given via keyword arguments on initialization.

classmethod from_pandas(data, row_names=None, col_names=None, nrow=None, ncol=None, **kwargs)[source]#

Convert a pd.DataFrame to a DataCube

Parameters:

datapandas DataFrame
row_namestr or list of strings, optional: Name of “row” index in DataFrame.columns if columns is a MultiIndex.
col_namestr or list of strings, optional: Name of “col” index in Dataframe.columns if columns is a MultiIndex.
nrowint, optional: number of rows to be inferred from the DataFrame.columns. Ignored if row_name is given.
ncolint, optional: number of columns to be inferred from the DataFrame.columns. Ignored if col_name is given.
Note:: Keywords index and columns may not be specified, they are inferred from the pandas DataFrame.

make_cadence_label(cadence)[source]#

Create a formatted cadence label for the HTML repr

Parameters:

cadenceint: Cadence for which a label should be created

Returns:

str: Cadence label for the HTML repr

get_single_frame(cadence)[source]#

Create a stylized single cadence frame of a datacube

This is distinct from to_seriescollection() and from retreiving a single cadence of a DataCube. The former returns a pandas DataFrame with all pixels along the column axis and all cadences along the index axis. The latter returns a DataCube with a single cadence, time information is retained and remains the first index.

This returns a pandas DataFrame with rows on the index axis, and columns along the column axis. Time information is lost.

Return type:: DataFrame

stylize_frame(df, **kwargs)[source]#

Stylize a pandas.DataFrame for display.

Parameters:

dfpandas.DataFrame: The DataFrame to be stylized.
**kwargsdict: Additional keyword arguments for styling.

Returns:

pandas.io.formats.style.Styler: The stylized DataFrame.

Notes

This method applies various styling options to the DataFrame, including background gradient, precision formatting, and table styles.

to_seriescollection(row, col, **kwargs)[source]#

Convert lkdata.Cube to lkdata.SeriesCollection with the given row and column.

Parameters:

row: Union[int, float, List[Union[int, float]], slice]: Index/list of indices or slice of row indices to include.
col: Union[int, float, List[Union[int, float]], slice]: Index/list of indices or slice of column indices to include.

Returns:

SeriesCollection: A SeriesCollection object of the same type as the input data.

class lkdata.datacube.DataCube(data, uncertainty=None, time_indices=None, row_indices=None, col_indices=None, **kwargs)[source]#

A Cube object which contains data with time and 2 spatial dimensions.

Parameters:

dataArrayLike: The input data for the Cube. Should be 2D or 3D array-like.
uncertaintyUnion[List, ArrayLike]
time_indicesUnion[Dict, List, None], optional: Indices for the time dimension.
row_indicesUnion[Dict, List, None], optional: Indices for the row dimension.
col_indicesUnion[Dict, List, None], optional: Indices for the column dimension.
**kwargs: Any keyword arguments for constructing a pandas DataFrame, like index and columns, will be treated appropriately. Any unrecognized keys are stored as class attributes.

Attributes:

array: Numpy array representation
nseries: Total number of time series contained in the cube
styler: The pandas.DataFrame styler for single cadence frames.
units: Units associated with the data and uncertanties.
values: Return a Numpy representation of the DataFrame.
nrowint, optional: Number of rows in the spatial dimensions.
ncolint, optional: Number of distinct columns in the data
row_nameslist of strings, optional: List of distinct row names
col_nameslist of strings, optional: List of distinct column names

Methods

describe_cube(printoptions)**	Prints a description of the Cube instance.
from_pandas(data: pd.DataFrame, kwargs)**	Converts a pd.DataFrame to a Cube.
make_cadence_label(cadence: int)	Creates a formatted cadence label for the HTML representation.
single_frame(cadence: int)	Creates a stylized single cadence frame of the cube.
to_seriescollection(row, col, kwargs)**	Converts the Cube to a DataSeriesCollection with given row and column indices.

class lkdata.datacube.BoolCube(data, time_indices=None, row_indices=None, col_indices=None, **kwargs)[source]#

A Cube object which contains boolean entries.

Parameters:

dataArrayLike[bool]: The input data for the Cube. Should be 2D or 3D array-like.
time_indicesUnion[Dict, List], optional: Indices for the time dimension.
row_indicesUnion[Dict, List], optional: Indices for the row dimension.
col_indicesUnion[Dict, List], optional: Indices for the column dimension.
**kwargs: Any keyword arguments for constructing a pandas DataFrame, like index and columns, will be treated appropriately. Any unrecognized keys are stored as class attributes.

Attributes:

array: Numpy array representation with shape (ntime, nrow, ncol)
nseries: Total number of time series contained in the cube
styler: The pandas.DataFrame styler for single cadence frames.
units: Data units, if any
values: Return a Numpy representation of the DataFrame.
nrowint, optional: Number of rows in the spatial dimensions.
ncolint, optional: Number of distinct columns in the data
row_nameslist of strings, optional: List of distinct row names
col_nameslist of strings, optional: List of distinct column names

Methods

describe_cube(printoptions)**	Prints a description of the Cube instance.
from_pandas(data: pd.DataFrame, kwargs)**	Converts a pd.DataFrame to a Cube.
make_cadence_label(cadence: int)	Creates a formatted cadence label for the HTML representation.
single_frame(cadence: int)	Creates a stylized single cadence frame of the cube.
to_seriescollection(row, col, kwargs)**	Converts the Cube to a DataSeriesCollection with given row and column indices.

class lkdata.datacube.BitwiseCube(data, time_indices=None, row_indices=None, col_indices=None, code_dict=None, display_as='int', **kwargs)[source]#

A Cube object which contains bitwise entries.

Parameters:

dataArrayLike: The input data for the Cube. Should be 2D or 3D array-like.
time_indicesUnion[Dict, List], optional: Indices for the time dimension.
row_indicesUnion[Dict, List], optional: Indices for the row dimension.
col_indicesUnion[Dict, List], optional: Indices for the column dimension.
code_dictDict, optional: A dictionary mapping bit values to their definitions.
display_asstr, optional: How to display the values. Options are “int”, “bitset”, or “detailed”.
**kwargs: Any keyword arguments for constructing a pandas DataFrame, like index and columns, will be treated appropriately. Any unrecognized keys are stored as class attributes.

Attributes:

array: Numpy array representation with shape (ntime, nrow, ncol)
nseries: Total number of time series contained in the cube
styler: The pandas.DataFrame styler for single cadence frames.
units: Data units, if any
values: Return a Numpy representation of the DataFrame.
nrowint, optional: Number of rows in the spatial dimensions.
ncolint, optional: Number of distinct columns in the data
row_nameslist of strings, optional: List of distinct row names
col_nameslist of strings, optional: List of distinct column names

Methods

describe_cube(printoptions)**	Prints a description of the Cube instance.
from_pandas(data: pd.DataFrame, kwargs)**	Converts a pd.DataFrame to a Cube.
make_cadence_label(cadence: int)	Creates a formatted cadence label for the HTML representation.
single_frame(cadence: int)	Creates a stylized single cadence frame of the cube.
to_seriescollection(row, col, kwargs)**	Converts the Cube to a DataSeriesCollection with given row and column indices.

A Cube object which contains bitwise values.

Parameters:

dataUnion[List, np.ndarray]: The input data for the BitwiseCube. Values must be integers or sets of integers, or bitwise strings.
time_indicesUnion[Dict, List, None], optional: Indices for the time dimension.
row_indicesUnion[Dict, List, None], optional: Indices for the row dimension.
col_indicesUnion[Dict, List, None], optional: Indices for the column dimension.
**kwargs: Additional keyword arguments to pass to the parent class.

Attributes:

codesDict: Return the code dictionary used in this Bitwise product.
values_displaystr: Get the current display mode for values.

property values_display#

Get the current display mode for values.

Returns:

str: The current display mode for values. Possible values are: - ‘int’: Display the raw integer values. - ‘bitset’: Display the values as sets of powers of 2. - ‘detailed’: Display the values as dictionaries mapping powers of 2 to their corresponding codes.

Notes

This property is used to control how values are displayed in the object’s string representation and in any generated output (e.g., when using Jupyter notebooks).