neurocaps.analysis.transition_matrix

class transition_matrix(trans_dict, output_dir=None, suffix_title=None, suffix_filename=None, show_figs=True, save_plots=True, return_df=True, save_df=True, **kwargs)

Generate and Visualize the Averaged Transition Probabilities.

Uses the "transition_probability" output from CAP.calculate_metrics to generate and visualize the averaged transition probability matrix for all groups from the analysis.

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 (os.PathLike 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.

• suffix_title (str or None, default=None) -- Appended to the title of each plot.

• suffix_filename (str or None, default=None) -- Appended to the filename of each saved plot if output_dir is provided.

• show_figs (bool, default=True) -- Display figures.

• save_plots (bool, default=True) -- If True, plots are saves as png images. For this to be used, output_dir must be specified.

• return_df (bool, default=False) -- If True, returns a dictionary with a transition probability matrix for each group.

• 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.

• **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.

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

The "From/To" index name appears in versions >=0.17.11.