Machine learning models, whether regression or classification, predict unknown information about a sample from data we can collect and observe about it. The foundation of ML is that variables of interest (e.g. health status, age, treatment efficacy) leave a trace in the known data (e.g. the microbial profile of a stool sample). Building an ML model means using source data to discover whether those patterns are present and, if so, using them to infer the outcome of a target variable on new samples. ML models are also a valuable way to identify which features are linked to the outcome variable, which helps generate biological hypotheses and guide further research.

Choose between ML Regression or Classification

From the module panel, choose either the ML Regression or the ML Classification module, depending on the type of output your model will predict. The question to ask is: “Is the outcome I want to predict categorical or numerical?”

ML Regression

Predicts a numerical value: how much?For example, a metabolite concentration, an inflammation marker, a clinical score, or the age of a patient.

ML Classification

Predicts a category: which group?For example, patient vs healthy control, responder vs non-responder, or one of several body sites.

Choose what your model should predict

Select the variable your model should predict through the Target Variable parameter in the Analysis section. It lists the metadata columns available for your dataset: categorical for classification, numerical for regression

Training an ML model

Building a model requires a set of samples for which both parts are available: the Input data (microbial, metabolomic, or functional profiles) and the target Variable we want to predict (a label for classification, or a value for regression). The phase where complete data is used to ‘teach’ a model what are the data patterns that allow to link input data to make a prediction of a target variable is called model training. During model training, the model learns the input-to-output relationship between your data and the output. For this reason, training requires a dataset where, for each sample, both the data used for prediction and the outcome to predict are available (Training dataset).

Model performance is bounded by the data, not only by the algorithm. It depends on whether a real relationship between input and output exists, how strong that relationship is, how many samples are available, and the quality of the input data. Good input data starts before training, at study design, sampling, and sequencing.

Pre-processing the Data Table

As in any other analysis module on Cosmos-Hub 2.0, the input to the ML model is the Cohort Data Table that was assembled at creation of the Analysis Project through the Query Builder. Pre-processing parameters directly affect the microbial features table used for the analyses modules. In ML, particular care is needed when choosing pre-processing parameters, since this will decide many aspects of the input table used for training.

Overfitting, noise, and the imbalance between the number of features and samples strongly affect how well an ML model trains and generalizes, and pre-processing is where you most influence them. Filtering too aggressively removes real low-abundance or condition-specific signal, so reduce features and samples only as far as the noise and overfitting warrant.

Pre-processing impacts mainly on 4 aspects of the Data Table that is used for training and CV-validation: feature values of the Data Table , the number of features, the number of samples, and whether sample profiles are adjusted for sequencing depth through rarefaction. Each parameter acts on them as follows:

Parameter	Affects	Effect on the training data
Analysis Metric	Feature values	Expresses each feature as raw `counts` or `relative abundance`. Relative abundance rescales every sample to the same total, changing the values so the model compares composition rather than sequencing depth.
Taxonomic Rank	Number of features	A coarser rank (`genus`) merges related taxa into fewer, less sparse features, lowering overfitting risk at the cost of resolution.
Data Table Preprocessing Method (`Filter`)	Number of samples, and features	Removes samples below a read-depth cutoff, improving data quality but reducing sample size. It also drops any feature found only in the removed samples.
Data Table Preprocessing Method (`Rarefaction`)	Sequencing depth, and features	Subsamples all samples to a common depth, removing depth as a signal the model could exploit, at the cost of discarding reads and dropping some low-abundance features.
Feature Relative Abundance Threshold	Number of features	A higher value counts fewer low-abundance features as detected, reducing noise but risking loss of real low-abundance signal.
Feature Prevalence Threshold	Number of features	A higher value discards features present in few samples, reducing dimensionality but risking loss of rare, condition-specific signal.

Choose the ML algorithm

The ML algorithm is the method the model uses to find the patterns that link the input data to the target. Different algorithms learn different kinds of relationships between microbiome features and the target variable. Choose it from the ML Algorithm parameter dropdown.

