diff --git a/docs/images/._schema.png b/docs/images/._schema.png index 881dd01..340d8f8 100644 Binary files a/docs/images/._schema.png and b/docs/images/._schema.png differ diff --git a/docs/index.html b/docs/index.html index 9decf19..01e1422 100644 --- a/docs/index.html +++ b/docs/index.html @@ -60,7 +60,7 @@
- + Skip to content @@ -415,7 +415,7 @@ -

Welcome to AsaruSim V1.0.

+

AsaruSim V1.0.1 documentation



version - AsaruSim @@ -440,9 +440,10 @@

Welcome to AsaruSim V1.0.

workflow schema

Contributing

-

Contributions are more than welcome. See the git repository page.

+

Contributions are more than welcome. See the git repository + GitHub

License

-

AsaruSim is released under the GPL 3.0 license.

+

AsaruSim is released under the GPL 3.0 license.

Citations

If you use AsaruSim in your research, please cite this manuscript:

diff --git a/docs/search/search_index.json b/docs/search/search_index.json index 3aa6cd3..9e15866 100644 --- a/docs/search/search_index.json +++ b/docs/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to AsaruSim V1.0.","text":"

AsaruSim derives from the Amazigh word Asaru (\u2d30\u2d59\u2d30\u2d54\u2d53 ) which can mean \"pipeline\" or \"channel\". AsaruSim is an automated Nextflow workflow designed for simulating 10x single-cell long read data from the count matrix level to the sequence level. It aimed at creating a gold standard dataset for the assessment and optimization of single-cell long-read methods.

Five major steps are implemented:

(1) - Simulation of a synthetic UMI count matrix. (2) - Generation of perfect raw reads. (3) - Amplification of the perfect reads. (4) - Generation of realistic synthetic reads by adding errors to mimic real reads. (5) - Production of a report with quality control values and plots calculated on the resulting synthetic reads.

"},{"location":"#contributing","title":"Contributing","text":"

Contributions are more than welcome. See the git repository page.

"},{"location":"#license","title":"License","text":"

AsaruSim is released under the GPL 3.0 license.

"},{"location":"#citations","title":"Citations","text":"

If you use AsaruSim in your research, please cite this manuscript:

Ali Hamraoui, Laurent Jourdren and Morgane Thomas-Chollier. AsaruSim: a single-cell and spatial RNA-Seq Nanopore long-reads simulation workflow. bioRxiv 2024.09.20.613625; doi: https://doi.org/10.1101/2024.09.20.613625

"},{"location":"#acknowledgements","title":"Acknowledgements","text":"

We would like to express our thanks to SLSim developers, which has been helpful to the AsaruSim workflow. Additionally, our thanks go to the teams behind Badread, SPARSim, and Trans-NanoSim whose tools are integral to the AsaruSim workflow.

"},{"location":"examples/","title":"Use example","text":""},{"location":"examples/#usage","title":"Usage","text":"

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 documentaion.

"},{"location":"examples/#examples","title":"EXAMPLES","text":""},{"location":"examples/#sample-data","title":"Sample data","text":"

A demonstration dataset to initiate this workflow is accessible on zenodo DOI : 10.5281/zenodo.12731408. This dataset is a subsample from a Nanopore run of the 10X 5k human pbmcs.

The human GRCh38 reference transcriptome, gtf annotation and fasta referance genome can be downloaded from Ensembl.

"},{"location":"examples/#basic-workflow","title":"BASIC WORKFLOW","text":"
 nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                      --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                      --features gene_name \\\n                      --gtf dataset/genes.gtf\n
"},{"location":"examples/#with-pcr-amplifiction","title":"WITH PCR AMPLIFICTION","text":"
 nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                      --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                      --features gene_name \\\n                      --gtf dataset/GRCh38-2020-A-genes.gtf \\\n                      --pcr_cycles 2 \\\n                      --pcr_dup_rate 0.7 \\\n                      --pcr_error_rate 0.00003\n
