Options Reference

Every supported configuration field, with defaults read from the Python classes

Use immutable option dataclasses or load a nested JSON object. Omit settings you do not need to change.

Syntax

from instancespace.data.options import InstanceSpaceOptions, PilotOptions

options = InstanceSpaceOptions.default(pilot=PilotOptions.default(dims=3))
options = InstanceSpaceOptions.from_dict({"pilot": {"dims": 3}})

Configuration Rules

The tables use canonical Python field names. JSON accepts these names and the explicit aliases shown, case-insensitively. Validation rejects unknown or conflicting fields. Construct a new configuration with dataclasses.replace; do not mutate a frozen dataclass.

Defaults below describe InstanceSpaceOptions.default(). A stage seed of None inherits general.seed. TRACE's omitted purity is method-dependent: 0.55 for legacy, 0.60 for trace3. Select method="trace3" explicitly when that policy is required.

For direct PRELIM calls, PrelimOptions.from_options(options) composes perf, bound.flag, norm.flag, auto.preproc and prelim. It does not add JSON fields. Exact constructor signatures and composed fields are in the options API.

options.parallel

Field	Default	Description
`flag`	`False`	Enable supported threaded or joblib parallel work. False runs those tasks serially; this does not disable numerical-library internal threads.
`n_cores`	`2`	Positive worker count used when parallel.flag is true. Existing caller-supplied execution behavior is controlled by the pipeline. JSON aliases: `ncores`.

options.perf

Field	Default	Description
`max_perf`	`False`	True when larger raw algorithm performance is better; false for a cost such as error or run time. JSON aliases: `maxperf`.
`abs_perf`	`True`	True compares raw performance to an absolute epsilon threshold. False uses relative regret from the best algorithm on each instance. JSON aliases: `absperf`.
`epsilon`	`0.2`	Finite absolute threshold when abs_perf is true, otherwise a relative tolerance in [0, 1]. The threshold is inclusive in both directions. Raw observed performance must be nonnegative.
`beta_threshold`	`0.55`	Fraction in [0, 1]. An instance is beta-easy when strictly more than this fraction of the retained algorithms are good. JSON aliases: `betathreshold`.

options.auto

Field	Default	Description
`preproc`	`True`	Apply automatic feature bounding and Box-Cox/Z-score preprocessing. When false, bound.flag and norm.flag do not trigger those transforms.

options.bound

Field	Default	Description
`flag`	`True`	Clip feature outliers when auto.preproc is true, using prelim.iqr_multiplier. This does not clip raw algorithm performance.

options.norm

Field	Default	Description
`flag`	`True`	Apply fitted Box-Cox and Z-score transforms when auto.preproc is true. Exploration applies saved training parameters rather than refitting.

options.selvars

Field	Default	Description
`small_scale_flag`	`False`	Select a random fraction of training instances before feature selection. Use one subsetting mode at a time; fraction selection takes precedence over index-file and density modes. JSON aliases: `smallscaleflag`.
`small_scale`	`0.5`	Fraction in [0, 1] for small_scale_flag. Supply a float strictly between 0 and 1 for a viable random subset; the chosen rows must still permit the configured folds and projection. JSON aliases: `smallscale`.
`file_idx_flag`	`False`	Use file_idx for an explicit row subset when fractional selection is disabled. The file must exist and contain valid one-based row indices. JSON aliases: `fileidxflag`.
`file_idx`	`''`	CSV path containing one-based row indices, one per row. Relevant when file_idx_flag is true. JSON aliases: `fileidx`.
`feats`	`None`	Feature names to retain, or None for all. Names may include the feature_ prefix. An empty list selects all. If some names match, unknown names warn and are ignored; no matches raise an error.
`algos`	`None`	Algorithm names to retain, or None for all. Names may include the algo_ prefix. An empty list selects all. If some names match, unknown names warn and are ignored; no matches raise an error. Algorithms never good in training are pruned afterward.
`selvars_type`	`'Ftr&Good'`	Density-filter rule: Ftr, Ftr&AP, Ftr&Good or Ftr&AP&Good. These combine feature proximity with raw algorithm performance and/or good-performance labels. JSON aliases: `type`.
`min_distance`	`0.1`	Strictly positive feature-space distance for density filtering. Relevant when density_flag is true; supply a float. JSON aliases: `mindistance`.
`density_flag`	`False`	Enable greedy density filtering when fractional and index-file subsetting are disabled. SIFTED reapplies the density rule after selecting features. JSON aliases: `densityflag`.

options.sifted