Algorithm	Task	Best for
`Random Forest`	Regression · Classification	A reliable general-purpose default
`Support Vector Machine`	Regression · Classification	Flexible, non-linear relationships
`Linear Regression`	Regression	Simplicity and interpretability
`Gradient Boosting Regressor`	Regression	Strong performance on complex, non-linear patterns
`ElasticNet Regression`	Regression	Interpretability with feature selection (many correlated features)
`Logistic Regression`	Classification	Simplicity and interpretability
`ElasticNet Logistic Regression`	Classification	Interpretability with feature selection
`Gradient Boosting`	Classification	Maximum prediction accuracy

More flexible algorithms, like Support Vector Machines, can capture more complex patterns but at cost of harder interpretability; simpler ones, like linear and logistic regression, are less powerful but output offer easier to interpret, which makes them ideal to understand which features and how much are associated with the target variable.

Random Forest is a good default for exploratory work because it handles non-linear patterns and usually works well without extensive tuning. For biological interpretation, it can be useful to compare it with a simpler model such as linear or logistic regression.

Correct for confounding variables (Covariates)

A confounding variable, or confounder, is a factor associated with both the input and the target, which can create or mask an apparent link between them. The microbiome is shaped by many such factors, including age, sex, BMI, diet, and health conditions. When one of these factors differs systematically between your groups, the model can pick up its effect and mistake it for a microbiome-target relationship. Covariates are the factors you adjust for to prevent this: variables you expect to influence the microbiome but that are not the biological signal you want to study. Use the Covariates parameter dropdown in the Analysis section to select the categorical or numerical metadata variables to correct for.

Confounders in microbiome studiesFor example, if you train a model to predict a disease from the gut microbiome but the patients are older on average than the controls, the model may partly learn age-related shifts in the microbiome and appear to predict the disease when it is in part reading age. Adjusting for age (and other host factors) as covariates or through matching has been shown to markedly reduce spurious microbiome–disease signals.Vujkovic-Cvijin I et al. Host variables confound gut microbiota studies of human disease. Nature. 2020;587:448–454.

Covariate correction is applied to the feature table before the model is trained. For each feature, a linear model estimates the portion of that feature’s variation explained by the selected covariates. That portion is subtracted, and the residual values, the variation not explained by the covariates, are used as the model input. Use covariates when they may influence the microbiome and could otherwise obscure the relationship between microbial features and the target. Correcting for them lets the model focus on the microbial signal related to the target variable you chose rather than these background factors. This can help reduce the influence of known confounders, but it should be interpreted carefully. Covariate correction only adjusts for the variables you select and for the type of relationship modeled. It does not prove that the remaining microbial signal is causal or fully independent of those covariates.

Do not include variables that may lie on the biological pathway between the microbiome and the target. Adjusting for those variables can remove part of the signal you are trying to study. For example, if the microbiome affects the target by driving inflammation (microbiome to inflammation to outcome), adjusting for an inflammation marker would remove the part of the microbial signal that acts through it.

Evaluate and optimize the model with Cross-Validation (K-fold)

Training a model raises two problems:

Overfitting. The model may fit patterns specific to the training data, such as batch effects or noise, rather than real biology. It then performs well on the samples it was trained on but poorly on new ones.
Hyperparameter selection. ML algorithms have hyperparameters, settings that are not learned from the data and must be chosen.

Cross-validation addresses both. It estimates performance on samples the model did not train on, and provides the held-out performance used to choose hyperparameters, so tuning is not judged on the same data used to fit the model. Number of K-folds controls cross-validation. The dataset is split into K parts, called folds. The model is trained on most folds and tested on the held-out fold. This is repeated until each fold has been used as the test set once. For example, with 5 folds, the model trains on four-fifths of the data and tests on the remaining fifth, repeating this process five times. For most microbiome datasets, 5 folds is a good default. Use more folds only when the dataset is large enough to support stable splits. For classification, be especially careful when some classes are small: each fold needs enough samples from each class to make the evaluation meaningful.

Run the model and read the results

Once the parameters are set, click Apply and Run. The model will be trained on your data and then display the results of the module described in the next two sections. The next sections cover how to interpret the output of the ML Classification and ML Regression modules, evaluate the performances of the ML model and explore which are the microbial features (e.g: taxa, functions) that appear to be behind the biological patterns.

Recommended parameters

Pre-processing