"},{"location":"examples/#with-simulated-cell-type-counts","title":"WITH SIMULATED CELL TYPE COUNTS","text":"
 nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                      --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                      --features gene_name \\\n                      --gtf dataset/GRCh38-2020-A-genes.gtf \\\n                      --sim_celltypes true \\\n                      --cell_types_annotation dataset/sub_pbmc_cell_type.csv\n
"},{"location":"examples/#with-personalized-error-model","title":"WITH PERSONALIZED ERROR MODEL","text":"
nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                     --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                     --features gene_name \\\n                     --gtf dataset/GRCh38-2020-A-genes.gtf \\\n                     --build_model true \\\n                     --fastq_model dataset/sub_pbmc_reads.fq \\\n                     --ref_genome dataset/GRCh38-2020-A-genome.fa \n
"},{"location":"examples/#complete-workflow","title":"COMPLETE WORKFLOW","text":"
 nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                      --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                      --features gene_name \\\n                      --gtf dataset/GRCh38-2020-A-genes.gtf \\\n                      --sim_celltypes true \\\n                      --cell_types_annotation dataset/sub_pbmc_cell_type.csv\n                      --build_model true \\\n                      --fastq_model dataset/sub_pbmc_reads.fq \\\n                      --ref_genome dataset/GRCh38-2020-A-genome.fa \n                      --pcr_cycles 2 \\\n                      --pcr_dup_rate 0.7 \\\n                      --pcr_error_rate 0.00003\n
"},{"location":"examples/#results","title":"Results","text":"

After execution, results will be available in the specified --outdir. This includes simulated Nanopore reads .fastq, along with log files and QC report.

"},{"location":"examples/#cleaning-up","title":"Cleaning Up","text":"

To clean up temporary files generated by Nextflow:

nextflow clean -f\n
"},{"location":"introduction/","title":"Install AsaruSim","text":"

This pipeline is powered by Nextflow workflow manager. All dependencies are automatically managed by Nextflow through a preconfigured Docker container, ensuring a seamless and reproducible installation process.

AsaruSim Github repository.

"},{"location":"introduction/#requirements","title":"Requirements","text":""},{"location":"introduction/#install-nextflow","title":"Install nextflow","text":"

Ensure you have the following installed on your system:

Java 8 or later: Nextflow requires Java. Install it from Oracle or use a package manager like apt, brew, or yum depending on your OS.

curl -s https://get.nextflow.io | bash\nchmod +x nextflow\nsudo mv nextflow /usr/local/bin/\n

Nextflow is now installed and ready to use on your system. For further details on using Nextflow, refer to the official documentation.

"},{"location":"introduction/#install-docker","title":"Install docker","text":"

Install Docker.

"},{"location":"introduction/#run-asarusim","title":"Run AsaruSim","text":" 
git clone https://github.com/GenomiqueENS/AsaruSim.git\n\ncd AsaruSim\n
nextflow run main.nf --help\n
"},{"location":"parameters/","title":"Input parameters","text":"

AsaruSim simulation requires input parameters, describing the macro characteristics of the desired synthetic reads.

"},{"location":"parameters/#count-matrix","title":"Count matrix","text":""},{"location":"parameters/#-matrix-csv-file","title":"--matrix csv file","text":"

Feature-by-cell (gene/cell or isoform/cell) count matrix in csv format, where rows represent the features (genes or transcripts) and columns represent cells (or spatial barcodes). The input matrix may be derived from an existing single-cell short- or long-read preprocessed run. this parameter is required.

AsaruSim require a feature name and GTF annotation for gene-per-cell matrix

Since the sequence names in the reference transcriptome correspond to transcript ids, it is necessary for users to specify the feature name within their matrix when gene-per-cell matrix is provided. Set the feature name using the --features parameter. Available options include:

Additionally, users are required to supply a gene annotation (.gtf format) file using the --gtf parameter.

"},{"location":"parameters/#-bc_counts-csv-file","title":"--bc_counts csv file","text":"

To simulate specific UMI counts per cell barcode with random transcripts, set the --bc_counts parameter to the path of a UMI counts .CSV file. This parameter eliminates the need for an input matrix, enabling the simulation of UMI counts where transcripts are chosed randomly.

