cycles

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