Kepler - Host-Agnostic Taxonomic Profiling (WGS)
CHAMP - Human Taxonomic Profiling (WGS)
Short-read 16S - Taxonomic
16S LR Amplicon profiling - Taxonomic
Host-Agnostic Functional
CHAMP Functional (GMM, GBM, KEGG)
AMR/VF - Functional

Parameter	Recommended value
Taxonomic Rank	`species`
Data Table Pre-processing Method	`Raw` if samples have comparable read depths. `Filter` if a few samples have notably lower read depth than the rest of the cohort. `Rarefaction` to standardize the whole cohort to a common read depth, using the optimal depth from the Rarefaction module. Uneven depth can make the model learn sequencing effort rather than biology, so standardize depth across groups before training.
Read Depth	`default` with `Raw` or `Filter`. With `Rarefaction`, use the optimal depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size.
Seed	`default` (only when method is `Rarefaction`)
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering helps removing sparse taxa that mostly add noise and increase overfitting risk.

Parameter	Recommended value
Taxonomic Rank	`species`
Data Table Pre-processing Method	`Raw` if samples have comparable read depths. `Filter` if a few samples have notably lower read depth than the rest of the cohort. `Rarefaction` to standardize the whole cohort to a common read depth, using the optimal depth from the Rarefaction module. Uneven depth can make the model learn sequencing effort rather than biology, so standardize depth across groups before training.
Read Depth	`default` with `Raw` or `Filter`. With `Rarefaction`, use the optimal depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size.
Seed	`default` (only when method is `Rarefaction`)
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering helps removing sparse taxa that mostly add noise and increase overfitting risk.

Parameter	Recommended value
Taxonomic Rank	`genus`
Data Table Pre-processing Method	`Raw` if samples have comparable read depths. `Filter` if a few samples have notably lower read depth than the rest of the cohort. `Rarefaction` to standardize the whole cohort to a common read depth, using the optimal depth from the Rarefaction module. Uneven depth can confound model training; standardize depth across groups when testing subtle signals.
Read Depth	`default` with `Raw` or `Filter`. With `Rarefaction`, use the optimal depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size.
Seed	`default` (only when method is `Rarefaction`)
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering helps removing sparse taxa that mostly add noise and increase overfitting risk.

Parameter	Recommended value
Taxonomic Rank	`species`
Data Table Pre-processing Method	`Raw` if samples have comparable read depths. `Filter` if a few samples have notably lower read depth than the rest of the cohort. `Rarefaction` to standardize the whole cohort to a common read depth, using the optimal depth from the Rarefaction module. Uneven depth can confound model training; long-read runs are usually shallower, so check group depth before choosing `Raw`.
Read Depth	With `Rarefaction`: `100,000`, or the depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size. With `Filter`: `20,000`, adjusted to remove only the samples with notably lower depth.
Seed	`default` (only when method is `Rarefaction`)
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering helps removing sparse taxa that mostly add noise and increase overfitting risk.

Parameter	Recommended value
Data Table Pre-processing Method	`Raw` if samples have comparable read depths. `Filter` if a few samples have notably lower read depth than the rest of the cohort. `Rarefaction` to standardize the whole cohort to a common read depth, using the optimal depth from the Rarefaction module. Uneven depth can make functional models track sequencing effort rather than biology; standardize depth for fair comparison.
Read Depth	`default` with `Raw` or `Filter`. With `Rarefaction`, use the optimal depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size.
Seed	`default` (only when method is `Rarefaction`)
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering removes very low-prevalence functions that mostly add noise and increase model complexity.