example of UMI counts per CB file:

CB counts ACGGCGATCGCGAGCC 1260 ACGGCGATCGCGAGCC 1104"},{"location":"parameters/#-cell_types_annotation-csv-file","title":"--cell_types_annotation csv file","text":"

AsaruSim can generate synthetic count tables with varying cell types, differentially expressed genes, or isoforms. This capability is particularly useful for simulating count matrices that mimic the characteristics of existing cell populations. To simulate cell groups, AsaruSim requirs suplimentary parameters describing the characteristic of desired cell groups.

Requirements for simulating cell groups : AsaruSim use SPARSim R package to simulate synthetic count table. for each cell group to simulate, SPARSim needs 3 information as input:

fore more information see SPARSim vignettes.

AsaruSim allows user to estimate this characteristic from an existing count table. To do so, the user need to set --sim_celltypes parameter to true and to provide the list of cell barcodes of each group (.CSV file) using --cell_types_annotation parameter:

CB cell_type ACGGCGATCGCGAGCC type 1 ACGGCGATCGCGAGCC type 2

AsaruSim will then use the provided matrix to estimate characteristic of each cell groups and generate a synthetic count matrix.

"},{"location":"parameters/#template","title":"Template","text":"

AsaruSim generates reads that correspond to a 10X Genomics library construction coupled with Nanopore sequencing. The final construction corresponds to : an adaptor sequence composed of 10X and Nanopore adaptors, a cellular barcode (CB), UMI sequences at the same frequencies as in the synthetic count matrix, a 20 bp oligo(dT), the feature-corresponding cDNA sequence from the reference transcriptome and a template switch oligo (TSO) at the end.

"},{"location":"parameters/#-dt_length-int","title":"--dT_LENGTH INT","text":"

The mean length of the oligo(dT) tail sequence, assuming a normal distribution. (default : 15 bp).

"},{"location":"parameters/#-adapter_seq-str","title":"--ADAPTER_SEQ STR","text":"

Defines the sequence of the adapter used in the ONT and 10X Genomics libraries. By default, the 10X 3' solution V3 adapter sequence is used.

(default :ACTAAAGGCCATTACGGCCTACACGACGCTCTTCCGATCT).

"},{"location":"parameters/#-tso_seq-str","title":"--TSO_SEQ STR","text":"

Specifies the sequence of the Template Switching Oligo (TSO) nucleotid.

(default :TGTACTCTGCGTTGATACCACTGCTT).

"},{"location":"parameters/#-full_length-bool","title":"--full_length BOOL","text":"

Simulate untruncated reads. (default :false).

"},{"location":"parameters/#-truncation_model-csv-file","title":"--truncation_model csv file","text":"

Truncation probability distribution. Automatically generated when the --build_model option is enabled. (default :bin/models/truncation_default_model.csv)

"},{"location":"parameters/#-unspliced_ratio-float","title":"--unspliced_ratio FLOAT","text":"

The percentage of unspliced reads to simulate. (default :0.0).

"},{"location":"parameters/#-intron_retention-bool","title":"--intron_retention BOOL","text":"

Enable simulation of intron retention events. If enabled, a reference genome must be provided using the --ref_genome option. (default :false)

"},{"location":"parameters/#-ir_model-csv-file","title":"--ir_model csv file","text":"

Markov model of Intron Retention events. This can be generated using the Nanosim module model_intron_retention.py. (default :bin/models/SC3pv3_GEX_Human_IR_markov_model)

AsaruSim requires both a reference genome and a GTF annotation to simulate intron retention events and unspliced transcripts

To simulate intron retention events (--intron_retention) and unspliced transcripts (--unspliced_ratio), you must provide a reference genome in FASTA format. Additionally, a GTF annotation file containing intron coordinate information is required, which can be generated using the AGAT tool:\\

 conda install -c bioconda agat\nagat_sp_add_introns.pl --gff genes.sorted.gtf -o genes.sorted.intron.gff

