torch_openreml.covariance.DesignMatrix

class torch_openreml.covariance.DesignMatrix(x, levels=None, drop_first=False, dtype=None, device=None)

Bases: Matrix

Fixed design matrix constructed from numeric or categorical input.

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

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

Numeric input is passed to numeric_to_design_matrix() and categorical string input to categorical_to_design_matrix(). In both cases levels and drop_first control which columns are retained.

Initialize a fixed design matrix from numeric or categorical input.

Parameters:

• x (torch.Tensor, list, or tuple) – Input data. Either a numeric tensor or list, or a list of strings for categorical data.

• levels (list, optional) – Explicit level ordering for categorical input, or bin edges for numeric input.

• drop_first (bool, optional) – Whether to drop the first column. Defaults to False.

• dtype (torch.dtype, optional) – Desired dtype of the matrix.

• device (torch.device, optional) – Desired device of the matrix.

Raises:

TypeError – If x is not a torch.Tensor, list, or tuple.

Example:

import torch
from torch_openreml.covariance import DesignMatrix

mat = DesignMatrix(torch.tensor([1.0, 2.0, 3.0, 4.0]))
print(mat())

mat = DesignMatrix(["a", "b", "a", "c"])
print(mat())

mat = DesignMatrix(["a", "b", "a", "c"], levels=["c", "b", "a"])
print(mat())

tensor([[1.],
        [2.],
        [3.],
        [4.]])
tensor([[1., 0., 0.],
        [0., 1., 0.],
        [1., 0., 0.],
        [0., 0., 1.]])
tensor([[0., 0., 1.],
        [0., 1., 0.],
        [0., 0., 1.],
        [1., 0., 0.]])

Methods

__call__(*args, **kwargs)	Construct the matrix from a flat parameter tensor.
auto_grad(params)	Compute the Jacobian of build() with respect to trainable parameters using automatic differentiation.
check_params(params)	Validate a parameter tensor and return its device and dtype.
from_param_dict(param_dict)	Extract parameter tensors from a dictionary into a flat 1D tensor.
get_intermediates(params)	Retrieve cached intermediate computation results if still valid.
grad(params)	Compute the Jacobian of __call__() with respect to trainable parameters.
manual_grad(params)	Compute the Jacobian of __call__() with respect to trainable 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.
set_no_grad([index, param_name])	Set the indices of parameters to exclude from gradient computation.
to_param_dict(params)	Convert a flat parameter tensor to a parameter dictionary.
trans_grad(params)	Compute the element-wise derivative of the parameter transforms.
trans_params(params)	Apply parameter transforms to a flat parameter tensor.

Attributes

no_grad_index	Indices of parameters excluded from gradient computation.
num_params	Total number of parameters.
param_names	Ordered parameter names.
repr_dict	Key-value pairs used to build the string representation.
shape	Output matrix shape.
trans	Parameter transforms.

__call__(*args, **kwargs)

Construct the matrix from a flat parameter tensor.

Must be implemented by subclasses. Implementations should convert params via from_param_dict() or to_param_dict(), then call check_params() to validate and trans_params() to apply transforms before any computation.

Parameters:

params (torch.Tensor or dict) – Flat 1D parameter tensor or parameter dictionary.

Returns:

Constructed matrix of shape shape.

Return type:

torch.Tensor

property repr_dict

Key-value pairs used to build the string representation.

Type:

dict