API Reference

This page provides detailed API documentation for all public classes and functions in the npdict package.

NumpyNDArrayWrappedDict

class npdict.wrap.NumpyNDArrayWrappedDict(lists_keystrings: list[list[str]], default_initial_value: float = 0.0)[source]

Bases: dict

A dictionary-like class that wraps a NumPy n-dimensional array.

This class provides a dictionary interface to a NumPy array, where the keys are tuples of strings and the values are the corresponding elements in the array. The class maintains a mapping between string keys and array indices, allowing for more intuitive access to array elements.

__getitem__(item: tuple[str, ...] | str) → float[source]

Get the value at the specified keys.

Parameters:

item (Tuple[str, ...] | str) – A tuple of string keys, one for each dimension of the array.

Returns:

The value at the specified keys.

Return type:

float

Raises:

WrongArrayDimensionException – If the number of keys does not match the number of dimensions in the array.

__init__(lists_keystrings: list[list[str]], default_initial_value: float = 0.0)[source]

Initialize a new NumpyNDArrayWrappedDict.

Parameters:

  • lists_keystrings (list[list[str]]) – A list of lists of strings, where each inner list contains the keys for one dimension of the array. For example, [[‘a’, ‘b’], [‘c’, ‘d’]] would create a 2x2 array with keys (‘a’, ‘c’), (‘a’, ‘d’), (‘b’, ‘c’), (‘b’, ‘d’).

  • default_initial_value (float, optional) – The default value to fill the array with, by default 0.0.

Raises:

DuplicatedKeyError – If there are duplicate keys in any of the lists of keys.

__iter__() → Generator[tuple[str, ...], None, None][source]

Iterate over all possible key tuples in the dictionary.

Yields:

Tuple[str, …] – A tuple of string keys, one for each dimension of the array.

__len__() → int[source]

Return the total number of elements in the dictionary.

Returns:

The total number of elements in the dictionary.

Return type:

int

__repr__() → str[source]

Return a string representation of the dictionary.

Returns:

A string representation of the dictionary.

Return type:

str

__setitem__(key: tuple[str, ...] | str, value: float) → None[source]

Set the value at the specified keys.

Parameters:

  • key (Tuple[str, ...] | str) – A tuple of string keys, one for each dimension of the array.

  • value (float) – The value to set at the specified keys.

Raises:

WrongArrayDimensionException – If the number of keys does not match the number of dimensions in the array.

__str__() → str[source]

Return a string representation of the dictionary.

Returns:

A string representation of the dictionary.

Return type:

str

property dimension_sizes: list[int]

Get the size of each dimension in the array.

Returns:

A list of the size of each dimension in the array.

Return type:

list[int]

classmethod from_dict(oridict: dict[tuple[str, ...], float], default_initial_value: float = 0.0) → Self[source]

Create a new NumpyNDArrayWrappedDict from a standard Python dictionary.

This method automatically extracts the keys for each dimension from the dictionary.

Parameters:

  • oridict (dict[Tuple[str, ...], float]) – A standard Python dictionary with keys as tuples of strings and values as floats.

  • default_initial_value (float, optional) – The default value to fill the array with for keys not present in oridict, by default 0.0.

Returns:

A new NumpyNDArrayWrappedDict with the same keys and values as oridict.

Return type:

NumpyNDArrayWrappedDict

classmethod from_dict_given_keywords(lists_keywords: list[list[str]], oridict: dict[tuple[str, ...], float], default_initial_value: float = 0.0) → Self[source]

Create a new NumpyNDArrayWrappedDict from a standard Python dictionary with given keywords.

Parameters:

  • lists_keywords (list[list[str]]) – A list of lists of strings, where each inner list contains the keys for one dimension of the array.

  • oridict (dict[Tuple[str, ...], float]) – A standard Python dictionary with keys as tuples of strings and values as floats.

  • default_initial_value (float, optional) – The default value to fill the array with for keys not present in oridict, by default 0.0.

Returns:

A new NumpyNDArrayWrappedDict with the same keys and values as oridict.

Return type:

NumpyNDArrayWrappedDict

classmethod from_numpyarray_given_keywords(lists_keywords: list[list[str]], numarray: ndarray) → Self[source]

Create a new NumpyNDArrayWrappedDict from a NumPy array with given keywords.

Parameters:

  • lists_keywords (list[list[str]]) – A list of lists of strings, where each inner list contains the keys for one dimension of the array.

  • numarray (np.ndarray) – The NumPy array containing the values for the new dictionary.

Returns:

A new NumpyNDArrayWrappedDict with the specified keys and values from the NumPy array.

Return type:

NumpyNDArrayWrappedDict