"},{"location":"parameters/#reference-transcripts","title":"Reference transcripts","text":"

The feature-corresponding cDNA sequence is sampled from the reference transcriptome or reference genome for unsplaced and intron retained transcripts.

"},{"location":"parameters/#-transcriptome-fasta-file","title":"--transcriptome FASTA file","text":"

A reference transcriptome file in .fasta format can be downloaded from Ensembl.

"},{"location":"parameters/#-length_dist-str","title":"--length_dist STR","text":"

To mimic the real read length distribution when a gene expression matrix is provided, a realistic read length distribution is achieved by selecting a random cDNA of the corresponding gene, with a prior probability favoring short-length cDNA.

AsaruSim estimates this read length using a log-normal distribution. Users may provide their parameters to personalize the distribution using three comma-delimited values (shape, location, scale) with the parameter --length_dist. (default :0.37,0.0,825)

Fit read distribution of real reads

Users may also fit their real reads distribution with this approach by providing a subset of real reads (in .FASTQ format) using the --model_fastq parameter. (See also build model in the Error model section)

"},{"location":"parameters/#-ref_genome-fasta-file","title":"--ref_genome FASTA file","text":"

The reference genome file in .fasta format can be downloaded from Ensembl.

"},{"location":"parameters/#pcr-amplification","title":"PCR amplification","text":"

AsaruSim take into account the bias of PCR amplification introduced during library constructions process. The PCR amplification is simulated by replicating the synthetic reads at each cycle, with a capturing probabily and un error rate.

"},{"location":"parameters/#-pcr_cycles-int","title":"--PCR_cycles INT","text":"

The number of PCR cycles to simulate. During each cycle, the reads are duplicated exponentially, following the formula: $$\\ N = N_0 \\times (1 + E)^{C} \\ $$

where: N is the final number of reads, N0 is the initial number of reads, E is the efficiency rate, and C is the number of cycles.

"},{"location":"parameters/#-pcr_efficiency-float","title":"--PCR_efficiency FLOAT","text":"

The efficiency rate of duplication is fixed by the user (default: --PCR_efficiency 0.9)

"},{"location":"parameters/#-pcr_error_rate-float","title":"--PCR_error_rate FLOAT","text":"

The probability to be mutated during the process for each nucleotide in the duplicated read. The error rate is also fixed by the user (default: --PCR_error_rate 3.5e-05)

"},{"location":"parameters/#-total_reads-int","title":"--total_reads INT","text":"

Number of total reads to random subset from the resulting artificial PCR product, to mimic the experimental protocol where only a subset of the sample is used for the sequencing step.

Users can use amplification rate instead of PCR amplification

Inspired by SLSim, the amplification rate allows users to repeat each template read a specified number of times. This is a simpler way to simulate amplification with: $$\\ x \\sim \\text{Poi}(\\text{amp_rate}) \\ $$ The value of x is set by the user using --amp_rate

"},{"location":"parameters/#error-model","title":"Error model","text":"

AsaruSim uses the Badread Python library to simulate nanopore sequencing errors and assign per-base quality scores based on pre-trained error models (see Badread documentation for more information). To do so, AsaruSim requires:

"},{"location":"parameters/#-trained_model-str","title":"--trained_model STR

This allows the user to choose one of the built-in error models within the Badread database. The possible values are:

nanopore2023: a model trained on ONT R10.4.1 reads from 2023 (the default). nanopore2020: a model trained on ONT R9.4.1 reads from 2020. nanopore2018: a model trained on ONT R9.4/R9.4.1 reads from 2018. random: a random error model with a 1/3 chance each of insertion, deletion, and substitution. a file path for a trained model.

","text":""},{"location":"parameters/#-badread_identity-str","title":"--badread_identity STR

Badread uses the Beta distribution to sample read identities. The distribution is defined with three parameters: mean, standard deviation, and maximum value. To pass these parameters to AsaruSim, use three comma-delimited values (identity mean, max, stdev). default : --badread_identity 95,99,2.5.

","text":""},{"location":"parameters/#-build_model-bool","title":"--build_model BOOL

