> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmosid.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Build ML Classification and Regression models on Cosmos-Hub 2.0
> Build Regression or Classification ML models with Cosmos-Hub 2.0
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?"
Predicts a **numerical value**: *how much?*
For example, a metabolite concentration, an inflammation marker, a clinical score, or the age of a patient.
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](DAP_docs/preprocessing-overview) 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 studies**
For 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
| 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](/analysis/rarefaction).
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](/analysis/rarefaction). 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](/analysis/rarefaction).
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](/analysis/rarefaction). 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](/analysis/rarefaction).
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](/analysis/rarefaction). 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](/analysis/rarefaction).
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](/analysis/rarefaction). 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](/analysis/rarefaction).
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](/analysis/rarefaction). 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](/analysis/rarefaction). 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](/analysis/rarefaction).
|
| 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
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.
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** · `None`
**Suggested** · 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.
Whether samples with a missing target value are excluded.
* \*\*Options \*\* `TRUE` or `FALSE`
* **Default** · `TRUE`
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 query
**Default** · `None`
**Suggested** · 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.
Whether samples with missing covariate values are excluded. Available only when one or more covariates are selected.
**Options** · `TRUE` or `FALSE`
**Default** · `TRUE`
**Suggested** · `TRUE` when covariate values are required for Covariates adjustment.
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 `30`
**Default** · `10`
Whether the model uses features as relative abundance or presence/absence. This defines the biological signal the model learns from.
**Options** · `abundance`, `presence`
**Default** · `abundance`
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`