Plotting

class irtorch.Plotter(model: BaseIRTModel)

Bases: object

Class for producing various plots from an IRT model. A fitted model typically holds an instance of this class in its plot property. Thus the methods can be accessed through model.plot.method_name().

Parameters: model (BaseIRTModel) – The IRT model to use for plotting.

expected_sum_score(items: list[int] = None, latent_variables: tuple[int] = (1,), title: str = None, x_label: str = None, y_label: str = None, color: str = None, colorscale: str = 'Greens', theta_range: tuple[float, float] = None, second_theta_range: tuple[float, float] = None, steps: int = None, fixed_thetas: Tensor = None, rescale: bool = True) → Figure

Plots the expected sum score from the model against the latent variable(s). Supports full test scores, a single item or a subset of items.

Parameters

items (list[int], optional) – The items used to compte the sum score. If None, all items are used. (default is None)
latent_variables (tuple[int], optional) – The latent variables to plot. (default is (1,))
title (str, optional) – The title for the plot. (default is None)
x_label (str, optional) – The label for the X-axis. (default is None and uses “Latent variable” for one latent variable and “Latent variable 1” for two latent variables)
y_label (str, optional) – The label for the Y-axis. (default is None and uses “Expected sum score” or “Expected item score” for one latent variable, and “Latent variable 2” for two latent variables)
color (str, optional) – The color to use for plots with one latent variable. (default is None and uses the default color sequence for the plotly_white template)
colorscale (str, optional) – Sets the colorscale for the multiple latent variable surface plots. See https://plotly.com/python/builtin-colorscales/ (default is “Greens”)
theta_range (tuple[float, float], optional) – The theta range for plotting. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
second_theta_range (tuple[float, float], optional) – The range for plotting for the second latent variable. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
steps (int, optional) – The number of steps along each theta axis to construct the latent variable grid for which the sum score is evaluated at. (default is None and uses 100 for one latent variable and 18 for two latent variables)
fixed_thetas (torch.Tensor, optional) – Only for multdimensional models. Fixed values for latent space variable not plotted. (default is None and uses the medians in the training data)
rescale (bool, optional) – Whether to plot the transformed latent scores if a transformation scale exists. (default is True)

Returns

The plotly Figure object for the plot.

Return type

go.Figure

information(items: list[int] = None, latent_variables: tuple[int] = (1,), degrees: list[int] = None, title: str = None, x_label: str = None, y_label: str = None, color: str = None, colorscale: str = 'Greens', theta_range: tuple[float, float] = None, second_theta_range: tuple[float, float] = None, steps: int = None, fixed_thetas: Tensor = None, rescale: bool = True) → Figure

Plots the Fisher information function against the latent variable(s). Supports both item and test information.

Parameters

items (list[int], optional) – The items to plot. If None, the full test information is plotted. (default is None)
latent_variables (tuple[int], optional) – The latent variables to plot. (default is (1,))
degrees (list[int], optional) – A list of angles in degrees between 0 and 90. One degree for each latent variable. Only applicable when the model is multidimensional. Information will be computed in the direction of the angles. (default is None)
title (str, optional) – The title for the plot. (default is None)
x_label (str, optional) – The label for the X-axis. (default is None and uses “Latent variable” for one latent variable and “Latent variable 1” for two latent variables)
y_label (str, optional) – The label for the Y-axis. (default is None and uses “Information” for one latent variable and “Latent variable 2” for two latent variables)
color (str, optional) – The color to use for plots with one latent variable. (default is None and uses the default color sequence for the plotly_white template)
colorscale (str, optional) – Sets the colorscale for the multiple latent variable surface plots. See https://plotly.com/python/builtin-colorscales/ (default is “Greens”)
theta_range (tuple[float, float], optional) – The theta range for plotting. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
second_theta_range (tuple[float, float], optional) – The range for plotting for the second latent variable. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
steps (int, optional) – The number of steps along each theta axis to construct the latent variable grid for which information is evaluated at. (default is None and uses 100 for one latent variable and 18 for two latent variables)
fixed_thetas (torch.Tensor, optional) – Only for multdimensional models. Fixed values for latent space variable not plotted. (default is None and uses the medians in the training data)
rescale (bool, optional) – Whether to plot the transformed latent scores if a transformation scale exists. (default is True)

