Torch modules

irtorch.torch_modules contains various PyTorch modules. These modules are used in different contexts of the package, but can also be used separately.

class irtorch.torch_modules.MonotonePolynomialModule(degree: int, in_features: int = 1, out_features: int = 1, intercept: int = False, relationship_matrix: Tensor = None, negative_relationships: bool = False, shared_directions: int = 1)

Bases: Module

A polynomial with monotonicity constraints.

Parameters

  • degree (int) – Degree of the polynomial. Needs to be an uneven number.

  • in_features (int) – Number of input features.

  • out_features (int) – Number of output features.

  • intercept (bool) – Whether to include an intercept term. (Default: False)

  • relationship_matrix (torch.Tensor, optional) – A boolean tensor of shape (in_features, out_features,) that determines which inputs are related to which outputs. Typically used for IRT models to remove relationships between some items or item categories and latent variables. (Default: None)

  • negative_relationships (bool, optional) – Whether to allow for negative relationships. (Default: False)

  • shared_directions (int, optional) – Only when negative_relationships is true. Number of out_features with shared relationship directions. out_features needs to be divisible with this. (Default: 1)

forward(x: Tensor) → Tensor

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_polynomial_coefficients() → Tensor

Returns the polynomial coefficients.

Returns

Tuple of tensors containing the coefficients of the polynomial with dimensions (degree, input_dim, output_dim), the second tensor contains the intercept if it exists and None otherwise.

Return type

tuple[torch.Tensor, torch.Tensor]

class irtorch.torch_modules.NeuralSplineFlow(transformation: RationalQuadraticSpline, distribution: Distribution)

Bases: Module

Normalizing flow using rational-quadratic splines [7].

Parameters

  • transform (RationalQuadraticSpline) – Transforms values from the observed data to the chosen distribution.

  • distribution (Distribution) – The base distribution of the flow that generates the observed data.

forward(inputs) → Tensor

Transforms from observed data into the chosen distribution (noise).

Parameters

inputs (torch.Tensor) – A tensor of shape [batch_size, …], the data to be transformed.

Returns

A tensor of shape [batch_size, …].

Return type

torch.Tensor

inverse(inputs) → Tensor

Transforms from the chosen distribution (noise) into observed data.

Parameters

inputs (torch.Tensor) – A tensor of shape [batch_size, …], the data to be transformed.

Returns

A tensor of shape [batch_size, …].

Return type

torch.Tensor

log_prob(value) → Tensor

The log-likelihood of the observed data in the chosen distribution after transformation. Usually the negative loss when training.

Parameters

value (torch.Tensor) – A tensor of shape [batch_size, …], the data to be transformed.

Returns

A tensor of shape [batch_size, …].

Return type

torch.Tensor

class irtorch.torch_modules.RationalQuadraticSpline(variables: int, num_bins=30, lower_input_bound=0.0, upper_input_bound=1.0, lower_output_bound=0.0, upper_output_bound=1.0, min_bin_width=0.001, min_bin_height=0.001, min_derivative=0.001, free_endpoints=False)

Bases: Module

This module implements a rational quadratic spline, as described in the paper β€œNeural Spline Flows” by Durkan et al. [7].

Parameters

  • variables (int) – The number of variables (dimensions) to transform.

  • num_bins (int, optional) – The number of bins to use for the spline (default is 30).

  • lower_input_bound (float, optional) – The left boundary of the transformation interval (default is 0.0).

  • upper_input_bound (float, optional) – The right boundary of the transformation interval (default is 1.0).

  • lower_output_bound (float, optional) – The bottom boundary of the transformation interval (default is 0.0).

  • upper_output_bound (float, optional) – The top boundary of the transformation interval (default is 1.0).

  • min_bin_width (float, optional) – The minimum width of each bin (default is 1e-3).

  • min_bin_height (float, optional) – The minimum height of each bin (default is 1e-3).

  • min_derivative (float, optional) – The minimum derivative value at the knots (default is 1e-3).

  • free_endpoints (bool, optional) – When free_endpoints=True, the lower and upper output bounds become trainable parameters (default is False).

forward(inputs, inverse=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.