CLI Reference

The fSTG Toolkit CLI is invoked as a Python module:

python -m fstg_toolkit [OPTIONS] COMMAND [ARGS]...

The CLI is organised into four command groups: graph, plot, dashboard, and simulate (a subgroup of graph). The plot and dashboard groups require the [plot] and [dashboard] extras respectively. The graph frequent command requires the [frequent] extra.

Main CLI

python -m fstg_toolkit

Build, plot and simulate spatio-temporal graphs for fMRI data.

Usage

python -m fstg_toolkit [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

-l, --log-level <log_level>

Set the logging level.

Options:

debug | info | error

-v, --verbose

Show logs into the console.

graph

python -m fstg_toolkit graph

Build, calculate metrics and simulate graphs.

Usage

python -m fstg_toolkit graph [OPTIONS] COMMAND [ARGS]...

build

Build spatio-temporal graphs from sequences of correlation matrices.

The spatio-temporal graphs will be saved to OUTPUT, built from the correlation matrices in CORRELATION_MATRICES_PATH and the area descriptions in AREAS_DESCRIPTION_PATH.

Accepted file formats for correlation matrices are numpy pickle files with extensions .npz or .npy.

The CSV file for the description of areas and regions should have the columns: Id_Area, Name_Area, and Name_Region.

Usage

python -m fstg_toolkit graph build [OPTIONS] AREAS_DESCRIPTION_PATH
                                   [CORRELATION_MATRICES_PATH]...

Options

-o, --output <output>

Path where to write the built graph. If there is no ‘.zip’ extension, it will be added.

Default:

"a graph archive named 'output.zip' in the current directory"

-t, --corr-threshold <corr_threshold>

The threshold of the correlations maps.

Default:

0.4

--absolute-thresholding, --no-absolute-thresholding

Flag to tell how to threshold the correlations (on absolute values or not).

-acn, --areas-column-name <areas_column_name>

The name of the column of areas’ names in the description file.

Default:

'Name_Area'

-rcn, --regions-column-name <regions_column_name>

The name of the column of regions’ names in the description file.

Default:

'Name_Region'

--select

Select the graphs to build and save using an input prompt (only if there are multiple sets of correlation matrices).

--no-raw

Do not save the raw data along with the graphs.

--max-cpus <max_cpus>

Set the number of CPUs to use for the processing.

Arguments

AREAS_DESCRIPTION_PATH

Required argument

CORRELATION_MATRICES_PATH

Optional argument(s)

frequent

Perform a frequent patterns analysis.

It relies on the SPMiner package. Frequent patterns will be written into the given dataset.

Note that loading the SPMiner docker service for the first time can take a while, as its docker image is built at the first use. Later call will be much faster.

DATASET_PATH is the path to spatio-temporal graphs built with the command ‘build’.

Usage

python -m fstg_toolkit graph frequent [OPTIONS] DATASET_PATH

Arguments

DATASET_PATH

Required argument

metrics

Calculate metrics on spatio-temporal graphs.

DATASET_PATH is the path to spatio-temporal graphs built with the command ‘build’.

Usage

python -m fstg_toolkit graph metrics [OPTIONS] DATASET_PATH

Options

--max-cpus <max_cpus>

Set the number of CPUs to use for the processing.

Arguments

DATASET_PATH

Required argument

simulate

Simulate a spatio-temporal graph.

Usage

python -m fstg_toolkit graph simulate [OPTIONS] COMMAND [ARGS]...

Options

-o, --output_path <output_path>

Path where to write the simulated output.

Default:

"a file named 'output' in the current directory"

correlations

Simulate correlations matrices from a spatio-temporal graph.

Usage

python -m fstg_toolkit graph simulate correlations [OPTIONS] GRAPH_PATH

Options

-t, --threshold <threshold>

The correlation threshold when building graph from matrices.

Default:

0.4

Arguments

GRAPH_PATH

Required argument

pattern

Generate a spatio-temporal graph pattern from a description.

The input strings for networks, spatial edges, and temporal edges must follow specific formats.

NETWORKS:

The syntax for a single network is area_range,region,internal_strength, where area_range is either a single area ID or a range between IDs separated by a colon. Multiple networks at a given time are concatenated with spaces. Networks of different time instants are separated by a / symbol. The entire description must be surrounded by quotes.

SPATIAL_EDGES:

The syntax for a single spatial edge is network1_id,network2_id,correlation. Multiple descriptions are concatenated between quotes and separated by spaces.

TEMPORAL_EDGES:

The syntax for a single temporal edge is network_id_range,network_id_range, where network_id_range can be either a single network ID or multiple IDs separated by a - character. The type of edge is automatically inferred. Multiple descriptions are concatenated between quotes and separated by spaces.

Usage

python -m fstg_toolkit graph simulate pattern [OPTIONS] NETWORKS
                                              [SPATIAL_EDGES] [TEMPORAL_EDGES]

Arguments

NETWORKS

Required argument

SPATIAL_EDGES

Optional argument

TEMPORAL_EDGES

Optional argument

sequence

Generate a spatio-temporal graph from a sequence of patterns.

PATTERNS are the paths to the pattern files used to generate the graph.

SEQUENCE_DESCRIPTION is a space-separated list of elements, where each element is either a pattern (p<n>, where n is the order of the pattern) or a number (d) indicating d steady states.

Usage

python -m fstg_toolkit graph simulate sequence [OPTIONS] [PATTERNS]...
                                               SEQUENCE_DESCRIPTION

Arguments

PATTERNS

Optional argument(s)

SEQUENCE_DESCRIPTION

Required argument

plot

Requires the [plot] extra (pip install "fSTG-Toolkit[plot]").

python -m fstg_toolkit plot

Plot a spatio-temporal graph from an archive graph file.

The file GRAPH_PATH must be an archive containing the spatio-temporal graph.

Usage

python -m fstg_toolkit plot [OPTIONS] GRAPH_PATH COMMAND [ARGS]...

Arguments

GRAPH_PATH

Required argument

dynamic

Display an interactive dynamic graph.

Shows both spatial and temporal graphs with interactivity.

Usage

python -m fstg_toolkit plot GRAPH_PATH dynamic [OPTIONS]

multipartite

Plot as a multipartite graph.

The x-axis represents time, with nodes at each time point aligned vertically.

Note: This plot requires significant memory and may not be suitable for large graphs.

Usage

python -m fstg_toolkit plot GRAPH_PATH multipartite [OPTIONS]

spatial

Plot as a spatial connectivity graph.

Displays only the nodes and spatial edges at a specified time.

Usage

python -m fstg_toolkit plot GRAPH_PATH spatial [OPTIONS]

Options

-t, --time <time>

The time index of the spatial subgraph to show.

Default:

0

temporal

Plot as a temporal connectivity graph.

Displays all nodes and only the temporal edges.

Usage

python -m fstg_toolkit plot GRAPH_PATH temporal [OPTIONS]

dashboard

Requires the [dashboard] extra (pip install "fSTG-Toolkit[dashboard]").

python -m fstg_toolkit dashboard

Show dashboards for visualizing spatio-temporal graphs.

Usage

python -m fstg_toolkit dashboard [OPTIONS] COMMAND [ARGS]...

serve

Serve a dashboard for visualizing spatio-temporal graphs from a data directory.

Usage

python -m fstg_toolkit dashboard serve [OPTIONS] DATA_PATH UPLOAD_PATH

Options

--debug

Run the dashboard in debug mode.

-p, --port <port>

Port to run the dashboard service on.

Default:

8050

-d, --db-path <db_path>

Path to the database file to use for storing data files information.

Default:

"a 'data_files.db' file in the current directory"

-t, --token-size <token_size>

Size of the tokens used to identify the datasets. Use a larger size to accept more simultaneous datasets.

Default:

3

Arguments

DATA_PATH

Required argument

UPLOAD_PATH

Required argument

show

Show a dashboard for visualizing spatio-temporal graphs.

Usage

python -m fstg_toolkit dashboard show [OPTIONS] GRAPHS_DATA

Options

--debug

Run the dashboard in debug mode.

-p, --port <port>

Port to run the dashboard on.

Default:

8050

--no-browser

Start without opening the app in the default browser.

Arguments

GRAPHS_DATA

Required argument