Graph Construction

The Graph Construction module is a collection of transformer classes that construct adjacency matrices for graphs based on connectivity matrices. This includes well established methods like thresholding the connectivity matrix, but also allows for more complex adjacency matrix construction methods like kNN-based matrix construction. The adjacency matrices that the transform method of each class returns can then be converted into different formats like networkx, scipy sparse or dgl graphs.

Depending on the type of data you are working with, you might have very noisy data. Or you might be interested only in weaker connections. Or you want the same adjacency matrix for every graph. Transforming your connectivity matrix into an adjacency matrix of your choice can be achieved by the different graph constructor classes, which implement different transformations of the connectivity matrix. In the case of noisy data, thresholding the connections might reduce noise and increase computational speed, by having to evaluate less edges later on. Picking a threshold or percentage window allows you to discard other connections, focusing on the information that is contained in the connections that fall in your window range. And creating the same adjacency matrix for every graph, with only different node features might allow you to use graph algorithms you might otherwise not be able to use.

classDiagram-v2
    direction RL
    class Graph Constructor{
    +fit()
    +transform()
    +fit_transform()
    }
    Graph Constructor <|-- GraphConstructorThreshold
    Graph Constructor <|-- GraphConstructorPrecentage
    Graph Constructor <|-- GraphConstructorThresholdWindow
    Graph Constructor <|-- GraphConstructorPercentageWindow
    Graph Constructor <|-- GraphConstructorKNN
    Graph Constructor <|-- GraphConstructorSpatial
    Graph Constructor <|-- GraphConstructorRandomWalks

    link GraphConstructor "/photonai_graph/api/graph_construction/#graphconstructor"
    link GraphConstructorThreshold "/photonai_graph/api/graph_construction/#graphconstructorthreshold"
    link GraphConstructorPercentage "/photonai_graph/api/graph_construction/#graphconstructorpercentage"
    link GraphConstructorThresholdWindow "/photonai_graph/api/graph_construction/#graphconstructorthresholdwindow"
    link GraphConstructorPercentageWindow "/photonai_graph/api/graph_construction/#graphconstructorpercentagewindow"
    link GraphConstructorKNN "/photonai_graph/api/graph_construction/#graphconstructorknn"
    link GraphConstructorSpatial "/photonai_graph/api/graph_construction/#graphconstructorspatial"
    link GraphConstructorRandomWalks "/photonai_graph/api/graph_construction/#graphconstructorrandomwalks"

Hint: By clicking on the class in the above diagram you will find the according documentation.

GraphConstructor

Base class for all graph constructors. Implements methods shared by different constructors.

Parameters:

Name	Type	Description	Default
`one_hot_nodes`	`int`	whether to return a one hot node encoding as feature or not	`0`
`use_abs`	`int`	whether to convert all matrix values to absolute values before applying other transformations	`0`
`fisher_transform`	`int`	whether to perform a fisher transform of every matrix	`0`
`discard_original_connectivity`	`bool`	If true the second index of the last dimension will be the original connectivity. Otherwise the original connectivity will be dropped from the matrix.	`False`
`use_abs_fisher`	`int`	Changes the values to absolute values. Is applied after fisher transform and before z-score transformation	`0`
`zscore`	`int`	performs a zscore transformation of the data. Applied after fisher transform and np_abs eval_final_perfomance is set to True	`0`
`use_abs_zscore`	`int`	whether to use the absolute values of the z-score transformation or allow for negative values. Applied after fisher transform, use_abs and zscore	`0`
`adjacency_axis`	`int`	position of the adjacency matrix, default being zero	`0`
`logs`	`str`	Path to the log data	`None`

GraphConstructorThreshold

Transformer class for generating adjacency matrices from connectivity matrices. Thresholds matrix based on a chosen threshold value.

Parameters:

Name	Type	Description	Default
`threshold`	`float`	threshold value below which to set matrix entries to zero	`0.1`
`concatenation_axis`	`int`	axis along which to concatenate the adjacency and feature matrix	`3`
`return_adjacency_only`	`int`	whether to return the adjacency matrix only (1) or also a feature matrix (0)	`0`
`retain_weights`	`int`	whether to retain weight values or not	`0`
`discard_original_connectivity`	`bool`	If true the original connectivity will be passed on. Otherwise it gets discarded	`False`
`one_hot_nodes`	`int`	Whether to generate a one hot encoding of the nodes in the matrix (1) or not (0)	`0`
`use_abs`	`int`	whether to convert all matrix values to absolute values before applying other transformations	`0`
`fisher_transform`	`int`	whether to perform a fisher transform of each matrix (1) or not (0)	`0`
`use_abs_fisher`	`int`	changes the values to absolute values. Is applied after fisher transform and before z-score transformation	`0`
`zscore`	`int`	performs a zscore transformation of the data. Applied after fisher transform and np_abs	`0`
`use_abs_zscore`	`int`	whether to use the absolute values of the z-score transformation or allow for negative values	`0`
`adjacency_axis`	`int`	position of the adjacency matrix, default being zero	`0`
`logs`	`str`	Path to the log data	`None`

Example

Use outside of a PHOTON pipeline

Python

constructor = GraphConstructorThreshold(threshold=0.5,
                                        fisher_transform=1,
                                        use_abs=1)

Or as part of a pipeline

Python

my_pipe.add(PipelineElement('GraphConstructorThreshold',
                            hyperparameters={'threshold': 0.5}))

GraphConstructorPercentage

Transformer class for generating adjacency matrices from connectivity matrices. Selects the top x percent of connections and sets all other connections to zero

Parameters:

Name	Type	Description	Default
`percentage`	`float`	value of percent of connections to discard. A value of 90 keeps only the top 10%	`80`
`retain_weights`	`float`	whether to retain weight values or not	`0`
`one_hot_nodes`	`int`	Whether to generate a one hot encoding of the nodes in the matrix (1) or not (0)	`0`
`use_abs`	`int`	whether to convert all matrix values to absolute values before applying other transformations	`0`
`fisher_transform`	`int`	whether to perform a fisher transform of each matrix (1) or not (0)	`0`
`use_abs_fisher`	`int`	changes the values to absolute values. Is applied after fisher transform and before z-score transformation	`0`
`zscore`	`int`	performs a zscore transformation of the data. Applied after fisher transform and np_abs	`0`
`use_abs_zscore`	`int`	whether to use the absolute values of the z-score transformation or allow for negative values	`0`
`adjacency_axis`	`int`	position of the adjacency matrix, default being zero	`0`
`logs`	`str`	Path to the log data	`None`

Example

Use outside of a PHOTON pipeline

Python

constructor = GraphConstructorPercentage(percentage=0.9,
                                         fisher_transform=1,
                                         use_abs=1)

Or as part of a pipeline

Python

my_pipe.add(PipelineElement('GraphConstructorPercentage',
                            hyperparameters={'percentage': 0.9}))

GraphConstructorThresholdWindow

Transformer class for generating adjacency matrices from connectivity matrices. Thresholds matrix based on a chosen threshold window.

Parameters:

Name	Type	Description	Default
`threshold_upper`	`float`	upper limit of the threshold window	`1`
`threshold_lower`	`float`	lower limit of the threshold window	`0.8`
`retain_weights`	`float`	whether to retain weight values or not	`0`
`one_hot_nodes`	`int`	Whether to generate a one hot encoding of the nodes in the matrix.	`0`
`use_abs`	`int`	whether to convert all matrix values to absolute values before applying other transformations	`0`
`fisher_transform`	`int`	Perform a fisher transform of each matrix. No (0) or Yes (1)	`0`
`use_abs_fisher`	`int`	Changes the values to absolute values. Is applied after fisher transform and before z-score transformation	`0`
`zscore`	`int`	performs a zscore transformation of the data. Applied after fisher transform and np_abs eval_final_perfomance is set to True	`0`
`use_abs_zscore`	`int`	whether to use the absolute values of the z-score transformation or allow for negative values. Applied after fisher transform, use_abs and zscore	`0`
`adjacency_axis`	`int`	position of the adjacency matrix, default being zero	`0`
`logs`	`str`	Path to the log data	`None`