Returns

The Plotly Figure object for the plot.

Return type

go.Figure

item_entropy(item: int, latent_variables: tuple[int] = (1,), title: str = None, x_label: str = None, y_label: str = None, color: str = None, colorscale: str = 'Greens', theta_range: tuple[float, float] = None, second_theta_range: tuple[float, float] = None, steps: int = None, fixed_thetas: Tensor = None, rescale: bool = True) → Figure

Plot the entropy of an item against the latent variable(s).

Parameters

item (int) – The item for which to plot the entropy.
latent_variables (tuple[int], optional) – The latent variables to plot. (default is (1,))
title (str, optional) – The title for the plot. (default is None and prints “Item {item} entropy”)
x_label (str, optional) – The label for the X-axis. (default is None and uses “Latent variable” for one latent variable and “Latent variable 1” for two latent variables)
y_label (str, optional) – The label for the Y-axis. (default is None and uses ‘Entropy’ for one latent variable, and “Latent variable 2” for two latent variables)
color (str, optional) – The color to use for plots with one latent variable. (default is None and uses the default color sequence for the plotly_white template)
colorscale (str, optional) – Sets the colorscale for the multiple latent variable surface plots. See https://plotly.com/python/builtin-colorscales/ (default is “Greens”)
theta_range (tuple[float, float], optional) – The theta range for plotting. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
second_theta_range (tuple[float, float], optional) – The range for plotting for the second latent variable. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
steps (int, optional) – The number of steps along each theta axis to construct the latent variable grid for which the sum score is evaluated at. (default is None and uses 100 for one latent variable and 18 for two latent variables)
fixed_thetas (torch.Tensor, optional) – Only for multdimensional models. Fixed values for latent space variable not plotted. (default is None and uses the medians in the training data)
rescale (bool, optional) – Whether to plot the transformed latent scores if a transformation scale exists. (default is True)

Returns

The Plotly Figure object for the plot.

Return type

go.Figure

item_latent_variable_relationships(relationships: Tensor = None, theta: Tensor = None, title: str = 'Relationships: Items vs. latent variables', x_label: str = 'Latent variable', y_label: str = 'Items', colorscale: str = 'Greens') → Figure

Create a heatmap of item-latent variable relationships. Uses irtorch.models.BaseIRTModel.expected_item_score_gradients() to compute the relationships if not provided.

Parameters

relationships (torch.Tensor) – A tensor of item-latent variable relationships. Each row represents an item and each column represents a latent variable. If not provided, the relationships are computed using irtorch.models.BaseIRTModel.expected_item_score_gradients().
theta (torch.Tensor, optional) – The theta scores to use for computing the relationships. Need to be on the original theta scale. If not provided, the training theta scores are used. (default is None)
title (str, optional) – The title for the plot. (default is “Relationships: Items vs. latent variables”)
x_label (str, optional) – The label for the X-axis. (default is “Latent variable”)
y_label (str, optional) – The label for the Y-axis. (default is “Items”)
colorscale (str, optional) – Sets the colorscale figure. See https://plotly.com/python/builtin-colorscales/ (default is “Greens”)

Returns

The Plotly Figure object for the plot.

Return type

go.Figure

item_probabilities(item: int, latent_variables: tuple = (1,), title: str = None, x_label: str = None, y_label: str = None, theta_range: tuple[float, float] = None, second_theta_range: tuple[float, float] = None, steps: int = None, fixed_thetas: Tensor = None, plot_group_fit: bool = False, group_fit_groups: int = 10, group_fit_data: int = None, group_fit_population_theta: Tensor = None, theta_estimation: str = 'ML', grayscale: bool = False, plot_derivative: bool = False, rescale: bool = True) → Figure

