From f9fff5f572b007d869406a79b1b0a3b874bdc862 Mon Sep 17 00:00:00 2001
From: alihamraoui <hamraoui@bio.ens.psl.eu>
Date: Mon, 24 Jun 2024 17:51:37 +0200
Subject: [PATCH 1/5] index.html

---
 index.html | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 175 insertions(+)
 create mode 100644 index.html
diff --git a/index.html b/index.html
new file mode 100644
index 0000000..a1ec6ce
--- /dev/null
+++ b/index.html
@@ -0,0 +1,175 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="description" content="None" />
+      <link rel="shortcut icon" href="img/favicon.ico" />
+    <title>AsaruSim</title>
+    <link rel="stylesheet" href="css/theme.css" />
+    <link rel="stylesheet" href="css/theme_extra.css" />
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" />
+    
+      <script>
+        // Current page data
+        var mkdocs_page_name = "Installation";
+        var mkdocs_page_input_path = "index.md";
+        var mkdocs_page_url = null;
+      </script>
+    
+    <!--[if lt IE 9]>
+      <script src="js/html5shiv.min.js"></script>
+    <![endif]-->
+      <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
+      <script>hljs.highlightAll();</script> 
+</head>
+
+<body class="wy-body-for-nav" role="document">
+
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
+    <div class="wy-side-scroll">
+      <div class="wy-side-nav-search">
+          <a href="." class="icon icon-home"> AsaruSim
+        </a><div role="search">
+  <form id ="rtd-search-form" class="wy-form" action="./search.html" method="get">
+      <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" title="Type search term here" />
+  </form>
+</div>
+      </div>
+
+      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <ul>
+                <li class="toctree-l1"><a class="reference internal" href="introduction/">Introduction</a>
+                </li>
+              </ul>
+              <ul class="current">
+                <li class="toctree-l1 current"><a class="reference internal current" href="#">Installation</a>
+    <ul class="current">
+    <li class="toctree-l2"><a class="reference internal" href="#requirements">Requirements</a>
+    </li>
+    <li class="toctree-l2"><a class="reference internal" href="#install-nextflow">Install nextflow</a>
+    </li>
+    <li class="toctree-l2"><a class="reference internal" href="#install-docker">Install docker</a>
+    </li>
+    <li class="toctree-l2"><a class="reference internal" href="#run-asarusim">Run AsaruSim</a>
+    </li>
+    </ul>
+                </li>
+              </ul>
+              <ul>
+                <li class="toctree-l1"><a class="reference internal" href="parameters/">Input parameters</a>
+                </li>
+              </ul>
+              <ul>
+                <li class="toctree-l1"><a class="reference internal" href="examples/">Use example</a>
+                </li>
+              </ul>
+      </div>
+    </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+      <nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu">
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href=".">AsaruSim</a>
+        
+      </nav>
+      <div class="wy-nav-content">
+        <div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="." class="icon icon-home" aria-label="Docs"></a></li>
+      <li class="breadcrumb-item active">Installation</li>
+    <li class="wy-breadcrumbs-aside">
+    </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+            <div class="section" itemprop="articleBody">
+              
+                <h1 id="welcome-to-asarusim">Welcome to AsaruSim</h1>
+<p>AsaruSim is an automated <a href="https://www.nextflow.io/">Nextflow</a> workflow designed for simulating 10x single-cell Nanopore reads. It allows to benchmark and optimize single-cell Nanopore long read data processing pipelines.</p>
+<p>Github repository <a href="https://github.com/alihamraoui/AsaruSim">AsaruSim</a>.</p>
+<h2 id="requirements">Requirements</h2>
+<ul>
+<li><code>Nextflow</code> - A workflow engine for complex data pipelines.</li>
+<li><code>Docker</code> or <code>Singularity</code> - Containers for packaging necessary software, ensuring reproducibility.</li>
+</ul>
+<h2 id="install-nextflow">Install nextflow</h2>
+<p>Ensure you have the following installed on your system:</p>
+<p><code>Java 8 or later</code>: Nextflow requires Java. Install it from Oracle or use a package manager like apt, brew, or yum depending on your OS.</p>
+<pre><code class="language-bash">curl -s https://get.nextflow.io | bash
+chmod +x nextflow
+sudo mv nextflow /usr/local/bin/
+</code></pre>
+<p>Nextflow is now installed and ready to use on your system. For further details on using Nextflow, refer to the <a href="https://www.nextflow.io/docs/latest/index.html">official documentation</a>.</p>
+<h2 id="install-docker">Install docker</h2>
+<p><a href="https://docs.docker.com/engine/install/">Install Docker</a>.</p>
+<h2 id="run-asarusim">Run AsaruSim</h2>
+<ul>
+<li>1 - Clone the github repository</li>
+</ul>
+<pre><code class="language-bash">git clone https://github.com/alihamraoui/AsaruSim.git
+
+cd AsaruSim
+</code></pre>
+<ul>
+<li>2 - Run using nextflow</li>
+</ul>
+<pre><code class="language-bash">nextflow run main.nf --help
+</code></pre>
+              
+            </div>
+          </div><footer>
+    <div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
+        <a href="introduction/" class="btn btn-neutral float-left" title="Introduction"><span class="icon icon-circle-arrow-left"></span> Previous</a>
+        <a href="parameters/" class="btn btn-neutral float-right" title="Input parameters">Next <span class="icon icon-circle-arrow-right"></span></a>
+    </div>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <!-- Copyright etc -->
+  </div>
+
+  Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
+</footer>
+          
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+
+  <div class="rst-versions" role="note" aria-label="Versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    
+    
+      <span><a href="introduction/" style="color: #fcfcfc">&laquo; Previous</a></span>
+    
+    
+      <span><a href="parameters/" style="color: #fcfcfc">Next &raquo;</a></span>
+    
+  </span>
+</div>
+    <script src="js/jquery-3.6.0.min.js"></script>
+    <script>var base_url = ".";</script>
+    <script src="js/theme_extra.js"></script>
+    <script src="js/theme.js"></script>
+      <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+      <script src="search/main.js"></script>
+    <script>
+        jQuery(function () {
+            SphinxRtdTheme.Navigation.enable(true);
+        });
+    </script>
+
+</body>
+</html>
+
+<!--
+MkDocs version : 1.6.0
+Build Date UTC : 2024-06-24 15:16:33.822496+00:00
+-->