Raises:

  • WrongArrayShapeException – If the shape of the array does not match the number of keywords in each dimension.

  • WrongArrayDimensionException – If the number of dimensions in the array does not match the number of keyword lists.

generate_dict(nparray: ndarray) → Self[source]

Generate a new NumpyNDArrayWrappedDict with the same keys but different values.

Parameters:

nparray (np.ndarray) – The NumPy array containing the new values.

Returns:

A new NumpyNDArrayWrappedDict with the same keys but different values.

Return type:

NumpyNDArrayWrappedDict

Raises:

  • WrongArrayDimensionException – If the number of dimensions in the array does not match the number of dimensions in the dictionary.

  • WrongArrayShapeException – If the shape of the array does not match the shape of the dictionary.

get(key: tuple[str, ...], default_value: float | None = None) → float | None[source]

Get the value at the specified keys, or default value if the key does not exist.

Parameters:

  • key (Tuple[str, ...]) – A tuple of string keys, one for each dimension of the array.

  • default_value (float, optional) – Default value to return if the key cannot be found.

Returns:

The value at the specified keys.

Return type:

float

Raises:

WrongArrayDimensionException – If the number of keys does not match the number of dimensions in the array.

get_key_index(dim: int, key: str) → int[source]

Return the index of a given key in a certain dimension.

Parameters:

  • dim (int) – dimension of the key

  • key (str) – key of which you want to look up the index

Returns:

index of the given key in the given dimension

Return type:

int

items()[source]

Get all key-value pairs in the dictionary.

Returns:

A list of all key-value pairs in the dictionary.

Return type:

list[Tuple[Tuple[str, …], float]]

keys()[source]

Get all possible key tuples in the dictionary.

Returns:

A list of all possible key tuples.

Return type:

list[Tuple[str, …]]

classmethod load(filepath: str | PathLike) → Self[source]
save(filepath: str | PathLike) → None[source]
property tensor_dimensions: int

Get the number of dimensions in the array.

Returns:

The number of dimensions in the array.

Return type:

int

to_dict() → dict[tuple[str, ...], float][source]

Convert the wrapped dictionary to a standard Python dictionary.

Returns:

A standard Python dictionary with the same keys and values as the wrapped dictionary.

Return type:

dict[Tuple[str, …], float]

to_numpy() → ndarray[source]

Convert the wrapped dictionary to a NumPy array.

Returns:

The NumPy array containing the values of the dictionary.

Return type:

np.ndarray

update(new_dict: dict)[source]

This method is not supported for NumpyNDArrayWrappedDict.

Raises:

TypeError – Always raises this exception as the method is not supported.

values()[source]

Get all values in the dictionary.

Returns:

A list of all values in the dictionary.

Return type:

list[float]

SparseArrayWrappedDict

class npdict.sparse.SparseArrayWrappedDict(lists_keystrings: list[list[str]], default_initial_value: float = 0.0)[source]

Bases: NumpyNDArrayWrappedDict

A dictionary-like class that wraps a sparse array.

This class provides a dictionary interface to a sparse array, where the keys are tuples of strings and the values are the corresponding elements in the array. The class maintains a mapping between string keys and array indices, allowing for more intuitive access to array elements.

This implementation uses sparse arrays instead of NumPy arrays, which is more memory-efficient for arrays with many zero values.

__getitem__(item: Tuple[str, ...] | str) → float[source]

Get the value at the specified keys.

Parameters:

item (Tuple[str, ...] | str) – A tuple of string keys, one for each dimension of the array.

Returns:

The value at the specified keys.

Return type:

float

Raises:

WrongArrayDimensionException – If the number of keys does not match the number of dimensions in the array.

__init__(lists_keystrings: list[list[str]], default_initial_value: float = 0.0)[source]

Initialize a new SparseArrayWrappedDict.

Parameters:

  • lists_keystrings (list[list[str]]) – A list of lists of strings, where each inner list contains the keys for one dimension of the array. For example, [[‘a’, ‘b’], [‘c’, ‘d’]] would create a 2x2 array with keys (‘a’, ‘c’), (‘a’, ‘d’), (‘b’, ‘c’), (‘b’, ‘d’).

  • default_initial_value (float, optional) – The default value to fill the array with, by default 0.0.

Raises:

DuplicatedKeyError – If there are duplicate keys in any of the lists of keys.

__repr__() → str[source]

Return a string representation of the dictionary.

Returns:

A string representation of the dictionary.

Return type:

str

__setitem__(key: Tuple[str, ...] | str, value: float) → None[source]

Set the value at the specified keys.

Parameters:

  • key (Tuple[str, ...] | str) – A tuple of string keys, one for each dimension of the array.

  • value (float) – The value to set at the specified keys.