Plots the item probability curves for a given item. Supports 2D and 3D plots.

Parameters

item (int) – The item to plot (starts from 1).
latent_variables (tuple, optional) – The latent variables to plot. (default is (1,))
title (str, optional) – The title for the plot. (default is None and uses “IRF - Item {item}”)
x_label (str, optional) – The label for the X-axis. (default is None and uses “Latent variable” for one latent variable and “Latent variable 1” for two latent variables)
y_label (str, optional) – The label for the Y-axis. (default is None and uses “Probability”)
theta_range (tuple, optional) – The theta range for plotting. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
second_theta_range (tuple, optional) – The range for plotting for the second latent variable. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
steps (int, optional) – The number of steps along each theta axis used for probability evaluation. (default is None and uses 200 for one latent variable and 25 for two latent variables)
fixed_thetas (torch.Tensor, optional) – Only for multdimensional models. Fixed values for latent space variable not plotted. (default is None and uses the medians in the training data)
plot_group_fit (bool, optional) – Plot group average probabilities to assess fit. (default is False)
group_fit_groups (int, optional) – Only for plot_group_fit = True. The number of groups. (default is 10)
group_fit_data (torch.tensor, optional) – Only for plot_group_fit = True. The data used for group fit plots. Uses training data if not provided. (default is None)
group_fit_population_theta (torch.tensor, optional) – Only for plot_group_fit = True. The theta scores corresponding to group_fit_data. Will be estimated using group_theta_estimation if not provided. (default is None)
theta_estimation (str, optional) – Only for plot_group_fit = True. The estimation method for theta. Can be ‘NN’, ‘ML’, ‘EAP’ or ‘MAP’ for neural network, maximum likelihood, expected a posteriori or maximum a posteriori respectively. (default is ‘ML’)
grayscale (bool, optional) – Plot the item probability curves in grey scale. (default is False)
plot_derivative (bool, optional) – Plot the first derivative of the item probability curves. Only for plots with one latent variable. (default is False)
rescale (bool, optional) – Whether to plot the transformed latent scores if a transformation scale exists. (default is True)

Returns

The Plotly Figure object for the plot.

Return type

go.Figure

latent_score_distribution(scores_to_plot: Tensor = None, population_data: Tensor = None, latent_variables: tuple[int] = (1,), title: str = None, x_label: str = None, y_label: str = None, color: str = None, contour_colorscale: str = 'Greens', contour_plot_bins: int = None, rescale: bool = True, **kwargs) → Figure

Plots the distribution of latent scores.

Parameters

scores_to_plot (torch.Tensor, optional) – If provided, the requested latent variable distributions are plotted directly. If None, scores are computed from the population data or the model training data. (default is None)
population_data (torch.Tensor, optional) – The data used to compute the latent scores. If None, uses the training data. (default is None)
latent_variables (tuple[int], optional) – The latent dimensions to include in the plot. (default is (1,))
title (str, optional) – The title for the plot. (default is None)
x_label (str, optional) – The label for the X-axis. (default is None and uses “Latent variable” for one latent variable and “Latent variable 1” for two latent variables)
y_label (str, optional) – The label for the Y-axis. (default is None and uses “Density” for one latent variable and “Latent variable 2” for two latent variables)
color (str, optional) – The color to use for plots with one latent variable. (default is None and uses the default color sequence for the plotly_white template)
contour_colorscale (str, optional) – Sets the colorscale for the multiple latent variable contour plots. See https://plotly.com/python/builtin-colorscales/ (default is “Greens”)
contour_plot_bins (int, optional) – The number of histogram bins to use for creating the contour plot. (default is None and uses Sturges’ Rule)
rescale (bool, optional) – Whether to plot the transformed latent scores if a transformation scale exists. (default is True)
**kwargs (dict, optional) – Additional keyword arguments to be passed to irtorch.models.BaseIRTModel.latent_scores() if scores_to_plot is not provided.

Returns

The Plotly Figure object for the plot.

Return type

