instancespace.stages

Initialize the Preprocessing stage.

Select features and algorithms from the dataset.

Based on the user's configuration, this method filters the features and algorithms that should be used in subsequent stages.

Parameters

• x (NDArray[np.double]): 2D numpy array representing the feature matrix (instances x features).
• y (NDArray[np.double]): 2D numpy array representing the algorithm matrix (instances y algorithms).
• feat_labels (list[str]): List of labels corresponding to the features in 'x'.
• algo_labels (list[str]): List of labels corresponding to the algorithms in 'y'.
• selvars (SelvarsOptions): An instance of SelvarsOptions that contains settings of the prefered algorithms and instances.

Returns

• tuple[NDArray[np.double], NDArray[np.double], list[str], list[str]]: A tuple containing:
  • Modified feature matrix after feature selection and instance removal.
  • Modified algorithm matrix after algorithm selection and instance removal.
  • List of selected feature labels.
  • List of selected algorithm labels.

Remove instances and features with excessive missing values.

Instances (rows) with too many missing values are removed. Additionally, features (columns) that exceed a missing value threshold are also removed. Washing criterion: 1. For any row, if that row in both X and Y are NaN, remove 2. For X columns, if that column's 20% grids are filled with NaN, remove

Parameters

• x (NDArray[np.double]): 2D numpy array representing the feature matrix (instances x features).
• y (NDArray[np.double]): 2D numpy array representing the algorithm matrix (instances y algorithms).
• s (pd.Series | None): Optional series containing the source of instances.
• feat_labels (list[str]): List of labels corresponding to the features in 'x'.
• inst_labels (pd.Series): Series containing labels for each instance.
• nan_threshold (float): Fraction of missing values at which a feature is removed.

Returns

• tuple[NDArray[np.double], NDArray[np.double],
• pd.Series, list[str], pd.Series | None]: A tuple containing the modified feature matrix 'x', the modified algorithm matrix 'y',updated instance labels, list of feature labels that remain after removal, and optionally modified series 's' if provided.

See file docstring.

Apply fitted bounds and normalisation without re-fitting PRELIM.

Perform preliminary processing on the input data 'x' and 'y'.

Parameters

• x (NDArray[np.double]): The feature matrix (instances x features) to process.
• y (NDArray[np.double]): The performance matrix (instances x algorithms) to process.
• x_raw (NDArray[np.double]): The raw feature matrix.
• y_raw (NDArray[np.double]): The raw performance matrix.
• s (pd.Series | None): The instance source labels, or None.
• inst_labels (pd.Series): The instance labels.
• prelim_opts (PrelimOptions): The options for the preliminary processing.
• selvars_opts (SelvarsOptions): The options for the instance and feature selection.
• general_opts (GeneralOptions): The general options for all stages.

Returns

• tuple: The first items are the processed data: x, y, y_bin, y_best, p, num_good_algos, and beta. The remaining items are the fitted bound and normalization parameters: med_val, iq_range, hi_bound, lo_bound, min_x, lambda_x, mu_x, sigma_x, min_y, lambda_y, sigma_y, and mu_y.

Define the input variables for the stage.

Parameters

• x (NDArray[np.double]): Feature matrix to be processed (instances x features).
• y (NDArray[np.double]): Algorithm performance matrix (instances x algorithms).
• y_bin (NDArray[np.bool_]): Binary matrix indicating good algorithm performance.
• feat_labels (list[str]): List of feature labels.
• x_raw (NDArray[np.double]): Raw feature matrix.
• y_raw (NDArray[np.double]): Raw performance matrix.
• beta (NDArray[np.bool_]): Per-instance beta-easy labels.
• num_good_algos (NDArray[np.double]): Number of good algorithms for each instance.
• y_best (NDArray[np.double]): Best algorithm performance for each instance.
• p (NDArray[np.int_]): One-based best-algorithm index for each instance.
• inst_labels (pd.Series): Instance labels for the dataset.
• s (pd.Series | None): The instance source labels, or None.
• opts (SiftedOptions): The configuration options for the SIFTED stage.
• parallel_options (ParallelOptions): An instance of ParallelOptions containing parallel processing parameters.
• general_opts (GeneralOptions): General options (e.g. the RNG seed), not specific to any one stage.

Apply fitted feature indices without re-running selection.

Public method to access the private _sifted method.

Core Sifted stage to process feature selection and performance.

Parameters