To internally train a personalized read identity, Qscore, and error models, AsaruSim requires a real FASTQ read file that can be provided using --model_fastq. The user can choose the model to estimate sequence identity with the --identity_model option, which includes three possible identity models, either including or excluding gaps. By default, the \"Gap-Excluded Identity\" model is used.

AsaruSim also accepts pre-built model files

Users can use --error_model and --qscore_model to provide Badread pre-built models in file format.

","text":""}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"AsaruSim V1.0.1 documentation","text":"

AsaruSim derives from the Amazigh word Asaru (\u2d30\u2d59\u2d30\u2d54\u2d53 ) which can mean \"pipeline\" or \"channel\". AsaruSim is an automated Nextflow workflow designed for simulating 10x single-cell long read data from the count matrix level to the sequence level. It aimed at creating a gold standard dataset for the assessment and optimization of single-cell long-read methods.

Five major steps are implemented:

(1) - Simulation of a synthetic UMI count matrix. (2) - Generation of perfect raw reads. (3) - Amplification of the perfect reads. (4) - Generation of realistic synthetic reads by adding errors to mimic real reads. (5) - Production of a report with quality control values and plots calculated on the resulting synthetic reads.

"},{"location":"#contributing","title":"Contributing","text":"

Contributions are more than welcome. See the git repository

"},{"location":"#license","title":"License","text":"

AsaruSim is released under the GPL 3.0 license.

"},{"location":"#citations","title":"Citations","text":"

If you use AsaruSim in your research, please cite this manuscript:

Ali Hamraoui, Laurent Jourdren and Morgane Thomas-Chollier. AsaruSim: a single-cell and spatial RNA-Seq Nanopore long-reads simulation workflow. bioRxiv 2024.09.20.613625; doi: https://doi.org/10.1101/2024.09.20.613625

"},{"location":"#acknowledgements","title":"Acknowledgements","text":"

We would like to express our thanks to SLSim developers, which has been helpful to the AsaruSim workflow. Additionally, our thanks go to the teams behind Badread, SPARSim, and Trans-NanoSim whose tools are integral to the AsaruSim workflow.

"},{"location":"examples/","title":"Use example","text":""},{"location":"examples/#usage","title":"Usage","text":"

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 documentaion.

"},{"location":"examples/#examples","title":"EXAMPLES","text":""},{"location":"examples/#sample-data","title":"Sample data","text":"

A demonstration dataset to initiate this workflow is accessible on zenodo DOI : 10.5281/zenodo.12731408. This dataset is a subsample from a Nanopore run of the 10X 5k human pbmcs.

The human GRCh38 reference transcriptome, gtf annotation and fasta referance genome can be downloaded from Ensembl.

"},{"location":"examples/#basic-workflow","title":"BASIC WORKFLOW","text":"
 nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                      --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                      --features gene_name \\\n                      --gtf dataset/genes.gtf\n
"},{"location":"examples/#with-pcr-amplifiction","title":"WITH PCR AMPLIFICTION","text":"
 nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                      --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                      --features gene_name \\\n                      --gtf dataset/GRCh38-2020-A-genes.gtf \\\n                      --pcr_cycles 2 \\\n                      --pcr_dup_rate 0.7 \\\n                      --pcr_error_rate 0.00003\n
"},{"location":"examples/#with-simulated-cell-type-counts","title":"WITH SIMULATED CELL TYPE COUNTS","text":"
 nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                      --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                      --features gene_name \\\n                      --gtf dataset/GRCh38-2020-A-genes.gtf \\\n                      --sim_celltypes true \\\n                      --cell_types_annotation dataset/sub_pbmc_cell_type.csv\n