From d5caadaaa792bc3631bdf7630aac9b1314b2f2a0 Mon Sep 17 00:00:00 2001
From: Hamraoui Ali <72599648+alihamraoui@users.noreply.github.com>
Date: Mon, 24 Jun 2024 17:54:43 +0200
Subject: [PATCH 2/5] Rename README.md to README2.md

---
 README.md => README2.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename README.md => README2.md (100%)

diff --git a/README.md b/README2.md
similarity index 100%
rename from README.md
rename to README2.md

From 0d637a1ff9b7ebb17f816435623714419df3ac82 Mon Sep 17 00:00:00 2001
From: Ali Hamraoui <hamraoui@bio.ens.psl.eu>
Date: Thu, 11 Jul 2024 14:24:19 +0200
Subject: [PATCH 3/5] ADD: add seed value for PCR command

---
 bin/PCR.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)
 mode change 100644 => 100755 bin/PCR.py

diff --git a/bin/PCR.py b/bin/PCR.py
old mode 100644
new mode 100755
index 1d72ca9..ee9fb45
--- a/bin/PCR.py
+++ b/bin/PCR.py
@@ -5,7 +5,6 @@
 import os, sys, math
 from toolkit import multiprocessing_submit
 
-
 YELLOW = "\033[93m"
 GRAY = "\033[90m"
 RESET = "\033[0m"
@@ -13,7 +12,7 @@
 logging.basicConfig(level=logging.INFO, format=GRAY+ '%(message)s' +RESET)
 parser = argparse.ArgumentParser(description="Script for generating template sequences for scRNAseq simulation.")
 
-parser.add_argument('-f','--template', type=str, help="Path to the template FASTA file.")
+parser.add_argument('-f','--template', type=str, required=True, help="Path to the template FASTA file.")
 parser.add_argument('-o','--out', type=str, default="out.fa", help="Path to the output FASTA file.")
 parser.add_argument('-c','--cycles', type=int, default=5, help="number of cycles.")
 parser.add_argument('-d','--dup', type=int, default=0.7, help="duplication rate.")
