qbiocode.apps.sage.sage module

Summary

Classes:

QuantumSage

Sage class that will run an ML model over the input data frame which would be some set of defined data characeristics and performance metrics associated to the dataset the method use.

Functions:

calculate_SLGH
main	Command-line interface for QSage (Quantum Sage).

Reference

class QuantumSage(data_input)

Bases: object

Sage class that will run an ML model over the input data frame which would be some set of defined data characeristics and performance metrics associated to the dataset the method use. Right now it is focused on learning from just the data characteristics but it can eventual also include the model parameters as part of the input

__init__(data_input)

This function initializes the Sage with the input data frame that contains the data characteristics and performance metrics

predict(input_data, metric='f1_score')

Rank every model by its predicted score on one dataset.

Pass the dataset-complexity columns named by _columns_data_features – the SLGH feature that training derives is recomputed here, so a value passed in for it is ignored rather than trusted. Rows are sorted by metric * r2 descending: a model whose surrogate fits poorly cannot reach the top on a confident-looking point prediction alone, so read the r2 column alongside the score.

An unknown metric, a missing feature column, an untrained sage, or an input that is not exactly one row each raise – earlier versions returned None for an unknown metric and ranked on the first row of a multi-row input.

Parameters:

• input_data (pd.DataFrame) – Exactly one row, carrying at least the columns in _columns_data_features. Extra columns are ignored.

• metric (str) – One of the trained metrics (f1_score, auc, accuracy).

Returns:

One row per model, with columns

model, <metric>, r2 and <metric>*r2, ranked by the last of those.

Return type:

predictions_df (pd.DataFrame)

train_sub_sages(test_size=0.2, sage_type='random_forest', n_iter=None, cv=5)

Train sub-sage predictors for each ML model and performance metric.

This function trains regression models (Sage) that learn to predict model performance based on data complexity features. A separate sub-sage is trained for each combination of ML model and performance metric.

Parameters:

• test_size (float, optional) – Proportion of data to use for testing (0.0 to 1.0). Default is 0.2.

• sage_type (str, optional) –

  Type of regressor to use as Sage. Must be one of:

  • ’random_forest’: Random Forest with hyperparameter tuning (default)

  • ’mlp’: Multi-Layer Perceptron with grid search

  • ’xgboost_optuna’: XGBoost with Optuna optimization (state-of-the-art)

  Only ONE sage type can be selected per training run.

• n_iter (int, optional) – For Random Forest: number of hyperparameter search iterations (default: 50). For MLP: maximum number of training epochs (default: 1000). For XGBoost-Optuna: number of Optuna trials (default: 100). If None, uses the default for the selected sage_type.

• cv (int, optional) – Number of cross-validation folds for hyperparameter evaluation. Default is 5. Used by all sage types.

Returns:

Results are stored in the internal _results_subsages dictionary with structure:

{
    'metric1': {
        'model1': {
            'fit_model': <trained model>,
            'preds': <predictions on test set>,
            'y_test': <true values>,
            'params': <model parameters>,
            'mae': <mean absolute error>,
            'mse': <mean squared error>,
            'rmse': <root mean squared error>,
            'r2': <R² score>
        },
        ...
    },
    ...
}

Return type:

None

Raises:

• ValueError – If sage_type is not one of the valid types.

• ImportError – If sage_type is ‘xgboost_optuna’ but XGBoost or Optuna is not installed.

Notes

The function iterates over all available metrics and models, training a separate predictor for each combination. Progress is printed during training.

Only one sage type can be used per training run. If you want to compare different sage types, you need to train them separately and compare results.

Recommended Sage Type:

For best performance on continuous value prediction, use ‘xgboost_optuna’, which combines the power of gradient boosting with advanced Bayesian hyperparameter optimization.

Examples

Train with Random Forest (default):

>>> sage.train_sub_sages(test_size=0.2, sage_type='random_forest')

Train with MLP:

>>> sage.train_sub_sages(test_size=0.2, sage_type='mlp')

Train with XGBoost-Optuna (state-of-the-art):

>>> sage.train_sub_sages(test_size=0.2, sage_type='xgboost_optuna', n_iter=200)

Train with custom hyperparameter search:

>>> sage.train_sub_sages(sage_type='random_forest', n_iter=100, cv=10)

See also

_sage_random_forest

Random Forest Sage implementation

_sage_mlp

MLP Sage implementation

_sage_xgboost_optuna

XGBoost with Optuna Sage implementation (state-of-the-art)

predict

Make predictions using trained Sages

plot_results(figsize=(6, 4), saveFile='', show=None)

This function plots the results of the sub-sages trained on the input data. It will create a bar plot for each metric showing the performance of each model, and a scatter plot of the predictions vs. true values. The bar plot will show the mean absolute error (mae), mean squared error (mse), root mean squared error (rmse), and R2 score (r2) for each model. The scatter plot will show the predictions vs. true values for each model. If saveFile is provided, the plots will be saved to that file. Otherwise, the plots will be shown. It is designed to be used after the train_sub_sages function has been called, and the sub-sages have been trained.

Parameters:

• figsize (tuple) – Size of each figure.

• saveFile (str) – Base file name for the plots. One bar plot and one scatter plot are written per metric, with _<metric>_barplot and _<metric>_scatterplot inserted before the extension. If empty, nothing is written. Default is ‘’.

• show (bool | None) – Whether to call plt.show(). None (the default) means “show only when not saving”, which is what this docstring has always described; plt.show() used to be called unconditionally, so a run that saved to disk also blocked on a window under a GUI backend. It is ignored under a non-interactive backend either way.

Returns:

the figures, in the order drawn. All are already closed but remain savable.

Return type:

list[matplotlib.figure.Figure]

set_seed(seed=42)

calculate_SLGH(df, train_pct=0.7)

main()

Command-line interface for QSage (Quantum Sage).

This CLI allows users to train QSage models from the command line using CSV data files. QSage learns relationships between dataset complexity measures and model performance, enabling prediction of model performance on new datasets.

Usage:

qsage –input data.csv –output results/ [options]

The input CSV should contain:

• Dataset complexity features (# Features, # Samples, Intrinsic_Dimension, etc.)

• Performance metrics (accuracy, f1_score, auc)

• Metadata (Dataset, embeddings, model, etc.)

QProfiler Integration:

QSage is designed to work directly with QProfiler output. Simply use the compiled_results.csv file generated by QProfiler as input:

# Step 1: Run QProfiler qprofiler –config-name=config.yaml

# Step 2: Train QSage with QProfiler output qsage –input compiled_results.csv –output sage_results/

Examples

# Basic usage with QProfiler output qsage –input compiled_results.csv –output sage_results/

# With custom cross-validation and hyperparameter search qsage –input compiled_results.csv –output results/ –cv 10 –n-iter 100

# Train Random Forest sub-sages qsage –input data.csv –output results/ –model-type rf –seed 42

# Train MLP sub-sages qsage –input data.csv –output results/ –model-type mlp –n-iter 2000