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 columns in the spatial dimensions.
row_nameslist of strings, optional: Names of the row indices.
col_nameslist of strings, optional: Names of the column indices.

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)

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

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

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

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

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.

property units#: Data units, if any

property values#

Return a Numpy representation of the DataFrame.

Warning

We recommend using DataFrame.to_numpy() instead.

Only the values in the DataFrame will be returned, the axes labels will be removed.

Returns:

numpy.ndarray: The values of the DataFrame.

See also

DataFrame.to_numpy: Recommended alternative to this method.
DataFrame.index: Retrieve the index labels.
DataFrame.columns: Retrieving the column names.

Notes

The dtype will be a lower-common-denominator dtype (implicit upcasting); that is to say if the dtypes (even of numeric types) are mixed, the one that accommodates all will be chosen. Use this with care if you are not dealing with the blocks.

e.g. If the dtypes are float16 and float32, dtype will be upcast to float32. If dtypes are int32 and uint8, dtype will be upcast to int32. By numpy.find_common_type() convention, mixing int64 and uint64 will result in a float64 dtype.

Examples

A DataFrame where all columns are the same type (e.g., int64) results in an array of the same type.

>>> df = pd.DataFrame({'age':    [ 3,  29],
...                    'height': [94, 170],
...                    'weight': [31, 115]})
>>> df
   age  height  weight
0    3      94      31
1   29     170     115
>>> df.dtypes
age       int64
height    int64
weight    int64
dtype: object
>>> df.values
array([[  3,  94,  31],
       [ 29, 170, 115]])

A DataFrame with mixed type columns(e.g., str/object, int64, float32) results in an ndarray of the broadest type that accommodates these mixed types (e.g., object).

>>> df2 = pd.DataFrame([('parrot',   24.0, 'second'),
...                     ('lion',     80.5, 1),
...                     ('monkey', np.nan, None)],
...                   columns=('name', 'max_speed', 'rank'))
>>> df2.dtypes
name          object
max_speed    float64
rank          object
dtype: object
>>> df2.values
array([['parrot', 24.0, 'second'],
       ['lion', 80.5, 1],
       ['monkey', nan, None]], dtype=object)

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: 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 columns in the spatial dimensions.
row_nameslist of strings, optional: Names of the row indices.
col_nameslist of strings, optional: Names of the column indices.

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 columns in the spatial dimensions.
row_nameslist of strings, optional: Names of the row indices.
col_nameslist of strings, optional: Names of the column indices.

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 columns in the spatial dimensions.
row_nameslist of strings, optional: Names of the row indices.
col_nameslist of strings, optional: Names of the column indices.

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).

Cubes#

This Page