@@ -21,6 +20,7 @@
 parser.add_argument('-t','--thread', type=int, default=4, help="number of threads to use.")
 parser.add_argument('-b','--batch_size', type=int, default=500, help="batch size.")
 parser.add_argument('-n','--totalNamber', type=int, default=None, help="total number of sequence to select from the finel pool.")
+parser.add_argument('-s','--seed', type=int, default=2024, help="seed value.")
 
 class Molecule ():
     def __init__(self, name, length, seq, root, inherited_mut):
@@ -156,6 +156,9 @@ def main():
     logging.info("Batch size         : %s" , args.batch_size)
     logging.info("_______________________________")
 
+    random.seed(args.seed)
+    np.random.seed(args.seed)
+
     root_logger = logging.getLogger()
     for handler in root_logger.handlers:
         handler.setFormatter(logging.Formatter(YELLOW+'%(asctime)s - %(levelname)s' +RESET+ ' - %(message)s'))

From 0c4106d4f3be41cbd47cdb58c945c36795bd04df Mon Sep 17 00:00:00 2001
From: Ali Hamraoui <hamraoui@bio.ens.psl.eu>
Date: Thu, 11 Jul 2024 16:58:36 +0200
Subject: [PATCH 4/5] ADD: add PCR amplification process step

---
 bin/PCR.py     |  2 +-
 main.nf        | 11 ++++++++++-
 modules/PCR.nf | 23 +++++++++++++++++++++++
 3 files changed, 34 insertions(+), 2 deletions(-)
 create mode 100644 modules/PCR.nf

diff --git a/bin/PCR.py b/bin/PCR.py
index ee9fb45..6a5b514 100755
--- a/bin/PCR.py
+++ b/bin/PCR.py
@@ -15,7 +15,7 @@
 parser.add_argument('-f','--template', type=str, required=True, help="Path to the template FASTA file.")
 parser.add_argument('-o','--out', type=str, default="out.fa", help="Path to the output FASTA file.")
 parser.add_argument('-c','--cycles', type=int, default=5, help="number of cycles.")
-parser.add_argument('-d','--dup', type=int, default=0.7, help="duplication rate.")
+parser.add_argument('-d','--dup', type=float, default=0.7, help="duplication rate.")
 parser.add_argument('-e','--error', type=float, default=0.00003, help="error rate.")
 parser.add_argument('-t','--thread', type=int, default=4, help="number of threads to use.")
 parser.add_argument('-b','--batch_size', type=int, default=500, help="batch size.")
diff --git a/main.nf b/main.nf
index 1aac218..2134ba1 100755
--- a/main.nf
+++ b/main.nf
@@ -16,7 +16,11 @@ log.info """\
     build erro model              : ${params.build_model}
     FASTQ model                   : ${params.model_fastq}
     reference genome              : ${params.ref_genome}
-    amplification rate            : ${params.amp}
+    UMI duplication               : ${params.amp}
+    PCR amplification cycles      : ${params.cycles}
+    PCR duplication rate          : ${params.dup_rate}
+    PCR error rate                : ${params.error_rate}
+    Total number of PCR reads     : ${params.totalNamber}
     outdir                        : ${params.outdir}
     """
     .stripIndent()
@@ -29,6 +33,7 @@ include { LENGTH_ESTIMATION } from './modules/errorModel.nf'
 
 include { COUNT_SIMULATOR } from './modules/modules.nf'
 include { TEMPLATE_MAKER } from './modules/modules.nf'
+include { PCR_SIMULATOR } from './modules/PCR.nf'
 include { ERRORS_SIMULATOR } from './modules/modules.nf'
 include { GROUND_TRUTH } from './modules/modules.nf'
 include { QC } from './modules/modules.nf'
@@ -84,6 +89,10 @@ workflow {
         template_ch = TEMPLATE_MAKER(matrix_ch, transcriptome_ch, barcodes_ch, gtf_ch, length_dist_ch)
     }
 
