pcntoolkit.util.plotter#

A module for plotting functions.

Functions#

`plot_centiles`(→ list[matplotlib.figure.Figure])	Plot the centiles of the model.
`plot_centiles_advanced`(→ list[matplotlib.figure.Figure])	Generate centile plots for response variables with optional data overlay.
`plot_qq`(→ list[matplotlib.figure.Figure])	Plot QQ plots for each response variable in the data.
`plot_ridge`(→ list[matplotlib.figure.Figure])	Plot a ridge plot for each response variable in the data.

Module Contents#

plot_centiles(model: pcntoolkit.normative_model.NormativeModel, scatter_data: pcntoolkit.dataio.norm_data.NormData | None = None, centiles: list[float] = [0.05, 0.25, 0.5, 0.75, 0.95], covariate: str | None = None, response_vars: list[str] | None = None, scatter_kwargs: dict = {}, show_figure: bool = True, save_dir: str | None = None) → list[matplotlib.figure.Figure]#

Plot the centiles of the model.

Parameters:

model (NormativeModel) – The model to plot the centiles for.
scatter_data (NormData) – The data to scatter on top of the centiles.
centiles (List[float], optional) – The centiles to plot.
covariate (str, optional) – The covariate to plot on the x-axis.
response_vars (List[str] | None) – The response vars for which to make the plots. All are plotted if this is None, which is default.
scatter_kwargs (dict, optional) –
Keyword arguments for the scatter plot. May include: - color: The color of the scatter points. Hex code or matplotlib color name. - alpha: The transparency of the scatter points. Between 0 and 1. - s: The size of the scatter points. - marker: The marker of the scatter points. Uses matplotlib marker syntax: https://matplotlib.org/stable/api/markers_api.html - edgecolor: The edge color of the scatter points. Hex code or

matplotlib color name.
- linewidth: The width of the edge of the scatter points. 0 for no edge.
show_figure (bool, optional) – If True, call plt.show() after all figures are created. Defaults to True.
save_dir (str | None, optional) – Directory to save the figures. Defaults to None.

Returns:

One matplotlib Figure per response variable.

Return type:

list[Figure]

plot_centiles_advanced(model: pcntoolkit.normative_model.NormativeModel, centiles: list[float] | numpy.ndarray | None = None, conditionals: list[float] | numpy.ndarray | None = None, covariate: str | None = None, covariate_ranges: dict[str, tuple[float, float]] | None = None, response_vars: list[str] | None = None, batch_effects: dict[str, list[str]] | None | Literal['all'] = None, scatter_data: pcntoolkit.dataio.norm_data.NormData | None = None, harmonize_data: bool = True, hue_data: str = 'site', markers_data: str = 'sex', show_other_data: bool = False, show_thrivelines: bool = False, z_thrive: float = 0.0, show_figure: bool = True, save_dir: str | None = None, show_centile_labels: bool = True, show_legend: bool = True, show_yhat: bool = False, plt_kwargs: dict | None = None, **kwargs: Any) → list[matplotlib.figure.Figure]#

Generate centile plots for response variables with optional data overlay.

This function creates visualization of centile curves for all response variables in the dataset. It can optionally show the actual data points overlaid on the centile curves, with customizable styling based on categorical variables.

Parameters:

model (NormativeModel) – The model to plot the centiles for.
centiles (List[float] | np.ndarray | None, optional) – The centiles to plot. If None, the default centiles will be used.
conditionals (List[float] | np.ndarray | None, optional) – A list of x-coordinates for which to plot the conditionals
covariate (str | None, optional) – The covariate to plot on the x-axis. If None, the first covariate in the model will be used.
covariate_ranges (tuple[float, float], optional) – The range of the covariate to plot on the x-axis. If None, the range of the covariate that was in the train data will be used.
response_vars (List[str] | None) – The response vars for which to make the plots. All are plotted if this is None, which is default.
batch_effects (Dict[str, List[str]] | None | Literal[``”all”``], optional) – The batch effects to plot the centiles for. If None, the batch effect that appears first in alphabetical order will be used.
scatter_data (NormData | None, optional) – Data to scatter on top of the centiles.
harmonize_data (bool, optional) – Whether to harmonize the scatter data before plotting. Data will be harmonized to the batch effect for which the centiles were computed.
hue_data (str, optional) – The column to use for color coding the data. If None, the data will not be color coded.
markers_data (str, optional) – The column to use for marker styling the data. If None, the data will not be marker styled.
show_other_data (bool, optional) – Whether to scatter data belonging to groups not in batch_effects.
show_figure (bool, optional) – If True, call plt.show() after all figures are created. Defaults to True.
save_dir (str | None, optional) – The directory to save the plot to. If None, the plot will not be saved.
show_centile_labels (bool, optional) – Whether to show the centile labels on the plot.
show_legend (bool, optional) – Whether to show the legend on the plot.
plt_kwargs (dict, optional) – Additional keyword arguments passed to plt.subplots().
**kwargs (Any, optional) – Additional keyword arguments for the model.compute_centiles method.

Returns:

One matplotlib Figure per response variable.

Return type:

list[Figure]

plot_qq(data: pcntoolkit.dataio.norm_data.NormData, plt_kwargs: dict | None = None, bound: int | float = 0, plot_id_line: bool = False, hue_data: str | None = None, markers_data: str | None = None, split_data: str | None = None, response_vars: list[str] | None = None, seed: int = 42, show_figure: bool = True, save_dir: str | None = None) → list[matplotlib.figure.Figure]#

Plot QQ plots for each response variable in the data.

Parameters:

data (NormData) – Data containing the response variables.
plt_kwargs (dict or None, optional) – Additional keyword arguments for the plot. Defaults to None.
bound (int or float, optional) – Axis limits for the plot. Defaults to 0.
plot_id_line (bool, optional) – Whether to plot the identity line. Defaults to False.
hue_data (str or None, optional) – Column to use for coloring. Defaults to None.
markers_data (str or None, optional) – Column to use for marker styling. Defaults to None.
split_data (str or None, optional) – Column to use for splitting data. Defaults to None.
response_vars (List[str] | None = None,) – The response vars for which to make the plots. All are plotted if this is None, which is default.
seed (int, optional) – Random seed for reproducibility. Defaults to 42.
show_figure (bool, optional) – If True, call plt.show() after all figures are created. Defaults to True.

Returns:

One matplotlib Figure per response variable.

Return type:

list[Figure]

Examples

>>> plot_qq(data, plt_kwargs={"figsize": (10, 6)}, bound=3)

plot_ridge(data: pcntoolkit.dataio.norm_data.NormData, variable: Literal['Z', 'Y'], split_by: str, response_vars: list[str] | None = None, show_figure: bool = True, save_dir: str | None = None, **kwargs: Any) → list[matplotlib.figure.Figure]#

Plot a ridge plot for each response variable in the data.

Creates a density plot for the variable split by the split_by variable.

Each density plot will be on a different row.

The hue of the density plot will be the split_by variable.

Parameters:

data (NormData) – Data containing the response variable.
variable (Literal[``”Z”, ``"Y"]) – The variable to plot on the x-axis. (Z or Y)
split_by (str) – The variable to split the data by.
response_vars (list[str] or None, optional) – The response vars for which to make the plots. All are plotted if this is None, which is default.
show_figure (bool, optional) – If True, call plt.show() after all figures are created. Defaults to True.
save_dir (str or None, optional) – The directory to save the plot to. Defaults to None.
**kwargs (Any, optional) – Additional keyword arguments for the plot.

Returns:

One matplotlib Figure per response variable.

Return type:

list[Figure]