"},{"location":"examples/#with-personalized-error-model","title":"WITH PERSONALIZED ERROR MODEL","text":"
nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                     --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                     --features gene_name \\\n                     --gtf dataset/GRCh38-2020-A-genes.gtf \\\n                     --build_model true \\\n                     --fastq_model dataset/sub_pbmc_reads.fq \\\n                     --ref_genome dataset/GRCh38-2020-A-genome.fa \n
"},{"location":"examples/#complete-workflow","title":"COMPLETE WORKFLOW","text":"
 nextflow run main.nf --matrix dataset/sub_pbmc_matrice.csv \\\n                      --transcriptome dataset/Homo_sapiens.GRCh38.cdna.all.fa \\\n                      --features gene_name \\\n                      --gtf dataset/GRCh38-2020-A-genes.gtf \\\n                      --sim_celltypes true \\\n                      --cell_types_annotation dataset/sub_pbmc_cell_type.csv\n                      --build_model true \\\n                      --fastq_model dataset/sub_pbmc_reads.fq \\\n                      --ref_genome dataset/GRCh38-2020-A-genome.fa \n                      --pcr_cycles 2 \\\n                      --pcr_dup_rate 0.7 \\\n                      --pcr_error_rate 0.00003\n
"},{"location":"examples/#results","title":"Results","text":"

After execution, results will be available in the specified --outdir. This includes simulated Nanopore reads .fastq, along with log files and QC report.

"},{"location":"examples/#cleaning-up","title":"Cleaning Up","text":"

To clean up temporary files generated by Nextflow:

nextflow clean -f\n
"},{"location":"introduction/","title":"Install AsaruSim","text":"

This pipeline is powered by Nextflow workflow manager. All dependencies are automatically managed by Nextflow through a preconfigured Docker container, ensuring a seamless and reproducible installation process.

AsaruSim Github repository.

"},{"location":"introduction/#requirements","title":"Requirements","text":""},{"location":"introduction/#install-nextflow","title":"Install nextflow","text":"

Ensure you have the following installed on your system:

Java 8 or later: Nextflow requires Java. Install it from Oracle or use a package manager like apt, brew, or yum depending on your OS.

curl -s https://get.nextflow.io | bash\nchmod +x nextflow\nsudo mv nextflow /usr/local/bin/\n

Nextflow is now installed and ready to use on your system. For further details on using Nextflow, refer to the official documentation.

"},{"location":"introduction/#install-docker","title":"Install docker","text":"

Install Docker.

"},{"location":"introduction/#run-asarusim","title":"Run AsaruSim","text":" 
git clone https://github.com/GenomiqueENS/AsaruSim.git\n\ncd AsaruSim\n
nextflow run main.nf --help\n
"},{"location":"parameters/","title":"Input parameters","text":"

AsaruSim simulation requires input parameters, describing the macro characteristics of the desired synthetic reads.

"},{"location":"parameters/#count-matrix","title":"Count matrix","text":""},{"location":"parameters/#-matrix-csv-file","title":"--matrix csv file","text":"

Feature-by-cell (gene/cell or isoform/cell) count matrix in csv format, where rows represent the features (genes or transcripts) and columns represent cells (or spatial barcodes). The input matrix may be derived from an existing single-cell short- or long-read preprocessed run. this parameter is required.

AsaruSim require a feature name and GTF annotation for gene-per-cell matrix

Since the sequence names in the reference transcriptome correspond to transcript ids, it is necessary for users to specify the feature name within their matrix when gene-per-cell matrix is provided. Set the feature name using the --features parameter. Available options include:

Additionally, users are required to supply a gene annotation (.gtf format) file using the --gtf parameter.

"},{"location":"parameters/#-bc_counts-csv-file","title":"--bc_counts csv file","text":"

To simulate specific UMI counts per cell barcode with random transcripts, set the --bc_counts parameter to the path of a UMI counts .CSV file. This parameter eliminates the need for an input matrix, enabling the simulation of UMI counts where transcripts are chosed randomly.

example of UMI counts per CB file:

CB counts ACGGCGATCGCGAGCC 1260 ACGGCGATCGCGAGCC 1104"},{"location":"parameters/#-cell_types_annotation-csv-file","title":"--cell_types_annotation csv file","text":"

AsaruSim can generate synthetic count tables with varying cell types, differentially expressed genes, or isoforms. This capability is particularly useful for simulating count matrices that mimic the characteristics of existing cell populations. To simulate cell groups, AsaruSim requirs suplimentary parameters describing the characteristic of desired cell groups.

