torch_openreml.covariance.DummyMatrix¶

class torch_openreml.covariance.DummyMatrix(*args, levels=None, lex_order=True, drop_first=False, drop_empty_cols=False)[source]¶

Bases: Matrix

Fixed dummy matrix constructed from categorical input.

\[\symbf{V} = \symbf{X}\]

where \(\symbf{X}\) is constructed from *args at initialisation and remains fixed thereafter. This matrix has no trainable parameters, so grad() always returns (None, []).

__call__() follows the dtype and the device of its input; when it receives none, the PyTorch default dtype and device are used.

Initialize a fixed dummy matrix from numeric or categorical input.

Parameters:

*args (list, tuple, or pandas.Series) – Input data. One or many lists of strings for categorical data.
levels (list or tuple, optional) – Levels of each list of strings. Defaults to a list of sorted unique elements in each list of strings.
lex_order (bool, optional) – If True, the result columns are lexically ordered.
drop_first (bool, optional) – Whether to drop the first column. Defaults to False.
drop_empty_cols (bool, optional) – Whether to drop empty columns.

Raises:

TypeError – If any args is not a :class: list or tuple.

Example:

from torch_openreml.covariance import DummyMatrix

rep = ["rep1", "rep2", "rep2"]
block = ["block1", "block2", "block1"]

mat = DummyMatrix(rep, block)
print(mat())
print(mat.colnames)

tensor([[1., 0., 0., 0.],
        [0., 0., 0., 1.],
        [0., 0., 1., 0.]])
['rep1⋈block1', 'rep1⋈block2', 'rep2⋈block1', 'rep2⋈block2']

mat = DummyMatrix(rep, block, drop_first=True)
print(mat())
print(mat.colnames)

tensor([[0., 0., 0.],
        [0., 0., 1.],
        [0., 1., 0.]])
['rep1⋈block2', 'rep2⋈block1', 'rep2⋈block2']

mat = DummyMatrix(rep, block, levels=[["rep1", "rep2", "rep3"], ["block1", "block2"]])
print(mat())
print(mat.colnames)

tensor([[1., 0., 0., 0., 0., 0.],
        [0., 0., 0., 1., 0., 0.],
        [0., 0., 1., 0., 0., 0.]])
['rep1⋈block1', 'rep1⋈block2', 'rep2⋈block1', 'rep2⋈block2', 'rep3⋈block1', 'rep3⋈block2']

mat = DummyMatrix(rep, block, levels=[["rep3", "rep1"], ["block1", "block2"]], lex_order=False)
print(mat())
print(mat.colnames)

tensor([[0., 0., 1., 0.],
        [0., 0., 0., 0.],
        [0., 0., 0., 0.]])
['rep3⋈block1', 'rep3⋈block2', 'rep1⋈block1', 'rep1⋈block2']

mat = DummyMatrix(rep, block, levels=[["rep2", "rep1"], ["block1", "block2"]], lex_order=False, drop_empty_cols=True)
print(mat())
print(mat.colnames)

tensor([[0., 0., 1.],
        [0., 1., 0.],
        [1., 0., 0.]])
['rep2⋈block1', 'rep2⋈block2', 'rep1⋈block1']

Methods

`__call__`([free_params])	Return the dummy matrix, on the dtype and device of the input.
`auto_grad`([free_params])	Compute the Jacobian of `build()` with respect to free parameters using automatic differentiation.
`build_params`([free_params, include_fixed, ...])	Construct the full parameter tensor from free parameters.
`disable_cache`()	Disable caching of intermediate computation results.
`enable_cache`()	Enable caching of intermediate computation results.
`get_default_dtype_device`()	Get the dtype and the device of the parameter defaults.
`get_intermediates`(params)	Retrieve cached intermediate computation results if still valid.
`grad`([free_params])	Compute the Jacobian of `__call__()` with respect to trainable parameters.
`inverse`([free_params])	Construct the matrix and return its inverse.
`manual_grad`([free_params])	Compute the Jacobian of `__call__()` with respect to free parameters using a closed-form analytic expression.
`reset_intermediates`()	Clear the intermediate computation cache.
`resolve_dim`(n)	Resolve a matrix dimension from an integer or a vector of levels.
`set_intermediates`(params, intermediates)	Cache intermediate computation results keyed by the parameter values.
`set_param_specs`(key, *[, fixed, default, trans])	Update the fields of one or more parameter specifications in place.
`trans_grad`([free_params])	Compute the element-wise derivative of the free parameter transforms.

Attributes

`colnames`	Column names of the matrix.
`fixed_param_defaults`	Fixed parameter defaults.
`fixed_param_index`	Index of fixed parameters.
`fixed_param_names`	Fixed parameter names.
`fixed_param_trans`	Transforms for fixed parameters.
`free_param_defaults`	Free parameter defaults.
`free_param_index`	Index of free parameters.
`free_param_names`	Free parameter names.
`free_param_trans`	Transforms for free parameters.
`num_fixed_params`	Total number of fixed parameters.
`num_free_params`	Total number of free parameters.
`num_params`	Total number of parameters.
`param_defaults`	Parameter defaults.
`param_names`	Parameter names.
`param_specs`	Parameter specifications, returned as stored rather than copied.
`param_trans`	Parameter transforms.
`repr_dict`	Key-value pairs used to build the string representation.
`shape`	Output matrix shape.
`grad_mode`	Gradient computation mode.
`jacobian_method`	Jacobian method used by `auto_grad()`, one of `"jacrev"`, `"jacfwd"`, or `"jacobian"`.
`jacobian_chunk_size`	Number of outputs held per batch when `auto_grad()` differentiates with `"jacrev"`, or `None` to compute the Jacobian in a single batch.
`cache`	Whether intermediate computation results are cached, toggled by `enable_cache()` and `disable_cache()`.

__call__(free_params=None)[source]¶

Return the dummy matrix, on the dtype and device of the input.

The dummy matrix has no parameters, so free_params carries no values: only its dtype and device are used. When it is omitted, the PyTorch default dtype and device are used.

Parameters:

free_params (torch.Tensor or dict, optional) – Empty 1D parameter tensor whose dtype and device are followed, or an empty parameter dict. If omitted, the PyTorch default dtype and device are used. Default: None.

Returns:

The fixed dummy matrix.

Return type:

torch.Tensor

Raises:

TypeError – If free_params is not a Torch tensor or a dict.
ValueError – If free_params is not empty, since the matrix has no parameters to receive.

Example:

import torch
from torch_openreml.covariance import DummyMatrix

rep = ["rep1", "rep2", "rep2"]
mat = DummyMatrix(rep)
mat()

tensor([[1., 0.],
        [0., 1.],
        [0., 1.]])

mat(torch.tensor([], dtype=torch.float64))

tensor([[1., 0.],
        [0., 1.],
        [0., 1.]], dtype=torch.float64)

property colnames¶

Column names of the matrix.

Type:: list

property repr_dict¶

Key-value pairs used to build the string representation.

Type:: dict