Field	Default	Description
`flag`	`True`	Enable correlation screening, correlation clustering and genetic feature search. False retains the preprocessed feature columns.
`rho`	`0.1`	Absolute feature/performance correlation threshold in [0, 1] for screening.
`k`	`6`	Positive number of feature clusters. The stage can reduce it when fewer candidate features are available.
`n_trees`	`50`	Positive compatibility setting retained in configuration. Current PILOT/KNN fitness does not read it; it does not control a Random Forest. JSON aliases: `ntrees`.
`max_iter`	`1000`	Positive maximum iterations for correlation-distance k-means. JSON aliases: `maxiter`.
`replicates`	`100`	Positive number of k-means restarts.
`num_generations`	`100`	Positive maximum number of PyGAD generations. JSON aliases: `numgenerations`.
`num_parents_mating`	`2`	Positive number of mating parents, no greater than sol_per_pop. JSON aliases: `numparentsmating`.
`sol_per_pop`	`50`	Positive genetic-search population size. Must accommodate the mating, tournament and elitism settings. JSON aliases: `solperpop`.
`parent_selection_type`	`'tournament'`	PyGAD parent selection: sss, rws, sus, random, tournament, tournament_nsga2, nsga2 or rank. Names are case-insensitive. JSON aliases: `parentselectiontype`.
`k_tournament`	`4`	Positive tournament size, no greater than sol_per_pop. Used by tournament parent selection. JSON aliases: `ktournament`.
`keep_elitism`	`2`	Number of elite solutions retained per generation, from 0 through sol_per_pop. JSON aliases: `keepelitism`.
`crossover_type`	`'scattered'`	PyGAD crossover: single_point, two_points, uniform or scattered. JSON aliases: `crossovertype`.
`cross_over_probability`	`0.8`	Crossover probability in [0, 1]. The Python field includes an underscore between cross and over. JSON aliases: `crossoverprobability`.
`mutation_type`	`'random'`	PyGAD mutation: random, swap, scramble, inversion or adaptive. JSON aliases: `mutationtype`.
`mutation_probability`	`0.05`	Mutation probability in [0, 1]. Adaptive mutation requires two probabilities, as a list or tuple. JSON aliases: `mutationprobability`.
`stop_criteria`	`'saturate_5'`	Stopping rule saturate_N with positive integer N, or reach_VALUE with a finite numeric target. JSON aliases: `stopcriteria`.
`pval`	`0.05`	Correlation-screening significance threshold in [0, 1].
`dims`	`2`	Projection dimensions, 2 or 3, for direct SIFTED calls. The full pipeline uses pilot.dims for candidate projections.
`seed`	`None`	Nonnegative stage seed, or None to inherit general.seed. Controls clustering and genetic search.

options.pilot

Field	Default	Description
`x0`	`None`	Optional finite matrix of numerical starting vectors. It has d(2p+q) rows and one column per restart, for projection dimension d, retained feature count p and algorithm count q. Its columns determine the restart count.
`precalc_alpha`	`None`	Optional finite numerical solution column with d(2p+q) rows. It bypasses numerical search and takes precedence over x0 in the numerical branch. It does not override PLS or a viable analytic projection. JSON aliases: `precalcalpha`.
`analytic`	`False`	For method standard, request the analytic projection. A rank-deficient feature matrix falls back to numerical optimization. Ignored by method pls.
`n_tries`	`10`	Positive number of numerical restarts when neither x0 nor precalc_alpha supplies the solution. JSON aliases: `ntries`.
`adjust_rotation`	`False`	Apply a rigid canonical rotation in 2D so poorly solved instances face the target direction. Must be false for a 3D projection. JSON aliases: `adjustrotation`.
`cost_weight`	`1.0`	Strictly positive weight on the performance-reconstruction block of the standard projection objective. Not used by the PLS branch. JSON aliases: `alpha`, `costweight`.
`method`	`'standard'`	Projection method standard or pls. Standard uses analytic or multi-start numerical projection; pls uses SIMPLS with a persisted fitted feature mean.
`dims`	`2`	Projection dimensions, exactly 2 or 3. Also controls the full pipeline SIFTED candidate projection.
`view_groups`	`()`	Groups of zero-based retained-algorithm indices for optimized 3D viewpoints. An empty sequence requests one global viewpoint. Relevant only in 3D. JSON aliases: `viewgroups`.
`seed`	`None`	Nonnegative stage seed, or None to inherit general.seed. Controls numerical starts and viewpoint searches.

options.cloister

Field	Default	Description
`p_val`	`0.05`	Correlation significance threshold in [0, 1] for excluding contradictory corners. JSON aliases: `pval`.
`c_thres`	`0.7`	Absolute correlation cutoff in [0, 1] for the corner-contradiction test. JSON aliases: `corrthreshold`, `cthres`.
`max_features`	`20`	Positive upper feature-count bound for the corner-enumeration path. Above it the stage falls back to the observed-data hull. JSON aliases: `maxfeatures`.
`hull_dims`	`'all'`	all uses all projected coordinates; an integer of at least 2 selects a leading-coordinate hull. The dimensionality must be viable for the supplied projection. JSON aliases: `hulldims`.

options.pythia

