cycles

dgm.algorithm.cycles provides all necessary tools to search for cycles in a dgm graph. It does this by using a custom, optimized cycle search algorithm which makes use of Dijkstra's algorithm to find the shortest cycles starting (and ending again) in each node of the graph.

After running complete search, a custom cycles class is returned. This class is a wrapper around a pandas dataframe containing the cycles. The class also provides additional on top of the dataframe:

• Filtering cycles
• Selecting cycles
• Grouping cycles
• Clustering cycles
• Calculating extra measures for the cycles

CompleteSearch

Bases: NKAlgorithm

Searching all possible cycles with number of nodes greater than 2.

algorithm = DijkstraShortestPath instance-attribute

min_length = 0 instance-attribute

search_algorithms = {'dijkstra': DijkstraShortestPath, 'bfs': BreadthFirstSearch} instance-attribute

search_type = 'shortest' instance-attribute

__init__(graph)

compute_weight_matrix()

Calculate weight matrix. The weight matrix has, for each set of two nodes a value of 0 if the nodes are not connected. If the nodes are connected, the value in the matrix is the weight of the edge connectint them.

Returns:

Type	Description
ndarray	np.ndarray[N, N]: weight matrix

cycle_pairs()

For each node, find all edges connecting to it (in-neighbors). Using the distance matrix, verify if a cycle exists between with a distance larger than min_distance. If self.search_type is 'shortest', only return the closest in-neighbor, else return all in-neighbors.

Returns:

Type	Description
tuple[ndarray, ndarray]	tuple[np.ndarrays]: sources and targets

run()

Find all possible cycles in the graph.

Returns:

Name	Type	Description
Dataframe	DataFrame	Dataframe of cycles.

set_algorithm(algorithm)

Default: 'dijkstra'

set_min_length(min_length)

minimum length of a valid cycle found by the cycle search Default: 0

set_search_type(search_type)

Default: 'shortest'

to_nk_graph(graph)

CycleFilter

Class for filtering a cycle based on a parameter value (e.g. cycle length or cycle weight) It is possible to filter values equal to the parameter value, lower, higher than the parameter value or filter out the n lowest or n highest cycles, in this case n is the parameter value. In case of average, the closest value to the average is taken.

cycles = cycles instance-attribute

mode = None instance-attribute

parameter = None instance-attribute

__init__(cycles)

filter(value)

Filter cycles by condition value and mode (see CycleFilter.set_mode).

Example

If parameter = 'cycle_lenght', mode = 'less', value = 20

Only cycles with a length smaller than 20 will remain.

Parameters:

Name	Type	Description	Default
value	number	Parameter value for filtering.	required

Returns:

Type	Description
DataFrame	pd.Datagrame: Indices of cycles to keep

set_mode(mode)

Five modes are available: equal - Filter out cycles with parameter equal to value. not_equal - Filter out cycles with parameter not equal to value. greater - Filter out cycles with parameter greater than value. less - Filter out cycles with parameter less than value. n_lowest - Filter out value number of cycles with the lowest parameter value. n_highest - Filter out value number of cycles with the lowest parameter value.

set_parameter(parameter)

CycleSelection

Class for selecting a cycle based on a parameter value (e.g. cycle length or cycle weight) It is possible to select either the cycle with the smallest, largest, median or average value. In case of average, the closest value to the average is taken.

cycles = cycles instance-attribute

method = None instance-attribute

methods = {'smallest': self.select_smallest, 'greatest': self.select_greatest, 'median': self.select_median, 'average': self.select_average} instance-attribute

mode = None instance-attribute

parameter = None instance-attribute

__init__(cycles)

select()

Select a cycle based on a parameter value and using a certain mode

Example

If parameter = 'cycle_lenght', mode = 'smallest',

The cycle with the smallest cycle length will be selected.

Returns:

Type	Description
DataFrame	pd.DataFrame: datagrame of cycles

select_average(param_vals) staticmethod

select_greatest(param_vals) staticmethod

select_median(param_vals) staticmethod

select_smallest(param_vals) staticmethod

set_mode(mode)

Parameters:

Name	Type	Description	Default
mode	str	How to select a cycle based on the parameter value. Options: 'smallest', 'median', 'greatest', 'average'.	required

set_parameter(parameter)

Cycles

Bases: Serializable

The cycles class contains the results of applying the complete search algorithm on a dgm graph. The class wraps a pandas dataframe containing cycles. The class provides additional functionality such as filtering cycles, selecting cycles, clustering cycles, grouping cycles and calculating extra parameters using the cycles.

CLUSTER_METHODS = {'skl': SklClustering, 'spectral': SpectralClustering} class-attribute instance-attribute

PARAMETERIZATIONS = {'center': CycleCenter, 'normal': CycleNormal, 'intersect': CycleIntersect, 'boundary': CycleBoundary, 'winding_number': CycleWindingNumber, 'cv': CycleCv} class-attribute instance-attribute

boundaries = None instance-attribute

cluster_method = None instance-attribute

cluster_methods property

columns: list[str] property

Returns:

Name	Type	Description
list	list[str]	list of column names.

empty property

parameterizations property

__init__()

Constructor which creates a new, empty Cycles object. The cycles dataframe is already initialized.

add_boundaries(boundaries)

Add boundaries found by boundary filter to the graph. This adds a new column to the dataframe with values between 0 and len(boundaries). The number indicates around which boundary the cycle runs.