• x (NDArray[np.double]): Feature matrix (instances x features).
• y (NDArray[np.double]): Performance matrix of algorithms (instances x algorithms).
• y_bin (NDArray[np.bool_]): Binary matrix indicating instances with good algorithm performance.
• x_raw (NDArray[np.double]): Unprocessed feature matrix.
• y_raw (NDArray[np.double]): Unprocessed performance matrix.
• beta (NDArray[np.bool_]): Per-instance beta-easy labels.
• num_good_algos (NDArray[np.double]): Number of good algorithms per instance.
• y_best (NDArray[np.double]): Best algorithm performance for each instance.
• p (NDArray[np.int_]): Array of correlation p-values for features.
• inst_labels (pd.Series): Labels for each instance in the dataset.
• s (pd.Series | None): Series for optional selection during processing.
• feat_labels (list[str]): List of feature labels.
• opts (SiftedOptions): Configuration options for the Sifted stage.
• opts_selvars (SelvarsOptions): Options for selecting variables within the stage.
• data_dense (DataDense | None): Dense data representation, if available.
• parallel_options (ParallelOptions): Options for parallel processing.
• general_options (GeneralOptions): General options (e.g. the RNG seed), not specific to any one stage.

Returns

• SiftedOutput: Output of the Sifted stage, including selected feature and algorithm indices,correlation coefficients, performance metrics, silhouette scores, and feature selection flags.

Notes

This static method initialises a SiftedStage instance and calls its _sifted method, which uses the provided options and data to execute the Sifted stage pipeline and generate results.

Select features based on correlation with performance.

Returns

• x_aux (NDArray[np.double]): Filtered feature matrix after selection.
• rho (NDArray[np.double]): Pearson correlation coefficients between features and performance.
• pval (NDArray[np.double]): p-values for the correlation coefficients.
• selvars (NDArray[np.intc]): Indices of the selected features.

Select features based on clustering.

Parameters

• x_aux (NDArray[np.double]): Auxiliary feature matrix used for clustering.
• rng (np.random.Generator): Random number generator for reproducibility.

Returns

• clust (NDArray[np.bool_]): Boolean matrix where each column represents a cluster.
• cluster_labels (NDArray[np.intc]): Labels for the clusters.

Fitness function to evaluate the quality of solution in GA.

Parameters

• instance (pygad.GA): The instance of the genetic algorithm.
• solutions (NDArray[np.intc]): The array of integer values representing the solution to be evaluated.
• solution_idx (int): The index of the solution being evaluated.

Returns

• float: The fitness score of the solution: the worst (lowest) per- algorithm k-NN classification accuracy. pygad.GA always maximizes whatever this returns, so maximizing the minimum per-algorithm accuracy directly is equivalent to MATLAB's fitcknn/kfoldLoss-based costfcn (core/SIFTED.m), which ga() minimizes as max_i(loss_i) - -max_i(1 - acc_i) = min_i(acc_i) - 1, the same optimum up to an additive constant without changing the optimal feature set.

Evaluate cluster based on silhouette scores.

Parameters

• x_aux (NDArray[np.double]): Auxiliary feature matrix used for clustering.
• rng (np.random.Generator): Random number generator for reproducibility.

Returns

• silhouette_scores (list[float]): Silhouette scores for different cluster configurations.
• cluster_labels (NDArray[np.intc]): Labels for the selected cluster configuration.

Initialize the Pilot stage.

The Initialize functon is used to create a Pilot class.

Parameters

• x (NDArray[np.double]): The feature matrix (instances x features) to process.
• y (NDArray[np.double]): The data points for the selected feature.
• feat_labels (list[str]): The feature names.

Returns

• None

Project with the fitted PLS mean; older models retain linear inference.

Run the PILOT dimensionality reduction algorithm.

Parameters

• x (NDArray[double]): The feature matrix (instances x features) to process.
• y (NDArray[double]): The data points for the selected feature.
• feat_labels (list[str]): List feature names.
• options (PilotOptions): The options enabled for the Pilot Class.
• general_options (GeneralOptions): General options for all stages, for example the RNG seed.
• y_bin (NDArray[np.bool_] | None): Binary matrix (instances x algorithms) indicating good algorithm performance. Required only when options.adjust_rotation is set.
• parallel_options (ParallelOptions | None): Whether (and how much) to parallelise the numerical solver's ntries restart loop. None (the default for direct callers that don't pass one) runs the restarts sequentially, same as flag=False.

