# Import statement
from hottbox.core import Tensor
Tensor(array, custom_state=None, mode_names=None)[source]¶This class describes multidimensional data.
All its methods implement all common operation on a tensor alone
N-dimensional array
Provides flexibility to create a Tensor object in folded, unfolded or rotated state. Use with caution.
If provided, then should include only the following keys:
‘mode_order’ -> tuple of lists
‘normal_shape’ -> tuple
‘rtype’ -> str
Description of the tensor modes.
If nothing is specified then all modes of the created Tensor
get generic names ‘mode-0’, ‘mode-1’ etc.
Attributes
_data |
(np.ndarray) N-dimensional array. |
_modes |
(list[Mode]) Description of the tensor modes in form of a list where each element is object of |
_state |
(State) Reference to meta information about transformations applied to a tensor, such as unfolding, vectorising etc. Meta information. |
If parameter array is not of np.ndarray type.
If parameter custom_state is inconsistent with provided array
or does not meet requirements for creating State of the tensor.
If parameter mode_names is inconsistent with provided array and custom_state
or does not meet requirements for creating list of Mode of the tensor.
Examples
Creating a tensor with default parameters for meta data
>>> import numpy as np
>>> from hottbox.core import Tensor
>>> data = np.arange(24).reshape(2, 3, 4)
>>> tensor = Tensor(data)
>>> print(tensor)
This tensor is of order 3 and consists of 24 elements.
Sizes and names of its modes are (2, 3, 4) and ['mode-0', 'mode-1', 'mode-2'] respectively.
Creating a tensor with custom mode names
>>> import numpy as np
>>> from hottbox.core import Tensor
>>> data = np.arange(24).reshape(2, 3, 4)
>>> tensor = Tensor(data, mode_names=["Year", "Month", "Day"])
>>> tensor.show_state()
State(normal_shape=(2, 3, 4), rtype='Init', mode_order=([0], [1], [2]))
>>> print(tensor)
This tensor is of order 3 and consists of 24 elements.
Sizes and names of its modes are (2, 3, 4) and ['Year', 'Month', 'Day'] respectively.
Creating a tensor in custom state
>>> import numpy as np
>>> from hottbox.core import Tensor
>>> data = np.arange(24).reshape(2, 3*4)
>>> tensor = Tensor(data, custom_state={"normal_shape": (2, 3, 4),
... "mode_order": ([0], [1, 2]),
... "rtype": "T"}
>>> data.shape
(2, 12)
>>> tensor.shape
(2, 12)
>>> tensor.show_state()
State(normal_shape=(2, 3, 4), rtype='T', mode_order=([0], [1, 2]))
>>> print(tensor)
This tensor is of order 2 and consists of 24 elements.
Sizes and names of its modes are (2, 12) and ['mode-0', 'mode-1_mode-2'] respectively.
Methods
|
Equivalent to multidimnesional slicing |
|
Produces a copy of itself as a new object |
|
Copy modes meta from tensor representation |
|
Expose some metrics |
|
Fold to the original shape |
|
Mode-n product of a tensor with a matrix |
|
Set all meta information with respect to the current shape of data array |
|
Drop index for the specified mode number |
|
Set default name for the specified mode number |
|
Set index for specified mode |
|
Rename modes of a tensor |
|
Show the current state of the |
|
Perform mode-n unfolding to a matrix |
|
Perform vectorisation of a tensor |
|
Works in the same way as access but permits changing of the tensor data |
access(self, inds, mode)[source]¶Equivalent to multidimnesional slicing
The index of the axis. e.g [:,:,0] will be at mode=2, inds=0
The axis to access
Overwrite slice with a subtensor
Numpy array with the formulated subtensor
copy(self)[source]¶Produces a copy of itself as a new object
New object of Tensor class with attributes having the same values, but no memory space is shared
Notes
Only the last transformation will be copied if tensor is not in normal state
copy_modes(self, tensor)[source]¶Copy modes meta from tensor representation
data¶N-dimensional array with data values
fold(self, inplace=True)[source]¶Fold to the original shape
If True, then modifies itself. If False, then creates new object (copy)
Tensor of original shape (self.ft_shape)
If tensor is in normal state: self.in_normal_state is True.
Notes
Basically, this method can be called in order to undo both self.unfold and self.vectorise
frob_norm¶Frobenious norm of a tensor
ft_shape¶Shape of the a tensor in normal format (without being in unfolded or folded state)
in_normal_state¶Checks state of a tensor
Notes
If returns True, then can call unfold and mode_n_product.
If returns False, then can call fold
mode_n_product(self, matrix, mode, new_name=None, inplace=True)[source]¶Mode-n product of a tensor with a matrix
2D array
Specifies mode along which a tensor is multiplied by a matrix
If True, then modifies itself. If False, then creates new object (copy)
New name for the corresponding mode after computing this product. See Notes-3 for more info
The result of the mode-n product of a tensor with a matrix along specified mode.
If tensor is not in normal state: self.in_normal_state is False.
If there is uncertainty with assigning new name for the tensor.modes[mode].
Notes
Mode-n product operation changes the self._state._normal_shape attribute
Remember that mode-n product changes the shape of the tensor. Presumably, it also changes the interpretation of that mode depending on the matrix
If matrix is an object of Tensor class then you shouldn’t specify new_name, since
it will be changed to matrix.mode_names[0]
If matrix.mode_names[0] == "mode-0" then no changes to tensor.mode_names will be made
mode_names¶Description of the tensor modes in current state
modes¶Meta data for the modes of a tensor
order¶Order of a tensor
reset_meta(self)[source]¶Set all meta information with respect to the current shape of data array
reset_mode_index(self, mode=None)[source]¶Drop index for the specified mode number
Mode number which index to be dropped By default resets all indices
reset_mode_name(self, mode=None)[source]¶Set default name for the specified mode number
Mode number which name to be set to default value By default resets names of all modes
set_mode_index(self, mode_index)[source]¶Set index for specified mode
New indices for the tensor modes in form of a dictionary. Key defines the mode whose index to be changed. Value contains a list of new indices for this mode.
If parameter mode_index is inconsistent with self.modes.
set_mode_names(self, mode_names)[source]¶Rename modes of a tensor
New names for the tensor modes in form of a dictionary The name of the mode defined by the Key of the dict will be renamed to the corresponding Value
Return self so that methods could be chained
If parameter mode_names is inconsistent with self.modes.
shape¶Shape of a tensor in current state
Sizes of all dimensions of a tensor
size¶Number of elements in a tensor
unfold(self, mode, rtype='T', inplace=True)[source]¶Perform mode-n unfolding to a matrix
Specifies a mode along which a tensor will be unfolded
Defines an unfolding convention.
If True, then modifies itself. If False, then creates new object (copy)
Unfolded version of a tensor
If tensor is not in normal state: self.in_normal_state is False.
If parameter rtype is not one of {‘T’, ‘K’}.
vectorise(self, rtype='T', inplace=True)[source]¶Perform vectorisation of a tensor
Defines a vectorisation convention.
If True, then modifies itself. If False, then creates new object (copy)
Vectorised version of a tensor
If tensor is not in normal state: self.in_normal_state is False.
If parameter rtype is not one of {‘T’, ‘K’}.