Parameters:

Name	Type	Description	Default
boundaries	list	list of boundaries.	required

add_cycle(coords, scalars, node_ids, edge_ids, weights)

Add a new cycle to the dataframe. The new cycle gets appended to the end of the dataframe.

Parameters:

Name	Type	Description	Default
coords	list | ndarray	List / array of 3D coordinates per node.	required
scalars	list | ndarray	List / array of scalars per node.	required
node_ids	list | ndarray	List / array of node IDs.	required
edge_ids	list | ndarray	List / array of sequences of edge IDs. The edges are a list of source and target node ID.	required
weights	list | ndarray	List / array of edge weights.	required

add_parameter(parameter_name, values)

Add a new parameter as a column to the dataframe. The values must contain one entry per cycle in the dataframe.

If you pass an array that has two or more dimensions, the first dimension must be of len(cycles). Each cycle will then have a N-1 dimensional value for the corresponding entry

Parameters:

Name	Type	Description	Default
parameter_name	str	name of the parameter.	required
values	list	list of values.	required

Raises:

Type	Description
ValueError	if the parameter name already exists.

Returns:

Type	Description
Self	Self

add_parameterization(parameterization) classmethod

calc_parameter(param, *args, **kwargs)

Calculates a parameter and adds it to the dataframe (as a new column). To find out possible parameters, use Cycles.PARAMETERIZATIONS.keys().

Parameters:

Name	Type	Description	Default
param	str	name of the parameter.	required

calc_parameters(*params)

Calculates multiple parameters and adds them to the dataframe (as a new column). To find out possible parameters, use Cycles.PARAMETERIZATIONS.keys().

Parameters:

Name	Type	Description	Default
params	list[str]	list of string parameter names.	()

cluster(param=None, **kwargs)

Cluster the cycles using a clustering method. To find available methods, use Cycles.CLUSTER_METHODS. Depending on the cluster method a parameter is needed based on wich to cluster. Additional parameters passed to this method will be passed to the clustering method. This adds a new parameter (column) named 'cluster_labels' See Cycles.set_cluster_method

Parameters:

Name	Type	Description	Default
param	str	name of the parameter to cluster on (optional).	None

concat(other)

Concatenate multiple cycles objects together.

Parameters:

Name	Type	Description	Default
other	Cycles | DataFrame | list | tuple	cycles to concatenate.	required

Returns:

Type	Description
Self	self

filter_by(parameter, mode, value)

Filter the cycles based on a parameter (column in the dataframe) according to a value and a filter mode. For more info, check dgm.algorithm.cycles.CycleFilter.

Example

If parameter = 'cycle_lenght', mode = 'less', value = 20

Only cycles with a length smaller than 20 will remain.

Parameters:

Name	Type	Description	Default
parameter	str	name of the parameter.	required
mode	str	mode of filtering: Options: 'equal', 'not_equal', 'grater', 'less', 'n_lowest', 'n_highest'.	required
value	int	value to filter by.	required

Returns:

Name	Type	Description
Cycles	Self	New cycles object with only the remaining cycles

from_df(df) classmethod

Alternative constructor to create a new Cycles object from a pandas dataframe.

Parameters:

Name	Type	Description	Default
df	DataFrame	Pandas dataframe containing the cycles.	required

Returns:

Name	Type	Description
Cycles	Self	new Cycles object.

from_dict(dict_) classmethod

Alternative constructor to create a new Cycles object from a pandas series.

Parameters:

Name	Type	Description	Default
dict_	dict	dictionary containing cycles.	required

Returns:

Name	Type	Description
Cycles	Self	new Cycles object.

from_series(series) classmethod

Alternative constructor to create a new Cycles object from a pandas series.

Parameters:

Name	Type	Description	Default
series	Series	Pandas series containing a cycle.	required

Returns:

Name	Type	Description
Cycles	Self	new Cycles object.

group_by(param)

Group cycles using a certain parameter. Mainly usefull for parameters with discrete values. e.g. 'cluster_labels' and returns a dictionary with the discrete values as keys and a Cluster object with the cycles corresponding to said values.

Parameters:

Name	Type	Description	Default
param	str	name of the parameter to group by.	required

Returns:

Name	Type	Description
dict	dict[object, Self]	dictionary of cycles. Keys: unique param values, Valus: Cycles

select_by(parameter, mode)

Select a single cycle from the dataframe based on a parameter (column in the dataframe) and a filter mode. For more info, check dgm.algorithm.cycles.CycleSelection.

Example

If parameter = 'cycle_lenght', mode = 'smallest',

The cycle with the smallest cycle length will be selected.

Parameters:

Name	Type	Description	Default
parameter	str	name of the parameter.	required
mode	str	mode of filtering: 'smallest', 'median', 'greatest', 'average'	required

Returns:

Name	Type	Description
Cycles	Self	New cycles object with only a single remaining cycle

set_cluster_method(method)

Set the clustering method to be used.

sort_by(parameter, ascending=True)

Sort the cycles based on a parameter (column in the dataframe)

Parameters:

Name	Type	Description	Default
parameter	str	name of the parameter.	required
ascending	bool	sort by ascending or descending values.	True

Returns:

Name	Type	Description
Cycles	Self	New cycles object where cycles are sorted based on a parameter.

to_df()

unique()

Remove duplicate cycles