Field	Default	Description
`cv_folds`	`5`	Number of stratified classifier folds, an integer of at least 2. Each class must have enough training examples for the requested validation. JSON aliases: `cvfolds`, `kfold`.
`is_poly_krnl`	`False`	Use a degree-three polynomial kernel for classifier svm when true, otherwise Gaussian/RBF. Ignored by the other classifier types. JSON aliases: `ispolykrnl`.
`use_weights`	`False`	Use abs(y - y_best) from the supplied preprocessed performance arrays as sample weights where supported. Zero weights become the smallest finite nonzero weight; nonfinite weights become the largest. All-zero weights fall back to uniform. Unsupported classifiers warn and fit without weights. JSON aliases: `useweights`.
`params`	`None`	Optional finite hyperparameter matrix in reporting/MATLAB units, one row per retained algorithm and one column per tuned parameter. It bypasses search even when tuning is sobol or bayes. Required for tuning none.
`classifier`	`'svm'`	Binary learner svm, knn, tree, nb, linear or ensemble. See the classifier/tuning guide for the estimator and parameter ranges.
`tuning`	`'sobol'`	Search strategy sobol, bayes or none. Sobol is the default. Bayesian search uses four initial points and plain expected improvement; its trajectory is not MATLAB EI-plus.
`n_tuning_iter`	`20`	Positive total candidate-evaluation budget for Sobol or Bayesian search, including Bayesian initial points. Ignored when params bypasses tuning. JSON aliases: `ntuningiter`.
`skip`	`False`	Skip classifier fitting. TRACE3 can use observed labels; legacy trace.use_sim must be false when this is true.

options.trace

Field	Default	Description
`use_sim`	`True`	For legacy TRACE, use PYTHIA-predicted good labels when true and observed good labels when false. Must be false with legacy TRACE when pythia.skip is true. TRACE3 has its own prediction/skip dispatch. JSON aliases: `usesim`.
`purity`	`0.55`	Target footprint purity in [0, 1]. The omitted default is 0.55 for legacy and 0.60 for trace3. A TRACE3 candidate can terminate without reaching this target; inspect the footprint results. JSON aliases: `pi`.
`method`	`'legacy'`	legacy uses the 2D DBSCAN/polygon algorithm; trace3 uses 2D/3D alpha-shape footprints. A 3D projection with legacy selected warns and uses TRACE3.
`contra`	`True`	For legacy TRACE, remove contradictions between best-algorithm footprints. The sequential trimming can be sensitive to small coordinate changes. Not used by TRACE3.
`min_instances`	`4`	Positive TRACE3 support threshold. A footprint requires more than this number of distinct supporting points, together with full-dimensional geometry. JSON aliases: `mininstances`.
`min_area_frac`	`0.01`	TRACE3 minimum measure as a fraction of the training-space area or volume, in [0, 1]. Smaller candidate footprints are discarded. JSON aliases: `minareafrac`.
`boundary_tolerance`	`0.0`	Finite nonnegative Euclidean distance in projected-coordinate units. Zero includes exact boundaries; a positive value also includes points within that distance of edges/faces, including hole boundaries. Saved with the fitted model and reused for exploration; geometry area/volume is unchanged. JSON aliases: `boundarytolerance`.

options.outputs

Field	Default	Description
`csv`	`True`	Caller output preference. Built-in file creation requires Model.save_to_csv; build does not automatically export files from this flag.
`web`	`False`	Caller output preference. Built-in web export requires Model.save_for_web; this flag alone does not write files.
`png`	`True`	Caller output preference. Built-in plot export requires Model.save_graphs; this flag alone does not write files.

options.general

Field	Default	Description
`verbose`	`True`	Print detailed stage progress when true. Stage-level messages remain available when false.
`seed`	`0`	Nonnegative random seed, or None for consumers that support nondeterministic execution. PILOT and SIFTED inherit it when their seed is None. Equal seeds do not guarantee identical results across numerical libraries.

options.prelim

Field	Default	Description
`iqr_multiplier`	`5.0`	Strictly positive multiplier for feature clipping at median plus or minus this value times the interquartile range. JSON aliases: `iqrmultiplier`.
`nan_threshold`	`0.2`	Missing-feature fraction in [0, 1] used during ingestion filtering. Columns at the threshold are removed. Training must be complete after filtering; exploration may omit algorithm outcomes. JSON aliases: `nanthreshold`.

JSON names

Python field names and explicit JSON aliases in the tables are accepted case-insensitively. Duplicate aliases for the same field are rejected. Unknown fields are rejected. The pilot.ISA3D input selects a 2D/3D projection when dims is absent; an explicit dims must agree with it. pythia.uselibsvm is accepted and ignored. It does not select a classifier or tuning method.

The normal Python configuration groups are shown above. MATLAB settings under general.parallel and general.ncores correspond to Python's parallel.flag and parallel.n_cores; they are not additional Python fields.