{"id":16159677,"url":"https://github.com/yufree/mzrtsim","last_synced_at":"2026-02-18T16:01:28.668Z","repository":{"id":70179118,"uuid":"129319854","full_name":"yufree/mzrtsim","owner":"yufree","description":"Raw data and peaks list simulation for GC/LC-MS based data","archived":false,"fork":false,"pushed_at":"2025-08-17T22:31:58.000Z","size":60880,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-25T05:01:02.805Z","etag":null,"topics":["metabolomics","mzml","simulation"],"latest_commit_sha":null,"homepage":"https://yufree.github.io/mzrtsim/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yufree.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-04-12T22:56:39.000Z","updated_at":"2025-05-22T15:06:24.000Z","dependencies_parsed_at":"2024-10-27T19:15:26.276Z","dependency_job_id":"934d85c5-bb1f-4bf7-8e38-34667c6dedff","html_url":"https://github.com/yufree/mzrtsim","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/yufree/mzrtsim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yufree%2Fmzrtsim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yufree%2Fmzrtsim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yufree%2Fmzrtsim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yufree%2Fmzrtsim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yufree","download_url":"https://codeload.github.com/yufree/mzrtsim/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yufree%2Fmzrtsim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29585441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T13:56:48.962Z","status":"ssl_error","status_checked_at":"2026-02-18T13:54:34.145Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["metabolomics","mzml","simulation"],"created_at":"2024-10-10T01:59:17.437Z","updated_at":"2026-02-18T16:01:28.651Z","avatar_url":"https://github.com/yufree.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# mzrtsim\n\n\u003c!-- badges: start --\u003e\n\n[![R-CMD-check](https://github.com/yufree/mzrtsim/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/yufree/mzrtsim/actions/workflows/R-CMD-check.yaml)\n[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)\n\u003c!-- badges: end --\u003e\n\nThe goal of mzrtsim is to make raw data and features table simulation for LC/GC-MS based  data\n\n## Citation\n\nYu, M.; Philip, V. Mzrtsim: Raw Data Simulation for Reproducible Gas/Liquid Chromatography–Mass Spectrometry-Based Nontargeted Metabolomics Data Analysis. Anal. Chem. 2025, 97 (32), 17309–17314. https://doi.org/10.1021/acs.analchem.5c01213.\n\n## Installation\n\nYou can install the development version from [GitHub](https://github.com/) with:\n\n```{r eval=FALSE}\n# install.packages(\"remotes\")\nremotes::install_github(\"yufree/mzrtsim\")\n```\n\n## Raw Data simulation\n\nMS1 full scan data has been proved more complex than theoretical prediction. Recently study showed that soft ionization will also contain [fragment ions](https://www.nature.com/articles/s41596-023-00803-0) for structure identification and contain lots of [redundant peaks](https://pubs.acs.org/doi/10.1021/acs.analchem.7b02380). As shown in the following figure, MS1 full scan data could contain different types of ions from the same compound (red). Some peaks we could figure out the sources while some peaks might be hard to interpret. In this case, mzrtsim package will use experimental data instead of predicted peaks from the compound formula to show the complexity of MS1 spectra.\n\n![demo](https://yufree.github.io/presentation/figure/peakcom.png)\n\nYou could use `simmzml` to generate one mzML file.\n\n```{r eval=FALSE}\nlibrary(mzrtsim)\ndata(\"monams1\")\nsimmzml(db=monams1, name = 'test')\n```\n\nYou will find `test.mzML` and corresponding `test.csv` with m/z, retention time and compound name of the peaks. Here the `monams1` and `monahrms1` is from the MS1 data of MassBank of North America (MoNA) and could be downloaded from their [website](https://mona.fiehnlab.ucdavis.edu/downloads). You could also use `hmdbcms` to simulate EI source data extracted from [HMDB](https://hmdb.ca/downloads). Here we only use the MS1 full scan data for simulation.\n\n### Data extraction\n\nFor HMDB, you need to download their \"GC-MS Spectra Files (XML) - Experimental\" data [here](https://hmdb.ca/downloads). Then you need the following R code to construct the database for this package.\n\n```{r eval=FALSE}\nxmlpath \u003c- list.files('hmdb_experimental_cms_spectra/',full.names = T,recursive = T)\nlibrary(xml2)\ngetcms \u003c- function(i){\n  tree = xml2::read_xml(xmlpath[i])\n  accession = xml_text(xml2::xml_find_all(tree,'/c-ms/database-id'))\n  rti = as.numeric(xml_text(xml2::xml_find_all(tree,'/c-ms/retention-index')))\n  prec = as.numeric(xml_text(xml2::xml_find_all(tree,'/c-ms/derivative-exact-mass')))\n  formula = xml_text(xml2::xml_find_all(tree,'/c-ms/derivative-formula'))\n  ins = xml_text(xml2::xml_find_all(tree,'/c-ms/notes'))\n  ins2 = xml_text(xml2::xml_find_all(tree,'/c-ms/instrument-type'))\n  mode = xml_text(xml2::xml_find_all(tree,'/c-ms/ionization-mode'))\n  idms = xml_text(xml2::xml_find_all(tree,'/c-ms/id'))\n  instr = xml_text(xml2::xml_find_all(tree,'instrument-type'))\n  masscharge = as.numeric(xml_text(xml2::xml_find_all(tree,'/c-ms/c-ms-peaks/c-ms-peak/mass-charge')))\n  intensity =  as.numeric(xml_text(xml2::xml_find_all(tree,'/c-ms/c-ms-peaks/c-ms-peak/intensity')))\n  idx \u003c- intensity!=0\n  mz \u003c- list(name=accession, idms=idms, ionmode=mode, prec = prec, formula = formula, np = length(masscharge[idx]), rti = rti, instr = ins2, msm = ins, spectra=cbind.data.frame(mz=masscharge[idx],ins=intensity[idx]))\n  return(mz)\n}\n\nlibrary(parallel)\nhmdbcms \u003c- mcMap(getcms,1:length(xmlpath), mc.cores = 4)\nsaveRDS(hmdbcms,'hmdbcms.RDS')\n```\n\nFor MoNA, you can download the \"LC-MS Spectra\" data in format of \"msp\" from this [website](https://mona.fiehnlab.ucdavis.edu/downloads). Then we need to filter the MS1 data to generate database for LC-MS and subset data base for LC-HRMS.\n\n```{r eval=FALSE}\n# you need to install enviGCMS package by 'install.packages(\"enviGCMS\")'.\nmsp \u003c- enviGCMS::getMSP('MoNA-export-LC-MS_Spectra.msp')\nidx \u003c- sapply(msp, function(x) grepl('MS1',x$msm))\nidx1 \u003c- sapply(idx, function(x) length(x)\u003e0)\nmonams1 \u003c- msp[idx1]\nidx2 \u003c- sapply(monams1, function(x) grepl('MS1',x$msm))\nmonams1 \u003c- monams1[idx2]\n\nidx3 \u003c- sapply(monams1, function(x) x$instr )\nidx4 \u003c- sapply(idx3, function(x) length(x)\u003e0)\nmonams12 \u003c- monams1[idx4]\nsaveRDS(monams12,'monams1.RDS')\n\nidx5 \u003c- sapply(monams12, function(x) x$instr )\nmonams13 \u003c- monams12[grepl('FT|TOF',idx5)]\nidx5 \u003c- sapply(monams13, function(x) x$instr )\n\nnn \u003c- sapply(monams13,function(x) x$np)\nmedian(as.numeric(nn))\nmean(as.numeric(nn))\nsaveRDS(monams13,'monahrms1.RDS')\n```\n\nIf you have your own database in \"msp\" format, you can generate the custom database by the following code:\n\n```{r eval=FALSE}\nmsp \u003c- enviGCMS::getMSP('MoNA-export-LC-MS_Spectra.msp')\nsaveRDS(msp,'custom.RDS')\n```\n\nTo use the \"*.RDS\" database, you need to load them and refer their name for 'simmzml' function.\n\n```{r eval=FALSE}\ncustom \u003c- readRDS('custom.RDS')\nsimmzml(db=custom, name = 'test')\n```\n\nTo select certain compound for review/simulation, you could use name or inchikey.\n\n```{r}\ndata(monahrms1)\n# if you know the compound name\ncompoundname \u003c- 'Triacylglycerol 14:0-16:0-16:0'\ndatabasename \u003c- sapply(monahrms1,function(x) x$name)\ncompoundidx \u003c- databasename%in%compoundname\ncompound \u003c- monahrms1[compoundidx]\ncompound\n\n# if you know the inchikey\ncompoundinchikey \u003c- c('KQSFNXMDCOFFGW-GNDIVNLPSA-N','WRYJYFCCMSVEPQ-ORAXXRKOSA-N')\ndatabaseinchikey \u003c- sapply(monahrms1,function(x) x$inchikey)\ncompoundidx \u003c- databaseinchikey%in%compoundinchikey\ncompound \u003c- monahrms1[compoundidx]\ncompound\n```\n\n\n### Multiple files with experiment design\n\nYou could stimulate two groups of raw data with different peak heights for the same compounds. Retention time will follow a uniform distribution. 100 compounds could be selected randomly and base peaks' signal to noise ratio could be sampled from 100 to 1000. When signal to noise ratio is fixed for all samples, the peaks height will still be the only changed parameters for both groups. Each group contain 10 samples and 30% compounds are changed between case and control groups.\n\n```{r eval=FALSE}\ndir.create('case')\ndir.create('control')\n# set different peak height for 100 compounds\nph1 \u003c- c(rep(5,30),rep(10,40),rep(15,30))\nph2 \u003c- c(rep(5,20),rep(10,30),rep(15,50))\n# set retention time for 100 compounds. When the peak width is set as a single value, the simulated base peak width will be from a poisson distribution with this value as lambda. \nrt \u003c- seq(10,590,length.out=100)\nset.seed(1)\n# select compounds from database\ncompound \u003c- sample(c(1:4000),100)\nset.seed(2)\n# select signal to noise ratio for a larger dynamic range\nsn \u003c- sample(c(100:10000),100)\nfor(i in c(1:10)){\n  simmzml(name=paste0('case/case',i),db=monahrms1,pheight = ph1,compound=compound,rtime = rt, sn=sn)\n}\n\nfor(i in c(1:10)){\n  simmzml(name=paste0('control/control',i),db=monahrms1,pheight = ph2,compound=compound,rtime = rt, sn=sn)\n}\n```\n\nThen you could find 10 mzML files in case sub folder and another 10 mzML files in control sub folder, as well as corresponding csv files with m/z, retention time and compound name of the peaks. \n\nIf you prefer to simulate retention time shifts for different samples, you could add a random number to the retention time of each compound.\n\n```{r eval=FALSE}\nrt0 \u003c- rt\nset.seed(42)\nfor(i in c(1:10)){\n        rt \u003c- rt0 + rnorm(100) \n        simmzml(name=paste0('case/case',i),db=monahrms1,pwidth = pw1,compound=compound,rtime = rt, sn=sn)\n}\n```\n\n### Chromatography peaks\n\nYou could also use `simmzml` to stimulate tailing/leading peaks by defining the tailing factor of the peaks. When the tailing factor is lower than 1, the peaks are leading peaks. When the tailing factor is larger than 1, the peaks are tailing peaks. \n\n```{r eval=FALSE}\n# leading peaks\nsimmzml(name='test',db=monahrms1,pwidth = 10,compound=1,rtime = 100, sn=10,tailingfactor = 0.8)\n# tailing peaks\nsimmzml(name='test',db=monahrms1,pwidth = 10,compound=1,rtime = 100, sn=10,tailingfactor = 1.5)\n```\n\n### matrix stimulation\n\nYou could also input a m/z vector as matrix masses. Those masses will generate background baseline signals. By default, the mass vector is from matrix samples previous [published](https://jcheminf.biomedcentral.com/articles/10.1186/s13321-022-00586-8). \n\n```{r eval=FALSE}\ndata(mzm)\nsimmzml(name='test',db=monahrms1,pwidth = 10,compound=1,rtime = 100, sn=10,matrixmz = mzm,matrix = TRUE)\n```\n\n### Retention time simulation\n\nWe included column types and experimental retention time (in seconds) for LC-MS data and retention index for GC-MS data. You could use the following code to access such information.\n\n```{r}\ndata(monahrms1)\n# select compound by their index\ncompound \u003c- c(1,2,3)\ncolumn \u003c- sapply(monahrms1[compound],function(x) x$column)\n# print column\ncolumn\nretentiontime \u003c- sapply(monahrms1[compound],function(x) x$rt)\n# print retention time\nretentiontime\ndata(\"hmdbcms\")\n# select compound by their index\ncompound \u003c- c(1,2,300)\nretentionindex \u003c- sapply(hmdbcms[compound],function(x) x$rti)\n# print retention index\nretentionindex\n```\n\n\n## Peaks list simulation\n\nYou could also use `mzrtsim` to make simulation of peak list.\n\nHere we make a simulation of 100 compounds from selected database with two conditions and three batches. 5 percentage of the peaks were influenced by conditions and 10 percentage of the peaks were influenced by batch effects. Three different type could be simulated: monotonic, random and block. You could also bind batch type, for example, 'mb' means the simulation would contain both monotonic and block batch effects. 'db' means the spectra database to be used for simulation as metioned in raw data simulation section.\n\n```{r mzrtsim}\nlibrary(mzrtsim)\ndata(\"monams1\")\nsimdata \u003c- mzrtsim(ncomp = 100, ncond = 2, ncpeaks = 0.05,\n  nbatch = 3, nbpeaks = 0.1, npercond = 10, nperbatch = c(8, 5, 7), seed = 42, batchtype = 'mb', db=monams1)\n```\n\nYou could save the simulated data into multiple csv files by `simdata` function. `simraw.csv` could be used for metaboanalyst. `simraw2.csv` show the raw peaks list. `simcon.csv` show peaks influenced by conditions only.`simbatchmatrix.csv` show peaks influnced by batch effects only. `simbat.csv` show peaks influenced by batch effects and conditions. `simcomp.csv` show independent peaks influenced by conditions and batch effects. `simcompchange.csv` show the conditions changes of each groups. `simblockbatchange.csv` show the block batch changes of each groups. `simmonobatchange.csv` show the monotonic batch changes of each group.\n\n```{r simdata, eval=F}\nsimdata(sim,name = \"sim\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyufree%2Fmzrtsim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyufree%2Fmzrtsim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyufree%2Fmzrtsim/lists"}