transition_matrix#

neurocaps.analysis.transition_matrix(trans_dict, output_dir=None, plot_output_format='png', suffix_filename=None, suffix_title=None, save_plots=True, save_df=True, show_figs=True, return_df=True, **kwargs)[source]#

Generate and Visualize the Averaged Transition Probabilities.

Averages subject-level transition probabilities to produce a transition probability matrix. One matrix is generated per group.

Parameters:

trans_dict – A dictionary mapping groups to pandas DataFrame containing the transition probabilities for each subject. This assumes the output from CAP.calculate_metrics is being used, specifically metrics_output["transition_probability"].
output_dir (str or None, default=None) – Directory to save plots (if save_plots is True) and transition probability matrices DataFrames (if save_df is True) to. The directory will be created if it does not exist. Plots and dataframes will not be saved if None.
plot_output_format (str, default=”png”) –
The format to save plots in when output_dir is specified. Options are “png” or “pkl” (which can be further modified). Note that “pickle” is also accepted.

Changed in version 0.33.0: Replaces as_pickle and accepts a string value.
suffix_filename (str or None, default=None) – Appended to the filename of each saved plot if output_dir is provided.
suffix_title (str or None, default=None) – Appended to the title of each plot.
save_plots (bool, default=True) – If True, plots are saves as png images. For this to be used, output_dir must be specified.
save_df (bool, default=False,) – If True, saves the transition probability matrix contained in the DataFrames as csv files. For this to be used, output_dir must be specified.
show_figs (bool, default=True) – Display figures.
return_df (bool, default=False) – If True, returns a dictionary with a transition probability matrix for each group.
**kwargs –
Keyword arguments used when modifying figures. Valid keywords include:
- dpi: int, default=300 – Dots per inch for the figure.
- figsize: tuple, default=(8, 6) – Size of the figure in inches.
- fontsize: int, default=14 – Font size for the plot title, x-axis title, and y-axis title of each plot.
- xticklabels_size: int, default=8 – Font size for x-axis tick labels.
- yticklabels_size: int, default=8 – Font size for y-axis tick labels.
- shrink: float, default=0.8 – Fraction by which to shrink the colorbar.
- cbarlabels_size: int, default=8 – Font size for the colorbar labels.
- xlabel_rotation: int, default=0 – Rotation angle for x-axis labels.
- ylabel_rotation: int, default=0 – Rotation angle for y-axis labels.
- annot: bool, default=False – Add values to each cell.
- annot_kws: dict, default=None, – Customize the annotations.
- fmt: str, default=”.2g” – Modify how the annotated vales are presented.
- linewidths: float, default=0 – Padding between each cell in the plot.
- borderwidths: float, default=0 – Width of the border around the plot.
- linecolor: str, default=”black” – Color of the line that separates each cell.
- edgecolors: str or None, default=None – Color of the edges.
- alpha: float or None, default=None – Controls transparency and ranges from 0 (transparent) to 1 (opaque).
- bbox_inches: str or None, default=”tight” – Alters size of the whitespace in the saved image.
- cmap: str, callable default=”coolwarm” – Color map for the plot cells. Options include strings to call seaborn’s pre-made palettes, seaborn.diverging_palette function to generate custom palettes, and matplotlib.color.LinearSegmentedColormap to generate custom palettes.
- vmin: float or None, default=None – The minimum value to display in colormap.
- vmax: float or None, default=None – The maximum value to display in colormap.

Returns:

dict[str, pd.DataFrame] – An instance of a pandas DataFrame for each group if return_df is True.

Note

Dataframe Representation: Rows represent “from” and columns represent “to”. For instance, the probability at df.loc["CAP-1", "CAP-2"] represents the averaged probability from transitioning from CAP-1 to CAP-2.

From/To	CAP-1	CAP-2	CAP-3
CAP-1	0.40	0.35	0.25
CAP-2	0.20	0.45	0.35
CAP-3	0.35	0.18	0.47