Returns

• PilotOutput: Outputs from the Pilot stage.

Rotate the 2D projection so poorly-solved instances face theta.

Ported from PyISpace's pilot.adjust_rotation() (gitlab.com/ita-ml/pyispace). Rotation preserves all pairwise distances in z, so it only changes the space's visual orientation

• error, R2, and footprint areas are unaffected. The centroid of the instances flagged by bad_instances is rotated to sit at theta degrees (135 = upper-left quadrant, matching PyISpace's default), so that similar datasets come out consistently oriented across runs.

Parameters

• z (NDArray[np.double]): The 2D projection (instances x 2) to rotate.
• bad_instances (NDArray[np.bool_]): Boolean mask selecting the instances whose centroid should be placed at theta.
• theta (float): Target angle, in degrees, for the bad-instance centroid.

Returns

• NDArray[np.double]: The rotated projection, same shape as z.
• NDArray[np.double]: The 2x2 rotation matrix applied.

Solve the projection problem analytically.

Parameters

• x (NDArray[np.double]): The feature matrix (instances x features) to process.
• x_bar (NDArray[np.double]): Combined matrix of X and Y.
• n (int): Number of original features.
• m (int): Total number of features including appended Y.
• cost_weight (float): Scalar performance-reconstruction weight (MATLAB's costWeight). Scales the performance block relative to the feature block before the eigendecomposition; 1.0 weights both blocks equally.
• dims (int): Output projection dimensionality, either 2 or 3.

Returns

• NDArray[np.double]: Matrix A.
• NDArray[np.double]: Matrix B.
• NDArray[np.double]: Matrix C.
• NDArray[np.double]: Matrix Z.
• NDArray[np.double]: The mean squared error between x_bar and its low-dimensional approximation.
• NDArray[np.double]: The coefficient of determination between x_bar and its low-dimensional approximation.

Solve the projection problem via Partial Least Squares.

MATLAB's method='pls' alternative to the analytic/numeric eigen-decomposition solvers above - a genuinely different algorithm, not a variant of either. dims matches MATLAB's own plsregress(X, Y, d) call.

Implements the SIMPLS routine used by MATLAB R2026a's plsregress. Both inputs are mean-centred but not variance-scaled, matching the default MATLAB call in PILOT.m.

Parameters

• x (NDArray[np.double]): The feature matrix (instances x features) to process.
• y (NDArray[np.double]): The performance matrix (instances x algorithms).
• x_bar (NDArray[np.double]): Combined matrix of X and Y.
• m (int): Total number of features including appended Y.
• dims (int): Output projection dimensionality, either 2 or 3.

Returns

• NDArray[np.double]: Matrix A (dims x n), the projection matrix: Z = (X - mean(X)) @ A.T.
• NDArray[np.double]: Matrix Z (instances x dims), the projected coordinates.
• NDArray[np.double]: Matrix C (dims x q), the performance-block reconstruction matrix.
• NDArray[np.double]: Matrix B (n x dims), the feature-block reconstruction matrix.
• NDArray[np.double]: The sum of squared reconstruction error between x_bar and its low-dimensional approximation.
• NDArray[np.double]: The per-column coefficient of determination between x_bar and its low-dimensional approximation.

Solve the projection problem numerically.

Parameters

• x (NDArray[np.double]): The feature matrix (instances x features) to process.
• hd (NDArray[np.double]): Condensed pairwise distances between the instances in feature space. The quality of each trial is the Pearson correlation between these distances and the distances in the projected space.
• x0 (NDArray[np.double]): Initial guess for the solution.
• x_bar (NDArray[np.double]): Combined matrix of X and Y.
• n (int): Number of original features.
• m (int): Total number of features including appended Y.
• alpha (NDArray[np.double]): Flattened parameter vector containing both A (dimsn size) and B (mdims size) matrices.
• eoptim (NDArray[np.double]): Optimized error function.
• perf (NDArray[np.double]): Optimized performance matrix.
• opts (PilotOptions): Configuration options for PILOT.
• general_options (GeneralOptions): General options for all stages, for example verbosity.
• parallel_options (ParallelOptions | None): Whether (and how much) to parallelise the ntries restarts across OS processes (matching MATLAB's parfor). None or flag=False runs the restarts sequentially. Ignored - falls back to sequential - when already running inside another process pool's worker (see multiprocessing.parent_process() check below): SIFTED's GA fitness function calls into pilot() from inside its own ProcessPoolExecutor workers, and opening a second, nested pool there would reintroduce MATLAB's nested-parfor-inside-GA bug. In practice this never triggers today, since SIFTED always calls pilot() with analytic=True (bypassing this numerical branch entirely) - this check guards against that invariant ever changing silently.

Returns

• int: The index of the trial that has the highest distance correlation.
• NDArray[np.double]: Flattened parameter vector containing both A (dimsn size) and B (mdims size) matrices.
• NDArray[np.double]: Optimized error function.
• NDArray[np.double]: Optimized performance matrix.

Error function used for numerical optimization in the PILOT algorithm.

Parameters

• alpha (NDArray[np.float64]): Flattened parameter vector containing both A (dn size) and B (md size) matrices.
• x_bar (NDArray[np.float64]): Combined matrix of X and Y.
• n (int): Number of original features.
• m (int): Total number of features including appended Y.
• cost_weight (float): Scalar weight applied to the performance columns' squared error (MATLAB's pilotErrorFcn costWeight). 1.0 weights every column equally.
• d (int): Output projection dimensionality, either 2 or 3.

Returns

• float: The mean squared error between x_bar and its low-dimensional approximation.

Define the input for the Pythia stage.

Parameters

• z (NDArray[np.double]): The feature matrix.
• y_raw (NDArray[np.double]): The performance metrics.
• y_bin (NDArray[np.bool_]): The binary labels.
• y_best (NDArray[np.double]): The best performance metrics.
• algo_labels (list[str]): The algorithm labels.

Apply persisted PYTHIA state without fitting or mutating classifiers.

This is MATLAB's PYTHIAevalMode prediction core: normalize new coordinates with the parameters stored by the training run, apply each fitted classifier, pad test-only algorithms with empty predictions, and make the same precision-weighted recommendation as the build path.

Evaluate predictions with MATLAB's explicit confusion-count formulas.

MATLAB stores confusion counts in column-major order: [TN, FN, FP, TP]. Only observed instance/algorithm pairs contribute. inputs.observed has shape (n_instances, n_trained_algorithms) and must come from raw outcome availability, not binary labels. Accuracy uses the observed count for each algorithm. Missing classifiers, wholly unobserved algorithms and test-only algorithms retain NaN counts and rates.

Run the Pythia stage.

Parameters

• z (NDArray[np.double]): The feature matrix.
• y (NDArray[np.double]): The performance metrics.
• y_bin (NDArray[np.bool_]): The binary labels.
• y_best (NDArray[np.double]): The best performance metrics.
• algo_labels (list[str]): The algorithm labels.
• opts (PythiaOptions): The options for the Pythia stage.
• parallel_options (ParallelOptions): The parallel options, specifiy whether run in parallel and number of cores.
• general_options (GeneralOptions): General options (e.g. the RNG seed), not specific to any one stage.

Returns

• PythiaOutput: The output of the Pythia stage.

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.

Initialise the Trace analysis with provided data and options.

Parameters

• z (NDArray[np.double]): The space of instances, represented as an array of data points (features).
• y_bin (NDArray[np.bool_]): Binary indicators of performance for each algorithm.
• p (NDArray[np.int_]): Performance metrics for algorithms, where each value corresponds to the index of an algorithm.
• beta (NDArray[np.bool_]): Specific binary thresholds for footprint calculation.
• algo_labels (list[str]): List of labels for each algorithm.
• trace_opts (TraceOptions): Configuration options for TRACE and its subroutines.
• parallel_opts (ParallelOptions): Configuration options for parallel processing in Matilda.
• general_opts (GeneralOptions): General options (e.g. verbosity), not specific to any one stage.
• executor (ThreadPoolExecutor | None): A caller-owned, already-running pool to submit footprint work to instead of creating and tearing down a fresh one. None (the default) preserves the previous per-call pool behaviour.
• y_hat (NDArray[np.bool_] | None): Optional PYTHIA predictions used only by TRACE3.
• pythia_skipped (bool): Whether PYTHIA intentionally returned placeholder predictions.

Apply trained TRACE geometry without rebuilding or mutating it.

Perform the TRACE footprint analysis.

Parameters

• z (NDArray[np.double]): The space of instances.
• y_bin (NDArray[np.bool_]): Binary indicators of performance.
• p (NDArray[np.int_]): Performance metrics for algorithms.
• beta (NDArray[np.bool_]): Specific beta threshold for footprint calculation.
• algo_labels (list[str]): Labels for each algorithm.
• trace_opts (TraceOptions): Configuration options for TRACE and its subroutines.
• parallel_opts (ParallelOptions): Configuration options for parallel processing in Matilda.
• general_opts (GeneralOptions): General options for all stages, for example verbosity.
• executor (ThreadPoolExecutor | None): A caller-owned pool to reuse instead of creating a fresh one.
• y_hat (NDArray[np.bool_] | None): Optional PYTHIA predictions used only by TRACE3.
• pythia_skipped (bool): Whether PYTHIA intentionally returned placeholder predictions.

Returns

• TraceOutputs: The analysis results. These include the footprints and the summary statistics.

Re-evaluate trained geometry against new truth without rebuilding it.

Construct a footprint polygon using DBSCAN clustering.

Parameters

• y_bin (NDArray[np.bool_]): Binary indicator vector indicating which data points are of interest.

Returns

• Footprint: The constructed footprint with calculated area, density, and purity.

Detect and resolve contradictions between two footprint polygons.

Parameters

• base (Footprint): The base footprint polygon.
• test (Footprint): The test footprint polygon.
• y_base (NDArray[np.bool_]): Binary array indicating the points corresponding to the base footprint.
• y_test (NDArray[np.bool_]): Binary array indicating the points corresponding to the test footprint.

Returns

• tuple: Updated base and test footprints after resolving contradictions.

Refine an existing polygon by removing slivers and improving its shape.

Parameters

• polygon (Polygon | MultiPolygon): The polygon or multipolygon to be refined.
• y_bin (NDArray[np.bool_]): Binary array indicating which data points belong to the polygon.

Returns

• Polygon | MultiPolygon: The refined polygon, or an empty polygon if refinement fails.

Fit a polygon to the given data points, following the purity constraints.

Parameters

• polydata (NDArray[np.double]): The data points to fit the polygon to.
• y_bin (NDArray[np.bool_]): Binary array indicating which data points should be considered for the polygon.

Returns

• Polygon | MultiPolygon | None: The fitted polygon, or None if the fitting fails.

Summarize the footprint metrics.

Parameters

• footprint (Footprint): The footprint to summarize.
• space_area (float): The total area of the space being analyzed.
• space_density (float): The density of the entire space.

Returns

• list: A list containing summarized metrics such as area, normalized area, density, normalized density, and purity.

Generate a footprint with default values, indicating insufficient data.

Returns

• Footprint: An instance of Footprint with default values.

Perform DBSCAN clustering on the dataset.

Parameters

• y_bin (NDArray[np.bool_]): Binary indicator vector to filter the data points.
• data (NDArray[np.double]): The dataset to cluster.

Returns

• NDArray[np.int_]: Array of cluster labels for each data point.

Analytical way of estimating neighborhood radius for DBSCAN.

Parameters

• x (NDArray[np.double]): data matrix (m, n); m-objects, n-variables
• k (int): number of objects in a neighborhood of an object (minimal number of objects considered as a cluster)

Returns

• float: The estimated neighborhood radius.

Calculate the Euclidean distances between objects.

Parameters

• i (NDArray[np.double]): an object (1, n)
• x (NDArray[np.double]): data matrix (m, n); m-objects, n-variables

Returns

• NDArray[np.double]: The Euclidean distances, with shape (m,).

Density-Based Spatial Clustering of Applications with Noise (DBSCAN).

Parameters

• x (NDArray[np.double]): data matrix (m, n); m-objects, n-variables
• k (int): minimum number of points to form a cluster
• eps (float): neighborhood radius; if None, it will be estimated using the epsilon function

Returns

• NDArray[np.int_]: Cluster assignments for each point (-1 for noise)

Process an algorithm to calculate its good and best performance footprints.

Parameters

• i (int): Index of the algorithm to process.

Returns

• tuple[int, Footprint, Footprint]: The index of the algorithm, and its good and best performance footprints.

Perform parallel processing to calculate footprints for multiple algorithms.

Parameters

• n_workers (int): Number of worker threads to use.
• n_algos (int): Number of algorithms to process.

Returns

• tuple[list[Footprint], list[Footprint]]: Lists of good and best performance footprints for each algorithm.

Apply fitted state without training or mutating it.