go.Figure

log_likelihood(data: Tensor, latent_variables: tuple[int] = (1,), items: list[int] = None, expected_sum_score: bool = False, title: str = None, x_label: str = None, y_label: str = None, color: str = None, colorscale: str = 'Greens', theta_range: tuple[float, float] = None, second_theta_range: tuple[float, float] = None, steps: int = None, fixed_thetas: Tensor = None, rescale: bool = True) → Figure

Plots the log-likelihood function against the latent variable(s) for the supplied response pattern.

Parameters

data (torch.Tensor) – The response data. Needs to be a one row tensor with the same number of columns as the model has items.
latent_variables (tuple[int], optional) – The latent variables to plot. (default is (1,))
items (list[int], optional) – The items to consider for computing the log-likelihood. If None, all items in the model are used. (default is None)
expected_sum_score (bool, optional) – Whether to plot the log-likelihood against the expected sum score instead of the latent variable(s). (default is False)
title (str, optional) – The title for the plot. (default is None)
x_label (str, optional) – The label for the X-axis. (default is None and uses “Latent variable” for one latent variable and “Latent variable 1” for two latent variables)
y_label (str, optional) – The label for the Y-axis. (default is None and uses “Information” for one latent variable and “Latent variable 2” for two latent variables)
color (str, optional) – The color to use for plots with one latent variable. (default is None and uses the default color sequence for the plotly_white template)
colorscale (str, optional) – Sets the colorscale for the multiple latent variable surface plots. See https://plotly.com/python/builtin-colorscales/ (default is “Greens”)
theta_range (tuple[float, float], optional) – The theta range for plotting. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
second_theta_range (tuple[float, float], optional) – The range for plotting for the second latent variable. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
steps (int, optional) – The number of steps along each theta axis to construct the latent variable grid for which information is evaluated at. (default is None and uses 100 for one latent variable and 18 for two latent variables)
fixed_thetas (torch.Tensor, optional) – Only for multdimensional models. Fixed values for latent space variable not plotted. (default is None and uses the medians in the training data)
rescale (bool, optional) – Whether to plot the transformed latent scores if a transformation scale exists. (default is True)

Returns

The Plotly Figure object for the plot.

Return type

go.Figure

scale_transformations(input_latent_variable: int = 1, title: str = None, x_label: str = None, y_label: str = None, color: str = None, colorscale: str = 'Greens', input_theta_range: tuple[float, float] = None, steps: int = None, fixed_thetas: Tensor = None) → Figure

Plots the scale transformations for the latent variable(s).

Parameters

input_latent_variable (int, optional) – The latent variable to visualize (the input dimension). For multidimensional models, other latent variables are fixed (see fixed_thetas below). (default is 1)
title (str, optional) – The title for the plot. (default is None and uses “Scale Transformation(s)”)
x_label (str, optional) – The label for the X-axis. (default is None and uses “Original scale”)
y_label (str, optional) – The label for the Y-axis. (default is None and uses “Transformed scale”)
color (str, optional) – The color to use for plots with one latent variable. (default is None and uses the default color sequence for the plotly_white template)
colorscale (str, optional) – Sets the colorscale for the multiple latent variable surface plots. See https://plotly.com/python/builtin-colorscales/ (default is “Greens”)
input_theta_range (tuple[float, float], optional) – The theta range for plotting. For invertible scale transformations, this is the range of the transformed theta scores. Otherwise it is the range of the original theta scores. (default is None and uses limits based on training data)
steps (int, optional) – The number of steps along each theta axis to construct the latent variable grid for which information is evaluated at. (default is None and uses 100 for one latent variable and 18 for two latent variables)
fixed_thetas (torch.Tensor, optional) – Only for multdimensional models. Fixed values for latent space variable not plotted. (default is None and uses the medians in the training data)

Returns

The Plotly Figure object for the plot.

Return type

go.Figure

training_history() → Figure

Plots the training history of the model.

Returns: The Plotly Figure object for the plot.
Return type: go.Figure