Analysis steps

Usage

code.analysis.run_analysis()

RUN_ANALYSIS runs an analysis step on an item and saves the results to the output resdir

Parameters:

res (2D matrix) – the Mapper output result as struct for the item
analysis (struct) – the config definition of a specific analysis. Minimally, it needs a field type as string. It might also have other arguments that are needed for the analysis.
item (table item) – individual item details that are further needed for specifc analysis.
resdir (string) – the path of where to save the analysis results.

Possible analysis structs types:

plot_graph: plots the mapper shape graph and saved the plot at the path: ‘../plot_graph.png’.
compute_stats: compute the basis graph statistics (coverage, distances, assortativity, core_periphery) which are saved at the path ‘stats.json’. It also produces detailed results (1D files) for the basic graph measures (betweenness_centrality, core_periphery). If the HRF_threshold value is provided as an argument within the analysis struct, then the item needs a TR value, and the HRF_DURATION_STAT will be computed. The TR value is expected as either another argument or as a column part of the item.
compute_temp: creates the temporal connectivity matrices (TCM and TCM_inverted) which are saved as plots and as matrices (as 1D files). If skip_mat is set, it will avoid saving the matrix.
plot_task: plots the mapper shape graph with each node labelled based on a task file. This analysis requires extra arguments. First, “name” is required and can be any string. Second, a path to a CSV file is needed. The path can be set as an argument in the analysis as “task_path” argument, or alternatively, as a table column part of the item analyzed, with the column name as: “task_path_<name>”, where <name> represents the name defined as an argument.

Below, we have a few examples of analysis objects (in JSON format) with an associated item:

Analysis Examples

Example 1: Plot simple shape graph figure

Analysis:
{ "type": "plot_graph" }
Explanation:
Running this analysis will create the file: `plot_graph.png`

Example 2: Compute basic stats

Analysis:
{ "type": "compute_stats" }
Explanation:
Running this analysis will multiple files with the prefix stats:
`stats.json`: is a json file with basic stats of the mapper shape graph
`stats_degrees_TRs.1D: is a 1D file with each line representing the node
                       degree of each TR in the shape graph
`stats_core_periphery.1D`: is a 1D file representing the core-periphery
                           value for each node of the mapper shape graph
`stats_core_periphery_TRs_avg.1D`: is a 1D file representing the
                                   core-periphery value for each TRs
                                   computed as an average from each node
`stats_betweenness_centrality.1D`: the betweenness centrality of each node
                                   of the mapper shape graph
`stats_*`: other stats computed

Example 3: Compute basic stats with HRF measure

Analysis:
{ "type": "compute_stats", "args": { "HRF_threshold": 11 } }
Example cohort table (CSV file):
id0,id1,id2,path,TR
SBJ01,REST_LR_1,gordon333,/path/to/SBJ01/REST_LR_1/gordon333.npy,0.72
SBJ02,REST_LR_1,gordon333,/path/to/SBJ02/REST_LR_1/gordon333.npy,0.72
Explanation:
Running this analysis will produce similar results as the previous
`compute_stats` example, with the additional stats related to HRF stats:
Now, `stats.json` will include a `hrfdur_stat` statistic of the percentage
of nodes of the shape graph that have TRs with a time difference higher
than the `HRF_threshold` in seconds. For this, the RepetitionTime of each
scan is needed, and provided as part of the cohort file. In our example, we
will have nodes that have TRs separated by 11s, or 11s / 0.72 (TR) = 15
steps.

Example 4: Compute temporal connectivity/similarity matrices (TCM)

Analysis:
{ "type": "compute_temp", "args": { "skip_mat": true } }
Explanation:
Running this analysis will produce 2 files representing the similarity
matrix and its inverse, in PNG format only. Changing the "skip_mat" value
to false, will print two 1D files with the TCM matrix and it's inverse.

Example 5: Plot task

Analysis:
{ "type": "plot_task", "args": { "name": "CME", "path": "/path/to/timing.csv" } }
Explanation:
Running this analysis will create the file: `plot_task-CME.png` that will
color each node as a pie chart with the distribution of each label of TRs.
The label of each TR is extracted from the column `task_name` from the CSV
linked.
Important Requirement: the CSV containing the task_name column, should have
the same number of rows as number of TRs in all inputs from the cohort
file. If you have a varying number of rows (nr of TRs) for different
inputs, then you have to set a separate task file for each of those item in
the cohort file. Check the example below for such a setup.

Example 6: Plot task with varying number of TRs

Analysis:
{ "type": "plot_task", "args": { "name": "CME" }
Example cohort table (CSV file):
id0,id1,id2,path,TR,task_path_CME
SBJ01,REST,gordon333,/path/to/bold1.npy,0.72,/path/to/task_labels_for_item1.csv
SBJ02,REST,gordon333,/path/to/bold2.npy,0.72,/path/to/task_labels_for_item2.csv
Explanation:
Running this analysis is similar to the `plot_task` example above but each
individual item from the cohort file has it's own separate task labels.
This is a useful setting in case your bold files have a varying number of
TRs per scan.

Example 7: Plot task on task labels with a temporal filtering mask

Analysis:
{ "type": "plot_task", "args": { "name": "CME" }
Example cohort table (CSV file):
id0,id1,id2,path,TR,task_path_CME,tmask
SBJ01,REST,g333,/path/to/bold1.npy,0.72,/path/to/lbls_item1.csv,/path/to/confound2/scrubbed_item1.1D
SBJ02,REST,g333,/path/to/bold2.npy,0.72,/path/to/lbls_item2.csv,/path/to/confound2/scrubbed_item2.1D
Explanation:
Running this analysis is similar to the `plot_task` example above but in
this case the CSV is filtered by the tmask. This setup is useful when
running after a task that removes certain TRs of the scan. In that case,
the labels need to be filtered as well.

Analysis Types

code.analysis.plot_graph()

PLOT_GRAPH Plot the Mapper Graph

Inputs: :param res: the results from running Mapper :type res: Mapper struct

Parameters:: save_path (string) – where to save the resulting graph

code.analysis.plot_task()

PLOT_TASK Plot the Mapper Graph based on task data

Parameters:

res (Mapper struct) – the results from running Mapper
timing_table (table) – describes the task performed as classifying each TR as a value described in ‘task_name’. Optionally, one can add ‘task’ field as the ID of the task. The table must have the same amount of rows as there are TRs in the Mapper result.
save_path (string) – where to save the resulting graph plot
no_legend (bool) – if set to True, it will not print the legend
cmap ((3xN) 2D Matrix) – if set, it is a matrix that has the same number of rows as tasks in timing_table. Expected 3 columns for RGB for each task.

code.analysis.compute_stats()

STATS get stats from the Mapper Graph

Parameters:

res (Mapper struct) – the results from running Mapper
args (struct) – extra details to help create the stats
resdir (string) – where to save the resulting plots and matrices

code.analysis.compute_temp()

COMPUTE_TEMP Compute and plot the Temporal matrices

Parameters:

res (Mapper struct) – the results from running Mapper
resdir (string) – where to save the resulting plots and matrices
skip_mat (bool) – if true, it doesn’t print out the TCM matrices (default: false)