Parameter	Recommended value
Data Table Pre-processing Method	`Raw`
Read Depth	`default` with `Raw` or `Filter`. With `Rarefaction`, use the optimal depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size.
Seed	`default` (only when method is `Rarefaction`)
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0` GMM, GBM, and KEGG Orthologues and Modules are already aggregated

Parameter	Recommended value
Data Table Pre-processing Method	`Raw`
Read Depth	`default` with `Raw` or `Filter`. With `Rarefaction`, use the optimal depth from the Rarefaction module.
Seed	`default` (only when method is `Rarefaction`)
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering removes sparse resistance or virulence genes that mostly add noise and make the model harder to interpret.

Model settings

Parameter	Recommended value
ML Algorithm	`Random Forest` as a flexible default `Linear regression` for interpretability
Target Variable	The variable outcome you want your model to predict.
Feature Metric	`abundance` when the ML model should learn on the feature `presence` when ML model should learn on feature presence-absence
Covariates	Known confounders with a plausible linear effect (for example age, BMI, sex)
Drop samples with missing target	Enabled
Drop samples with missing covariates	Enabled
Number of K-folds	`5` (use `10` for large datasets, around 1000 or more samples)
Top Features (N)	`10` (increase for broader exploration)

Parameter reference

ML Algorithm

The machine-learning algorithm used to predict the target from microbiome features.Options ·

ML Regression: Random Forest, Linear Regression, ElasticNet Regression, Gradient Boosting Regressor, Support Vector Machine Regressor
ML Classification: Random Forest, Logistic Regression, ElasticNet Logistic Regression, Gradient Boosting, Support Vector Machine.

Default · Random Forest

Different algorithms capture different relationships: some are easier to interpret, others predict more accurately. Random Forest is a strong general-purpose default.

Target Variable

The variable the ML model should predict: the biological or clinical measurement you want to estimate from microbiome data.Options · One metadata column from those attached to the samples in the cohort. The required type (numerical or categorical) depends on the module:

ML Regression: numerical metadata (for example metabolite_concentration, age, bmi).
ML Classification: categorical metadata, with two or more classes (for example sex, health_status, disease_severity, sample_source).

Default · NoneSuggested · The variable behind your scientific question, the one you want to predict from the microbiome. For exploration or hypothesis generation, testing how well the microbiome predicts a given target is a good way to find out whether that variable could drive differences in microbiome.

Drop samples with missing target

Whether samples with a missing target value are excluded.

**Options ** TRUE or FALSE
Default · TRUE

Covariates

Numeric or binary metadata variables to correct for potential confounding before training.Options · Numeric or binary metadata columns from the metadata table associated with the queryDefault · NoneSuggested · Variables that may confound the relationship with the target and have a plausible linear effect on features (for example age, BMI, sex).

Example: If age is associated with both composition and the target, including it as a covariate helps separate microbiome-related signal from age-related effects.

Drop samples with missing covariates

Whether samples with missing covariate values are excluded. Available only when one or more covariates are selected.Options · TRUE or FALSEDefault · TRUESuggested · TRUE when covariate values are required for Covariates adjustment.

Top Features (N)

The number of top-ranked features shown from the best-performing model: the taxa or functions that contributed most to predicting the target.Options · Integer from 1 to 30Default · 10

Feature Metric

Whether the model uses features as relative abundance or presence/absence. This defines the biological signal the model learns from.Options · abundance, presenceDefault · abundance

Number of K-folds

The number of folds in stratified k-fold cross-validation. The data is split into this many parts (each preserving the target’s class distribution), and each is used once as the test set.

Options: Integer from 2 to 20
Default: 5

Getting Started

Import Data on Cosmos-Hub 2.0

Building Cohorts

Analysis Projects

Build ML Classification and Regression models on Cosmos-Hub 2.0

Choose between ML Regression or Classification

ML Regression

ML Classification

Choose what your model should predict

Training an ML model

Pre-processing the Data Table

Choose the ML algorithm

Correct for confounding variables (Covariates)

Evaluate and optimize the model with Cross-Validation (K-fold)

Run the model and read the results

Recommended parameters

Pre-processing

Model settings

Parameter reference

​Choose between ML Regression or Classification

ML Regression

ML Classification

​Choose what your model should predict

​Training an ML model

​Pre-processing the Data Table

​Choose the ML algorithm

​Correct for confounding variables (Covariates)

​Evaluate and optimize the model with Cross-Validation (K-fold)

​Run the model and read the results

​Recommended parameters

​Pre-processing

​Model settings

​Parameter reference

Choose between ML Regression or Classification

Choose what your model should predict

Training an ML model

Pre-processing the Data Table

Choose the ML algorithm

Correct for confounding variables (Covariates)

Evaluate and optimize the model with Cross-Validation (K-fold)

Run the model and read the results

Recommended parameters

Pre-processing

Model settings

Parameter reference