Example

Use outside of a PHOTON pipeline

Python

constructor = GraphConstructorThresholdWindow(threshold_upper=0.7,
                                              threshold_lower=0.3,
                                              use_abs=1)

Or as part of a pipeline

Python

my_pipe.add(PipelineElement('GraphConstructorThresholdWindow',
                            hyperparameters={'threshold_upper': 0.7, 'threshold_lower': 0.3}))

GraphConstructorPercentageWindow

Transformer class for generating adjacency matrices from connectivity matrices. Selects the top x percent of connections and sets all other connections to zero

Parameters:

Name	Type	Description	Default
`percentage_upper`	`float`	upper limit of the percentage window	`50`
`percentage_lower`	`float`	lower limit of the percentage window	`10`
`one_hot_nodes`	`int`	Whether to generate a one hot encoding of the nodes in the matrix (1) or not (0)	`0`
`use_abs`	`int`	whether to convert all matrix values to absolute values before applying other transformations	`0`
`fisher_transform`	`int`	whether to perform a fisher transform of each matrix (1) or not (0)	`0`
`use_abs_fisher`	`int`	changes the values to absolute values. Is applied after fisher transform and before z-score transformation	`0`
`zscore`	`int`	performs a zscore transformation of the data. Applied after fisher transform and np_abs	`0`
`use_abs_zscore`	`int`	whether to use the absolute values of the z-score transformation or allow for negative values	`0`
`adjacency_axis`	`int`	position of the adjacency matrix, default being zero	`0`
`logs`	`str`	Path to the log data	`None`

Example

Use outside of a PHOTON pipeline

Python

constructor = GraphConstructorPercentageWindow(percentage_upper=0.9,
                                               percentage_lower=0.7
                                               fisher_transform=1,
                                               use_abs=1)

Or as part of a pipeline

Python

my_pipe.add(PipelineElement('GraphConstructorPercentageWindow',
                            hyperparameters={'percentage_upper': 0.9, 'percentage_lower': 0.7}))

GraphConstructorKNN

Transformer class for generating adjacency matrices from connectivity matrices. Selects the k nearest neighbours for each node based on pairwise distance. Recommended for functional connectivity. Adapted from Ktena et al, 2017.

Parameters:

Name	Type	Description	Default
`k_distance`	`int`	the k nearest neighbours value, for the kNN algorithm.	`10`
`one_hot_nodes`	`int`	Whether to generate a one hot encoding of the nodes in the matrix (1) or not (0)	`0`
`use_abs`	`int`	whether to convert all matrix values to absolute values before applying other transformations	`0`
`fisher_transform`	`int`	whether to perform a fisher transform of each matrix (1) or not (0)	`0`
`use_abs_fisher`	`int`	changes the values to absolute values. Is applied after fisher transform and before z-score transformation	`0`
`zscore`	`int`	performs a zscore transformation of the data. Applied after fisher transform and np_abs	`0`
`use_abs_zscore`	`int`	whether to use the absolute values of the z-score transformation or allow for negative values	`0`
`adjacency_axis`	`int`	position of the adjacency matrix, default being zero	`0`
`logs`	`str`	Path to the log data	`None`

Example

Use outside of a PHOTON pipeline

Python

constructor = GraphConstructorKNN(k_distance=6,
                                  fisher_transform=1,
                                  use_abs=1)

Or as part of a pipeline

Python

my_pipe.add(PipelineElement('GraphConstructorKNN',
                            hyperparameters={'k_distance': 6}))

GraphConstructorSpatial

