InstanceSpace Python v0.4.1

instancespace.stages.cloister

CLOISTER Stage Module for Correlation-Based Boundary Estimation.

This module implements the CLOISTER stage, which estimates boundaries in a dataset by calculating feature correlations and using convex hull construction to define the boundary. It is designed to analyze the relationship between features and algorithmic performance, using correlation matrices to determine which features are significant.

The CLOISTER stage has several key steps:

  1. Calculate Pearson correlation coefficients between features.
  2. Filter correlations based on statistical significance (using a p-value threshold).
  3. Generate boundary estimates using minimum and maximum feature values.
  4. Apply convex hull construction to define the boundary of the feature space.

This module is structured around the CloisterStage class, which encapsulates the entire boundary estimation process. Utility methods are provided to calculate correlation matrices, generate binary representations for boundary selection, and compute convex hulls.

Dependencies:

  • numpy
  • scipy
  • loguru
Classes

CloisterStage : The primary class that implements the CLOISTER stage, providing methods to estimate boundaries using correlation and convex hulls.

Functions

cloister(x, a, options): The main function to estimate boundaries for a dataset, using a feature matrix x and projection matrix a.

class CloisterInput(typing.NamedTuple):

Inputs for the Cloister stage.

Attributes
  • x (NDArray[np.double]): The feature matrix (instances x features) provided to the CLOISTER stage.
  • a (NDArray[np.double]): The projection matrix provided to the CLOISTER stage.
  • cloister_options (Cloister Options): Options for running Cloister.
CloisterInput( x: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]], a: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]], cloister_options: instancespace.data.options.CloisterOptions, pilot_x_mean: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]] | None = None)

Create new instance of CloisterInput(x, a, cloister_options, pilot_x_mean)

x: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]

Alias for field number 0

a: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]

Alias for field number 1

cloister_options: instancespace.data.options.CloisterOptions

Alias for field number 2

pilot_x_mean: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]] | None

Alias for field number 3

class CloisterOutput(typing.NamedTuple):

Outputs from the Cloister stage.

Attributes
  • z_edge (NDArray[np.double]): Estimated boundary points.
  • z_ecorr (NDArray[np.double]): Correlated boundary points.
CloisterOutput( z_edge: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]], z_ecorr: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]])

Create new instance of CloisterOutput(z_edge, z_ecorr)

z_edge: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]

Alias for field number 0

z_ecorr: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]

Alias for field number 1

z_edge_faces: numpy.ndarray[typing.Any, numpy.dtype[numpy.int64]]

Zero-based triangles derived from the returned 3D boundary vertices.

z_ecorr_faces: numpy.ndarray[typing.Any, numpy.dtype[numpy.int64]]

Zero-based triangles derived from the correlated boundary vertices.

class CloisterStage(instancespace.stages.stage.Stage[instancespace.stages.cloister.CloisterInput, instancespace.stages.cloister.CloisterOutput]):

CloisterStage class for Correlation-Based Boundary Estimation.

The CloisterStage class implements the core functionality of the CLOISTER stage, which estimates boundaries in a dataset by analyzing the correlation between features.

The class provides methods to compute Pearson correlation coefficients, filter insignificant correlations, and generate convex hulls to create boundary estimates.

Methods

__init__(x, a) Initializes the CloisterStage with the provided feature matrix x and projection matrix a.

_run(options) Executes the CLOISTER stage to estimate boundaries based on the configuration options.

cloister(x, a, options) Main method that estimates boundaries by analyzing correlations between features and applying convex hull construction.

_inputs() Defines the input parameters required for the CLOISTER stage, which include the feature matrix x and the projection matrix a.

_outputs() Defines the output parameters returned by the CLOISTER stage, which include the estimated boundary points (z_edge) and the correlation-based boundary points (z_ecorr).

_compute_correlation(x, options) Computes the Pearson correlation matrix for the feature matrix x, and filters correlations based on statistical significance using the provided p-value threshold.

_generate_boundaries(x, rho, options) Generates boundary points for the feature matrix x based on the computed correlation matrix rho and configuration options.

_compute_convex_hull(points) Computes the convex hull for a given set of points to estimate the boundary of the dataset.

_decimal_to_binary_matrix(nfeats) Generates a binary matrix representing all possible boundary combinations for a given number of features.

@staticmethod
def cloister( x: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]], a: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]], options: instancespace.data.options.CloisterOptions, x_mean: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]] | None = None) -> CloisterOutput:

Estimate a boundary for the space using correlation.

Parameters
  • x (NDArray[np.double]): Feature matrix (instances x features) to process.
  • a (NDArray[np.double]): Projection matrix computed from Pilot.
  • options (CloisterOptions): Configuration options for CLOISTER.
  • x_mean (NDArray[np.double] | None): Fitted PILOT feature mean; None retains the uncentred boundary.
Returns
  • The output of the Cloister stage.