gad

gad

Implementation of the GAD Algorithm of Stolz et. al.

Classes

Name	Description
GAD	Geometric Anomaly Detection (GAD) class for determining stratifications.

GAD

gad.GAD(
    radii=None,
    neighbors=None,
    max_dim=1,
    n_jobs=1,
    threshold=None,
    collapse_edges=None,
    outlier_label=-1.0,
    tree_type=None,
)

Geometric Anomaly Detection (GAD) class for determining stratifications.

This class implements the GAD algorithm of Stolz et. al. to determine which points are manifold, boundary, or higher co-dimension stratum points for a point cloud dependent upon two radii parameters. By running this algorithm iteratively, one can assign dimensions to each point of a data set, effectively determining a stratification. Methods implementing both of these are provided.

Parameters

Name	Type	Description	Default
radii	tuple[float, float] | None	The radii of the annular neighborhood at every point. Only one of radii or neighbors should be specified.	None
neighbors	tuple[int, int] | None	The number of neighbors of the annular neighborhood at every point. Only one of radii or neighbors should be specified.	None
max_dim	int	The maximal dimension to run GAD.	1
n_jobs	int	The number of processors to use.	1
threshold	float | str | None	The parameter at which persistent features are counted.	None
collapse_edges	bool | None	The flag determining whether to collapse edges (see giotto-tda’s documentation on VietorisRipsPersistence). The default behavior is False if max_dim < 4; otherwise it is True.	None
outlier_label	float	The dimension to assign to any outliers.	-1.0
tree_type	str | None	The style of tree to use for nearest neighbors computation. Can be either ‘KD’ for KD Tree or ‘Ball’ for Ball Tree. Default is KD Tree.	None

Note

It seems like collapse_edges should be True if the homological dimension is “large”, but what this means in practice is still not clear. This could also cause slow down if a space has strata of many different dimensions.

This class is written in the style of a scikit-learn transformer.

Methods

Name	Description
fit	Fit the model to X.
fit_predict	Predict dimension estimates using GAD.
fit_predict_pw	Compute pointwise dimension estimates.
fit_transform_global	Output a single global dimension estimate.
predict	Use the GAD algorithm to predict a list of (local) dimensions.
predict_labels	Return integer labels corresponding to GAD classification.

fit

gad.GAD.fit(X, y=None, subset=None)

Fit the model to X.

Computes the annular neighborhood around each point of X[subset], where subset is a set of indices of X.

Parameters

Name	Type	Description	Default
X	np.ndarray[tuple[int, int], np.dtype[np.float64]]	Array containing n_samples points within ambient Euclidean space of dimension n_features.	required
y	np.ndarray[tuple[int], np.dtype[np.float64]] | None	Ignored.	None
subset	np.ndarray[tuple[int], np.dtype[np.int_]] | None	Those indices of X to used to compute the algorithm. If None, then set to range(len(X)).	None

Returns

Name	Type	Description
self	GAD	Returns the instance itself.

fit_predict

gad.GAD.fit_predict(X, y=None, subset=None, propagate='NN')

Predict dimension estimates using GAD.

This method is equivalent to calling fit and then predict. This method iteratively computes a list of local dimension estimates. In a fixed dimension, points are classified as either manifold, boundary, stratified, or outlier. Starting in max_dim, any point labelled as manifold is assigned max_dim. The process is then repeated, replacing max_dim by max_dim - 1 and all manifold points removed from the point cloud until the dimension hits 0.

Parameters

Name	Type	Description	Default
X	np.ndarray[tuple[int, int], np.dtype[np.float64]]	Array containing n_samples points within ambient Euclidean space of dimension n_features.	required
y	np.ndarray[tuple[int], np.dtype[np.float64]] | None	Ignored.	None
subset	np.ndarray[tuple[int], np.dtype[np.int_]] | None	Those indices of X to used to compute the algorithm. If None, then set to list(range(X)).	None
propagate	str	Method for propagating labels from subset to X. The default parameter NN (Nearest Neighbor) propagates labels to all of X based on their closest point to subset. No other values are implemented.	'NN'

Returns

Name	Type	Description
	np.ndarray[tuple[int], np.dtype[np.int_]]	Array of local dimensions.

fit_predict_pw

gad.GAD.fit_predict_pw(X, y=None, subset=None)

Compute pointwise dimension estimates.

This is the same as predict–included for skdim API consistency.

Parameters

Name	Type	Description	Default
X	np.ndarray[tuple[int, int], np.dtype[np.float64]]	Array containing n_samples points within ambient Euclidean space of dimension n_features.	required
y	np.ndarray[tuple[int], np.dtype[np.float64]] | None	Ignored. (Default value = None)	None
subset	np.ndarray[tuple[int], np.dtype[np.int_]] | None	Those indices of X to used to compute the algorithm. If None, then set to list(range(X)).	None

Returns

Name	Type	Description
	np.ndarray[tuple[int], np.dtype[np.int_]]	Array of pointwise dimension estimates.

fit_transform_global

gad.GAD.fit_transform_global(X, y=None, subset=None)

Output a single global dimension estimate.

This method averages all of the pointwise dimension estimates from self.predict. Included for skdim API consistency.

Parameters

Name	Type	Description	Default
X	np.ndarray[tuple[int, int], np.dtype[np.float64]]	Array containing n_samples points within ambient Euclidean space of dimension n_features.	required
y	np.ndarray[tuple[int], np.dtype[np.float64]] | None	Ignored.	None
subset	np.ndarray[tuple[int], np.dtype[np.int_]] | None	Those indices of X to used to compute the algorithm. If None, then set to range(len(X)).	None

Returns

Name	Type	Description
	np.float64	Average of pointwise dimension estimates.

predict

gad.GAD.predict(X, y=None, subset=None, propagate='NN')

Use the GAD algorithm to predict a list of (local) dimensions.

This method iteratively computes a list of local dimension estimates. Starting in self.max_dim, points are classified as either manifold or non-manifold. Any point labelled as manifold is assigned max_dim. The process is then repeated, replacing max_dim by max_dim - 1 and all manifold points removed from the point cloud until the dimension hits 0.

Parameters

Name	Type	Description	Default
X	np.ndarray[tuple[int, int], np.dtype[np.float64]]	Array containing n_samples points within ambient Euclidean space of dimension n_features.	required
y	np.ndarray[tuple[int], np.dtype[np.float64]] | None	Ignored.	None
subset	np.ndarray[tuple[int], np.dtype[np.int_]] | None	Those indices of X to used to compute the algorithm. If None, then set to list(range(X)).	None
propagate	str	Method for propagating labels from subset to X. The default parameter NN (Nearest Neighbor) propagates labels to all of X based on their closest point to subset. No other values are implemented.	'NN'

Returns

Name	Type	Description
return_id	np.ndarray[tuple[int], np.dtype[np.int_]]	Array of local dimensions.

predict_labels

gad.GAD.predict_labels(X, k=1)

Return integer labels corresponding to GAD classification.

Given a positive integer k, the GAD algorithm classifies each point of X as either an outlier, boundary, manifold, or stratified according to H_{k+1}(X). This method encodes those labels as self.outlier_label, 1, 2, or 3, respectively.

Parameters

Name	Type	Description	Default
X	np.ndarray[tuple[int, int], np.dtype[np.float64]]	Array containing n_samples points within ambient Euclidean space of dimension n_features.	required
k	int	The homological degree to compute.	1

Returns

Name	Type	Description
	np.ndarray[tuple[int], np.dtype[np.int_]]	An integer numpy array.