+    if (params.cycles > 0) {
+        template_ch = PCR_SIMULATOR(template_ch)
+    }
+
     gr_truth_ch = GROUND_TRUTH(template_ch)
     error_ch    = ERRORS_SIMULATOR(template_ch, error_model_ch, qscore_model_ch, identity_ch)
     qc_ch       = QC(error_ch)
diff --git a/modules/PCR.nf b/modules/PCR.nf
new file mode 100644
index 0000000..7d0dc71
--- /dev/null
+++ b/modules/PCR.nf
@@ -0,0 +1,23 @@
+process PCR_SIMULATOR {
+    publishDir params.outdir, mode:'copy'
+    
+    input:
+    path fasta
+
+    output:
+    path "amplified_reads.fa" 
+    
+    script:
+        def totalNamber = params.totalNamber == false? "" : "--totalNamber $params.totalNamber"
+
+    """
+    python3.11 $projectDir/bin/PCR.py -f ${fasta} \
+    --cycles $params.cycles \
+    --dup $params.dup_rate \
+    --error $params.error_rate \
+    --thread $params.threads \
+    $totalNamber \
+    --seed 2024 \
+    --out amplified_reads.fa
+    """
+}
\ No newline at end of file

From c227a5cc504d6de7299595e0986007c588248f2b Mon Sep 17 00:00:00 2001
From: Hamraoui Ali <72599648+alihamraoui@users.noreply.github.com>
Date: Thu, 11 Jul 2024 17:05:43 +0200
Subject: [PATCH 5/5] update README.md

---
 README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1a2a66e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,128 @@