Raises:

WrongArrayDimensionException – If the number of keys does not match the number of dimensions in the array.

classmethod from_NumpyNDArrayWrappedDict(npwrapped_dict: NumpyNDArrayWrappedDict, default_initial_value: float = 0.0) → Self[source]

Create a new SparseArrayWrappedDict from a NumpyNDArrayWrappedDict.

This method converts a dense NumPy array-based dictionary to a sparse array-based dictionary, which is more memory-efficient for arrays with many zero values.

Parameters:

  • npwrapped_dict (NumpyNDArrayWrappedDict) – The NumpyNDArrayWrappedDict to convert. Must not be a SparseArrayWrappedDict.

  • default_initial_value (float, optional) – The default value to fill the sparse array with, by default 0.0.

Returns:

A new SparseArrayWrappedDict with the same keys and values as the input dictionary.

Return type:

SparseArrayWrappedDict

Raises:

TypeError – If the input dictionary is already a SparseArrayWrappedDict.

classmethod from_dict_given_keywords(lists_keywords: list[list[str]], oridict: dict[Tuple[str, ...], float], default_initial_value: float = 0.0) → Self[source]

Create a new SparseArrayWrappedDict from a standard Python dictionary with given keywords.

Parameters:

  • lists_keywords (list[list[str]]) – A list of lists of strings, where each inner list contains the keys for one dimension of the array.

  • oridict (dict[Tuple[str, ...], float]) – A standard Python dictionary with keys as tuples of strings and values as floats.

  • default_initial_value (float, optional) – The default value to fill the array with for keys not present in oridict, by default 0.0.

Returns:

A new SparseArrayWrappedDict with the same keys and values as oridict.

Return type:

SparseArrayWrappedDict

classmethod from_numpyarray_given_keywords(lists_keywords: list[list[str]], numarray: ndarray) → Self[source]

Create a new SparseArrayWrappedDict from a NumPy array with given keywords.

Parameters:

  • lists_keywords (list[list[str]]) – A list of lists of strings, where each inner list contains the keys for one dimension of the array.

  • numarray (np.ndarray) – The NumPy array containing the values for the new dictionary.

Returns:

A new SparseArrayWrappedDict with the specified keys and values from the NumPy array.

Return type:

SparseArrayWrappedDict

Raises:

NotImplementedError – This method is not implemented for SparseArrayWrappedDict.

classmethod from_sparsearray_given_keywords(lists_keywords: list[list[str]], sparsearray: SparseArray) → Self[source]

Create a new SparseArrayWrappedDict from a sparse array with given keywords.

Parameters:

  • lists_keywords (list[list[str]]) – A list of lists of strings, where each inner list contains the keys for one dimension of the array.

  • sparsearray (sparse.SparseArray) – The sparse array containing the values for the new dictionary.

Returns:

A new SparseArrayWrappedDict with the specified keys and values from the sparse array.

Return type:

SparseArrayWrappedDict

Raises:

  • WrongArrayShapeException – If the shape of the array does not match the number of keywords in each dimension.

  • WrongArrayDimensionException – If the number of dimensions in the array does not match the number of keyword lists.

generate_dict(new_array: ndarray | SparseArray, dense: bool = False) → Self[source]

Generate a new dictionary with the same keys but different values.

Parameters:

  • new_array (Union[np.ndarray, sparse.SparseArray]) – The array containing the new values. Can be either a NumPy array or a sparse array.

  • dense (bool, optional) – If True, returns a NumpyNDArrayWrappedDict. If False, returns a SparseArrayWrappedDict. Default is False.

Returns:

A new dictionary with the same keys but different values.

Return type:

Union[NumpyNDArrayWrappedDict, SparseArrayWrappedDict]

Raises:

  • WrongArrayDimensionException – If the number of dimensions in the array does not match the number of dimensions in the dictionary.

  • WrongArrayShapeException – If the shape of the array does not match the shape of the dictionary.

classmethod load(filepath: str | PathLike) → Self[source]
save(filepath: str | PathLike) → None[source]
to_coo() → COO[source]

Convert the wrapped sparse array to a COO (Coordinate) format sparse array.

Returns:

A COO format sparse array containing the same values as the wrapped array.

Return type:

sparse.COO

to_dok() → DOK[source]

Get the underlying DOK (Dictionary of Keys) format sparse array.

Returns:

The underlying DOK format sparse array.

Return type:

sparse.DOK

to_numpy() → ndarray[source]

Convert the wrapped sparse array to a dense NumPy array.

Returns:

A dense NumPy array containing the values of the sparse array.

Return type:

np.ndarray

Exceptions