Requirements for simulating cell groups : AsaruSim use SPARSim R package to simulate synthetic count table. for each cell group to simulate, SPARSim needs 3 information as input:

fore more information see SPARSim vignettes.

AsaruSim allows user to estimate this characteristic from an existing count table. To do so, the user need to set --sim_celltypes parameter to true and to provide the list of cell barcodes of each group (.CSV file) using --cell_types_annotation parameter:

CB cell_type ACGGCGATCGCGAGCC type 1 ACGGCGATCGCGAGCC type 2

AsaruSim will then use the provided matrix to estimate characteristic of each cell groups and generate a synthetic count matrix.

"},{"location":"parameters/#template","title":"Template","text":"

AsaruSim generates reads that correspond to a 10X Genomics library construction coupled with Nanopore sequencing. The final construction corresponds to : an adaptor sequence composed of 10X and Nanopore adaptors, a cellular barcode (CB), UMI sequences at the same frequencies as in the synthetic count matrix, a 20 bp oligo(dT), the feature-corresponding cDNA sequence from the reference transcriptome and a template switch oligo (TSO) at the end.

"},{"location":"parameters/#-dt_length-int","title":"--dT_LENGTH INT","text":"

The mean length of the oligo(dT) tail sequence, assuming a normal distribution. (default : 15 bp).

"},{"location":"parameters/#-adapter_seq-str","title":"--ADAPTER_SEQ STR","text":"

Defines the sequence of the adapter used in the ONT and 10X Genomics libraries. By default, the 10X 3' solution V3 adapter sequence is used.

(default :ACTAAAGGCCATTACGGCCTACACGACGCTCTTCCGATCT).

"},{"location":"parameters/#-tso_seq-str","title":"--TSO_SEQ STR","text":"

Specifies the sequence of the Template Switching Oligo (TSO) nucleotid.

(default :TGTACTCTGCGTTGATACCACTGCTT).

"},{"location":"parameters/#-full_length-bool","title":"--full_length BOOL","text":"

Simulate untruncated reads. (default :false).

"},{"location":"parameters/#-truncation_model-csv-file","title":"--truncation_model csv file","text":"

Truncation probability distribution. Automatically generated when the --build_model option is enabled. (default :bin/models/truncation_default_model.csv)

"},{"location":"parameters/#-unspliced_ratio-float","title":"--unspliced_ratio FLOAT","text":"

The percentage of unspliced reads to simulate. (default :0.0).

"},{"location":"parameters/#-intron_retention-bool","title":"--intron_retention BOOL","text":"

Enable simulation of intron retention events. If enabled, a reference genome must be provided using the --ref_genome option. (default :false)

"},{"location":"parameters/#-ir_model-csv-file","title":"--ir_model csv file","text":"

Markov model of Intron Retention events. This can be generated using the Nanosim module model_intron_retention.py. (default :bin/models/SC3pv3_GEX_Human_IR_markov_model)

AsaruSim requires both a reference genome and a GTF annotation to simulate intron retention events and unspliced transcripts

To simulate intron retention events (--intron_retention) and unspliced transcripts (--unspliced_ratio), you must provide a reference genome in FASTA format. Additionally, a GTF annotation file containing intron coordinate information is required, which can be generated using the AGAT tool:\\

 conda install -c bioconda agat\nagat_sp_add_introns.pl --gff genes.sorted.gtf -o genes.sorted.intron.gff

"},{"location":"parameters/#reference-transcripts","title":"Reference transcripts","text":"

The feature-corresponding cDNA sequence is sampled from the reference transcriptome or reference genome for unsplaced and intron retained transcripts.

"},{"location":"parameters/#-transcriptome-fasta-file","title":"--transcriptome FASTA file","text":"

A reference transcriptome file in .fasta format can be downloaded from Ensembl.

"},{"location":"parameters/#-length_dist-str","title":"--length_dist STR","text":"