+[![Made with Docker](https://img.shields.io/badge/Made_with-Docker-blue?logo=docker&logoColor=white)](https://www.docker.com/ "Go to Docker homepage")
+[![dependency - Nextflow](https://img.shields.io/badge/dependency-Nextflow-green)](https://pkg.go.dev/Nextflow)
+
+[![GitHub tag](https://img.shields.io/github/tag/alihamraoui/AsaruSim?include_prereleases=&sort=semver&color=blue)](https://github.com/alihamraoui/AsaruSim/releases/tag/v1.0)
+![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)
+[![issues - AsaruSim](https://img.shields.io/github/issues/alihamraoui/AsaruSim)](https://github.com/alihamraoui/AsaruSim/issues)
+[![Twitter Follow](https://img.shields.io/twitter/follow/Genomique_ENS.svg?style=social)](https://twitter.com/Genomique_ENS)
+
+# Asaru Sim Documentation
+
+`AsaruSim` is an automated Nextflow workflow designed for simulating 10x single-cell Nanopore reads. It allows to benchmark and optimize single-cell Nanopore long read data processing pipelines.
+
+![Workflow Schema](images/workflow.png)
+
+## Prerequisites
+
+Before starting, ensure the following tools are installed and properly set up on your system:
+
+- **Nextflow**: A workflow engine for complex data pipelines. [Installation guide for Nextflow](https://www.nextflow.io/docs/latest/getstarted.html).
+- **Docker** or **Singularity**: Containers for packaging necessary software, ensuring reproducibility. [Docker installation guide](https://docs.docker.com/get-docker/), [Singularity installation guide](https://sylabs.io/guides/3.0/user-guide/installation.html).
+- **Git**: Required to clone the workflow repository. [Git installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+
+## Installation
+
+Clone the `AsaruSim` GitHub repository:
+
+```bash
+git clone https://github.com/alihamraoui/AsaruSim.git
+cd AsaruSim
+```
+
+## Configuration
+
+Customize runs by editing the `nextflow.config` file and/or specifying parameters at the command line.
+
+### Pipeline Input Parameters
+
+Here are the primary input parameters for configuring the workflow:
+
+| Parameter          | Description                                                   | Default Value                                 |
+|--------------------|---------------------------------------------------------------|-----------------------------------------------|
+| `matrix`           | Path to the count matrix csv file (required)                  | `test_data/matrix.csv`                        |
+| `bc_counts`        | Path to the barcode count file                                | `test_data/test_bc.csv`                       |
+| `transcriptome`    | Path to the reference transcriptome file (required)           | `test_data/transcriptome.fa`                  |
+| `features`         | Matrix feature counts                                         | `transcript_id`                               |
+| `gtf`              | Path to transcriptom annotation .gtf file                     | `null`                                        |
+| `cell_types_annotation`    | Path to cell type annotation .csv file                | `null`                                        |
+
+### Error/Qscore Parameters
+
+Configuration for error model:
+
+| Parameter          | Description                                                   | Default Value                                 |
+|--------------------|---------------------------------------------------------------|-----------------------------------------------|
+| `trained_model`    | Badread pre-trained error/Qscore model name                   | `nanopore2023`                                |
+| `badread_identity` | Comma-separated values for Badread identity parameters        | `"98,2,99"`                                   |
+| `error_model`      | Custom error model file (optional)                            | `null`                                        |
+| `qscore_model`     | Custom Q-score model file (optional)                          | `null`                                        |
+| `build_model`      | to build your own error/Qscor model                           | `false`                                       |
+| `model_fastq`      | reference real read (.fastq) to train error model   (optional)      | `false`                                       |
+| `ref_genome`       | reference genome .fasta file (optional)                       | `false`                                       |
+
+### Additional Parameters
+
+| Parameter          | Description                                                   | Default Value                                 |
+|--------------------|---------------------------------------------------------------|-----------------------------------------------|
+| `amp`              | Amplification factor                                          | `1`                                           |
+| `outdir`           | Output directory for results                                  | `"results"`                                   |
+| `projectName`      | Name of the project                                           | `"test_project"`                              |
+
+### Run Parameters
+
+Configuration for running the workflow:
+
+| Parameter         | Description                        | Default Value             |
+|-------------------|------------------------------------|---------------------------|
+| `threads`         | Number of threads to use           | `4`                       |
+| `container`       | Docker container for the workflow  | `'hamraouii/wf-SLSim'`    |
+| `docker.runOptions` | Docker run options to use       | `'-u $(id -u):$(id -g)'`  |
+
+## Execution
+
+To run the workflow with basic example:
+
+You can simulate a realistic disribution of per barcodes UMI counts by providing in addition to the filtered counts matrix a .csv file of BC counts.  AsaruSim will add a random transcrips count to fit the real distribution.
+```bash
+nextflow run main.nf --matrix test_data/matrix.csv \
+                     --bc_counts test_data/test_bc.csv \
+                     --transcriptome test_data/transcriptome.fa \
+
+```
+User can choose among 4 ways to simulate template reads.
+- use a real count matrix
+- estimated the parameter from a real count matrix to simulate synthetic count matrix 
+- specified by his/her own the input parameter
+- a combination of the above options
+
+We use SPARSIM tools to simulate count matrix. for more information a bout synthetic count matrix, please read [SPARSIM](https://gitlab.com/sysbiobig/sparsim/-/blob/master/vignettes/sparsim.Rmd?ref_type=heads#Sec_Input_parameter_estimated_from_data) documentaion.
+
+#### use a real count matrix
+```bash
+nextflow run main.nf --matrix test_data/matrix.csv \
+                     --transcriptome test_data/transcriptome.fa
+```
+
+## Results
+
+After execution, results will be available in the specified `--outdir`. This includes simulated Nanopore reads `.fastq`, along with log files and QC report.
+
+## Cleaning Up
+
+To clean up temporary files generated by Nextflow:
+
+```bash
+nextflow clean -f
+```
+## Acknowledgements
+
+- We would like to express our gratitude to [Youyupei](https://github.com/youyupei) for the development of [SLSim](https://github.com/youyupei/SLSim), which has been helpful to the `AsaruSim` workflow.
+- Additionally, our thanks go to the teams behind [Badread](https://github.com/rrwick/Badread) and [SPARSim](https://gitlab.com/sysbiobig/sparsim), whose tools are integral to the `AsaruSim` workflow.
+
+## Support and Contributions
+
+For support, please open an issue in the repository's "Issues" section. Contributions via Pull Requests are welcome. Follow the contribution guidelines specified in `CONTRIBUTING.md`.
+
+## License
+
+`AsaruSim` is distributed under a specific license. Check the `LICENSE` file in the GitHub repository for details.
