torch_openreml.covariance.DummyMatrix¶

class torch_openreml.covariance.DummyMatrix(*args, levels=None, lex_order=True, drop_first=False, drop_empty_cols=False, dtype=None, device=None)[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, []).

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.
dtype (torch.dtype, optional) – Desired dtype of the matrix.
device (torch.device, optional) – Desired device of the matrix.

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__`(args, *kwargs)	Construct the matrix from a flat parameter tensor.
`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.
`get_intermediates`(params)	Retrieve cached intermediate computation results if still valid.
`grad`([free_params])	Compute the Jacobian of `__call__()` with respect to trainable parameters.
`manual_grad`([free_params])	Compute the Jacobian of `__call__()` with respect to free parameters using a closed-form analytic expression.
`map_theta_to_dv`(theta)	An interface compatible with `torch_openreml.REML` that maps parameters to the matrix Jacobian.
`map_theta_to_v`(theta)	An interface compatible with `torch_openreml.REML` that maps parameters to a matrix.
`reset_intermediates`()	Clear the intermediate computation cache.
`set_intermediates`(params, intermediates)	Cache intermediate computation results keyed by parameter hash.
`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.
`param_trans`	Parameter transforms.
`repr_dict`	Key-value pairs used to build the string representation.
`shape`	Output matrix shape.

__call__(*args, **kwargs)[source]¶

Construct the matrix from a flat parameter tensor.

Must be implemented by subclasses. Implementations should convert free_params via build_params() to validate, include fixed parameters, and apply transforms before any computation.

Parameters:: free_params (torch.Tensor or dict) – Flat 1D parameter tensor or parameter dictionary. If omitted, default values are used. Default: None.
Returns:: Constructed matrix of shape shape.
Return type:: torch.Tensor

property colnames¶

Column names of the matrix.

Type:: list

property repr_dict¶

Key-value pairs used to build the string representation.

Type:: dict