Transformer class for generating adjacency matrices from connectivity matrices. Selects the k nearest neighbours for each node based on spatial distance of the coordinates in the chosen atlas. This method can be applied to both DTI and rs-fMRI data. A user can construct their own atlas using defined spatial coordinates that match those regions used in the correspoding connectivity matrices. Adapted from Ktena et al, 2017.

Danger

Currently considered untested! See Ticket

Parameters:

Name	Type	Description	Default
`k_distance`	`int`	the k nearest neighbours value, for the kNN algorithm.	`10`
`atlas_name`	`str`	name of the atlas coordinate file	`'ho'`
`atlas_folder`	`str`	path to the atlas coordinate file	`None`
`one_hot_nodes`	`int`	Whether to generate a one hot encoding of the nodes in the matrix (1) or not (0)	`0`
`use_abs`	`int`	whether to convert all matrix values to absolute values before applying other transformations	`0`
`fisher_transform`	`int`	whether to perform a fisher transform of each matrix (1) or not (0)	`0`
`use_abs_fisher`	`int`	changes the values to absolute values. Is applied after fisher transform and before z-score transformation	`0`
`zscore`	`int`	performs a zscore transformation of the data. Applied after fisher transform and np_abs	`0`
`use_abs_zscore`	`int`	whether to use the absolute values of the z-score transformation or allow for negative values	`0`
`adjacency_axis`	`int`	position of the adjacency matrix, default being zero	`0`
`logs`	`str`	Path to the log data	`None`

Example

Use outside of a PHOTON pipeline

Python

constructor = GraphConstructorSpatial(k_distance=7,
                                      atlas_name="ho_coords.csv",
                                      atlas_path="path/to/your/data/",
                                      fisher_transform=1,
                                      use_abs=1)

Or as part of a pipeline

Python

my_pipe.add(PipelineElement('GraphConstructorSpatial',
                            hyperparameters={'k_distance': 7,
                            'atlas_name': "ho_coords.csv", 'atlas_path': "path/to/your/data/"}))

GraphConstructorRandomWalks

Transformer class for generating adjacency matrices from connectivity matrices. Generates a kNN matrix and performs random walks on these. The coocurrence of two nodes in those walks is then used to generate a higher-order adjacency matrix, by applying the kNN algorithm on the matrix again. Adapted from Ma et al., 2019.

Parameters:

Name	Type	Description	Default
`k_distance`	`int`	the k nearest neighbours value, for the kNN algorithm.	`10`
`number_of_walks`	`int`	number of walks to take to sample the random walk matrix	`10`
`walk_length`	`int`	length of the random walk, as the number of steps	`10`
`window_size`	`int`	size of the sliding window from which to sample to coocurrence of two nodes	`5`
`no_edge_weight`	`int`	whether to return an edge weight (0) or not (1)	`1`
`one_hot_nodes`	`int`	Whether to generate a one hot encoding of the nodes in the matrix (1) or not (0)	`0`
`use_abs`	`int`	whether to convert all matrix values to absolute values before applying other transformations	`0`
`fisher_transform`	`int`	whether to perform a fisher transform of each matrix (1) or not (0)	`0`
`use_abs_fisher`	`int`	changes the values to absolute values. Is applied after fisher transform and before z-score transformation	`0`
`zscore`	`int`	performs a zscore transformation of the data. Applied after fisher transform and np_abs	`0`
`use_abs_zscore`	`int`	whether to use the absolute values of the z-score transformation or allow for negative values	`0`
`adjacency_axis`	`int`	position of the adjacency matrix, default being zero	`0`
`logs`	`str`	Path to the log data	`None`

Example

Use outside of a PHOTON pipeline

Python

constructor = GraphConstructorRandomWalks(k_distance=5,
                                          number_of_walks=25,
                                          fisher_transform=1,
                                          use_abs=1)

Or as part of a pipeline

Python

my_pipe.add(PipelineElement('GraphConstructorRandomWalks',
                            hyperparameters={'k_distance': 5,
                            'number_of_walks': 25}))