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 – Additional keyword arguments for customizing plots. See neurocaps.utils.PlotDefaults.transition_matrix() for all available options and their default values (See PlotDefaults Documentation for transition_matrix)

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
On this page