---
title: "How to Get Started"
output: 
  html_document:
    css: styles.css
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

IModMix allows the analysis and integration of multi-omics data types. If metabolomics abundance and proteomics or transcriptomics expression data from the same samples are available, they can be correlated (integrated) using iModMix. To ensure optimal performance and accurate results, please follow these guidelines to prepare and upload your data: 

## Uploading the Expression Matrices

- Omics matrix data should be in a tabular format (e.g., CSV, Excel).
- Each row represents a feature (e.g., gene, protein, metabolite), and each column represents a sample.
- The first column, labeled Feature_ID, should contain unique identifiers for each feature.

```{r data-example, echo=F, fig.align="center", fig.width=2, out.width="80%", fig.cap="Example of abundance/expression data that can be uploaded in the 'Metabolomics Abundance Data' and 'Proteomics/Genomics Expression Data' tabs."}
knitr::include_graphics(paste0(here::here(),"/inst/documentation/Expression.png"), error = FALSE)
```

## Uploading Metadata File

If available, metadata file is optional but recommended for optimal tool performance. 

Prepare a separate metadata file containing the experimental design and sample labels. It should have the following columns:

- Column 1 should be labeled Sample and each row should include unique sample IDs that match the sample IDs in your abundance/expression matrix files. Ensure that sample IDs are consistent across all datasets.This column enables linking omics data through samples.
- Column 2 can be labeled by a description for grouping samples (e.g., ‘treatment’ and ‘control’). Additional columns can be included for more grouping conditions. At least one grouping column is required to perform PCA, box plots, etc.

```{r, echo=F, fig.align="center", fig.width=2, out.width="20%", fig.cap="Example metadata data that can be uploaded in the 'Metadata' tab."}
knitr::include_graphics(paste0(here::here(),"/inst/documentation/Metadata.png"), error = FALSE)
```

## Uploading Annotation Files

If available, annotation files are optional but recommended for optimal tool performance.

Metabolomics Annotation data should have the following labeled columns:

- Feature_ID: The sample IDs used in your abundance matrix file.
- Metabolites: Include the corresponding metabolite name.
- KEGG: Include corresponding KEGG IDs.

Proteomics or Genomics Data: It should have the following columns:

- Feature_ID: The sample IDs used in your expression matrix file.
- Symbol: Include corresponding Symbols to enable enrichment analysis.

```{r, echo=F, fig.align="center", fig.width=2, out.width="90%", fig.cap="Example annotation data that can be uploaded in the 'Metabolomics Annotation Data' and 'Proteomics/Genomics Annotation data' tabs."}
knitr::include_graphics(paste0(here::here(),"/inst/documentation/Annotation.png"), error = FALSE)
```

## Preparing Data for Use with Our Tool

To ensure your data is ready for analysis, please follow these guidelines:

- Data Types: Metabolomics, proteomics, or genomics data should saved and uploaded as separate files.
- Identifiers: While KEGG IDs for metabolites and gene symbols for genes are optional, they are recommended for optimal performance. 
- Missing Values: IModMix handles missing values with knn Imputation if necessary.
- Unique Identifiers: Ensure that each Feature_ID is unique. Use make.names() for conflicts, and avoid duplicates to prevent errors.
- Web-based Tools for ID Conversion: If you need to convert identifiers, consider using web-based tools like the Uniprot batch conversion tool for genes/proteins or DAVID for genes.
- Ensure that the sample IDs in your metadata file match those in your omics data files. If there are discrepancies, an error will occur. Make sure all samples are labeled correctly with no extra or missing samples.

## Example data

We provide ten multi-omic datasets (transcriptomics and metabolomics) to further illustrate iModMix’s capabilities. These datasets (Benedetti et al. 2023) have been formatted to meet iModMix specifications, with variable columns labeled as “Feature_ID” and sample columns labeled as “Samples”.

These datasets are readily accessible for download on Zenodo:  
[https://doi.org/10.5281/zenodo.13988161](https://doi.org/10.5281/zenodo.13988161)

Furthermore, two case studies are available to help you get started with iModMix. You can use this data to run the application and explore its features.

**Case Study 1.** Clear cell renal cell carcinoma (ccRCC, RC20) Dataset with Identified Metabolites
We used 76 clear cell renal cell carcinoma (ccRCC) samples, 24 normal and 52 tumor (Golkaram et al. 2022; Tang et al. 2023; Benedetti et al. 2023) as a case study. 

- Data 1: It contained 904 identified metabolites from untargeted metabolomics. 
- Data 2: It contained 23001 genes from RNA-seq

Applying iModMix identified 751 gene modules and 34 metabolite modules. Differential expression analysis of the modules through t-test confirmed changes in metabolite abundance between highlighting reduced levels of gamma-glutamyltyrosine (module ME#BA3241, P-value: 0.0003), creatinine/C00791 (module ME#C06162 P-value: 4.2681E-15), xanthosine/C01762 (module ME#66628D P-value: 0.0015), docosahexaenoate (DHA; 22:6n3)/C06429 (module ME#904A67 P-value: 4.6906E-12), and 1-methyladenosine/C02494 (module ME#E1C62F P-value: 8.1847E-14) in tumors compared to normal tissue. Conversely, metabolites with increased abundance in tumors compared to normal tissues included proline/C00148, glutamine/C00064 (module ME#6C856F, P-value: 0.006), maltose/C00208 and 1-methylnicotinamide/C02918 (module ME#904A67  P-value: 4.6906E-12). 

**Case Study 2.** Lung Adenocarcinoma (LUAD) Dataset with Unidentified Metabolites
Matched proteomics and metabolomics dataset was generated using two mouse models for lung adenocarcinoma (LUAD) (10 wild type, 10 knockout).

- Data 1:  It contained 7353 metabolomics features (identified and unidentified) 
- Data 2: It contained 7928 protein groups. 

Applying iModMix generated 412 gene modules, and 287 metabolite modules. Strong correlations were observed between these modules, with correlations as high as 0.93. The correlations observed between variables in the 2 and 3 correlated pairs are notably high, with numerous correlations between proteins and both identified and unidentified metabolites exceeding 0.9. These strong correlations offer valuable insights into the unidentified metabolites, providing crucial information about their potential relationships and helping to elucidate their behavior.




  