To mimic the real read length distribution when a gene expression matrix is provided, a realistic read length distribution is achieved by selecting a random cDNA of the corresponding gene, with a prior probability favoring short-length cDNA.

AsaruSim estimates this read length using a log-normal distribution. Users may provide their parameters to personalize the distribution using three comma-delimited values (shape, location, scale) with the parameter --length_dist. (default :0.37,0.0,825)

Fit read distribution of real reads

Users may also fit their real reads distribution with this approach by providing a subset of real reads (in .FASTQ format) using the --model_fastq parameter. (See also build model in the Error model section)

"},{"location":"parameters/#-ref_genome-fasta-file","title":"--ref_genome FASTA file","text":"

The reference genome file in .fasta format can be downloaded from Ensembl.

"},{"location":"parameters/#pcr-amplification","title":"PCR amplification","text":"

AsaruSim take into account the bias of PCR amplification introduced during library constructions process. The PCR amplification is simulated by replicating the synthetic reads at each cycle, with a capturing probabily and un error rate.

"},{"location":"parameters/#-pcr_cycles-int","title":"--PCR_cycles INT","text":"

The number of PCR cycles to simulate. During each cycle, the reads are duplicated exponentially, following the formula: $$\\ N = N_0 \\times (1 + E)^{C} \\ $$

where: N is the final number of reads, N0 is the initial number of reads, E is the efficiency rate, and C is the number of cycles.

"},{"location":"parameters/#-pcr_efficiency-float","title":"--PCR_efficiency FLOAT","text":"

The efficiency rate of duplication is fixed by the user (default: --PCR_efficiency 0.9)

"},{"location":"parameters/#-pcr_error_rate-float","title":"--PCR_error_rate FLOAT","text":"

The probability to be mutated during the process for each nucleotide in the duplicated read. The error rate is also fixed by the user (default: --PCR_error_rate 3.5e-05)

"},{"location":"parameters/#-total_reads-int","title":"--total_reads INT","text":"

Number of total reads to random subset from the resulting artificial PCR product, to mimic the experimental protocol where only a subset of the sample is used for the sequencing step.

Users can use amplification rate instead of PCR amplification

Inspired by SLSim, the amplification rate allows users to repeat each template read a specified number of times. This is a simpler way to simulate amplification with: $$\\ x \\sim \\text{Poi}(\\text{amp_rate}) \\ $$ The value of x is set by the user using --amp_rate

"},{"location":"parameters/#error-model","title":"Error model","text":"

AsaruSim uses the Badread Python library to simulate nanopore sequencing errors and assign per-base quality scores based on pre-trained error models (see Badread documentation for more information). To do so, AsaruSim requires:

"},{"location":"parameters/#-trained_model-str","title":"--trained_model STR

This allows the user to choose one of the built-in error models within the Badread database. The possible values are:

nanopore2023: a model trained on ONT R10.4.1 reads from 2023 (the default). nanopore2020: a model trained on ONT R9.4.1 reads from 2020. nanopore2018: a model trained on ONT R9.4/R9.4.1 reads from 2018. random: a random error model with a 1/3 chance each of insertion, deletion, and substitution. a file path for a trained model.

","text":""},{"location":"parameters/#-badread_identity-str","title":"--badread_identity STR

Badread uses the Beta distribution to sample read identities. The distribution is defined with three parameters: mean, standard deviation, and maximum value. To pass these parameters to AsaruSim, use three comma-delimited values (identity mean, max, stdev). default : --badread_identity 95,99,2.5.

","text":""},{"location":"parameters/#-build_model-bool","title":"--build_model BOOL

To internally train a personalized read identity, Qscore, and error models, AsaruSim requires a real FASTQ read file that can be provided using --model_fastq. The user can choose the model to estimate sequence identity with the --identity_model option, which includes three possible identity models, either including or excluding gaps. By default, the \"Gap-Excluded Identity\" model is used.

AsaruSim also accepts pre-built model files

Users can use --error_model and --qscore_model to provide Badread pre-built models in file format.

","text":""}]} \ No newline at end of file