{"id":38676571,"url":"https://github.com/wglab/ampbinner","last_synced_at":"2026-01-17T10:01:17.170Z","repository":{"id":81512131,"uuid":"246922521","full_name":"WGLab/AmpBinner","owner":"WGLab","description":"A barcode demultiplexer for Oxford Nanopore long-read amplicon sequencing data","archived":false,"fork":false,"pushed_at":"2024-11-27T05:04:07.000Z","size":197,"stargazers_count":10,"open_issues_count":4,"forks_count":2,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-27T06:20:23.384Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WGLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2020-03-12T20:13:19.000Z","updated_at":"2024-11-27T05:04:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"379500d8-16f6-4f71-ab36-2b385882c64e","html_url":"https://github.com/WGLab/AmpBinner","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/WGLab/AmpBinner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FAmpBinner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FAmpBinner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FAmpBinner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FAmpBinner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WGLab","download_url":"https://codeload.github.com/WGLab/AmpBinner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FAmpBinner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28505570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: 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":[],"created_at":"2026-01-17T10:01:16.409Z","updated_at":"2026-01-17T10:01:17.156Z","avatar_url":"https://github.com/WGLab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AmpBinner: An anchor-assisted demultiplexing tool for Oxford Nanopore long-read amplicon sequencing data. \n\n## Features\n- AmpBinner uses the sequence upstream/downstream of the barcode (i.e. anchor) to help locate barcode position and eliminates random matching due to sequencing error.\n- AmpBinner does not require a pretrained model for demultiplexing and supports officially provided barcodes as well as custom-designed barcodes.\n- AmpBinner is able to demultiplex Oxford Nanopore sequencing data generated from **10X Genomics Chromium Single Cell 3ʹ Gene Expression Libraries**. \n\n## Table of Contents\n\n- [Requirements](#Requirements)\n- [Installation](#Installation)\n- [Usage](#Usage)\n  - [Quick start](#Quick_start)\n  - [Demultiplexing regular amplicons](#Demultiplexing_regular_amplicons)\n    - [Case 1: The barcode is next to the forward primer](#case1)\n    - [Case 2: The barcode is next to the reverse primer](#case2)\n    - [Case 3: The barcodes are on both ends. One sample have the same barcodes on both ends. Only one barcode is required to bin the reads.](#case3)\n    - [Case 4: The barcodes are on both ends. One sample may or may not have the same barcodes on both ends. Two barcodes are required to bin the reads.](#case4)\n  - [Demultiplexing 10X Genomics Chromium Single Cell 3ʹ Gene Expression Libraries](#tenx)\n\n\n## \u003ca name=\"Requirements\"\u003e\u003c/a\u003eRequirements\n- Operating system: Linux or macOS\n- [Python](https://www.python.org/) 2.7 or later\n- [minimap2](https://github.com/lh3/minimap2) 2.8 or later\n\n## \u003ca name=\"Installation\"\u003e\u003c/a\u003eInstallation\n\nAmpBinner calls `minimap2` to do sequence alignment. If you don't have `minimap2` in your system, you can install it following the instructions [here](https://github.com/lh3/minimap2#install).  \nIf you are using Linux, you can acquire precompiled binaries using the following commands:\n\n```\nwget https://github.com/lh3/minimap2/releases/download/v2.17/minimap2-2.17_x64-linux.tar.bz2\ntar -jxvf minimap2-2.17_x64-linux.tar.bz2\n./minimap2-2.17_x64-linux/minimap2\n```\n\nNext, you can clone the repository of AmpBinner using the following command.\n```\ngit clone https://github.com/WGLab/AmpBinner.git\n```\nThe scripts in the `./AmpBinner` can run directly without additional compilation or installation.\n\n## \u003ca name=\"Usage\"\u003e\u003c/a\u003eUsage\n\nThere are two script files in the `AmpBinner` directory. `ampBinner_10X.py` is used to demultiplex Oxford Nanopore sequencing data derived from 10X Genomics Chromium single cell libraries. There are usually several thousands of barcodes per sample.  `ampBinner.py` is for regular barcoding methods, including barcoding kits provided by Oxford Nanopore Technologies and custom-designed barcodes.\n\n### \u003ca name=\"Quick_start\"\u003e\u003c/a\u003e Quick start\n\n```\n# The barcode is beside forward primer\npath/to/AmpBinner/ampBinner.py --in_fq example_data.fastq.gz --amp_seq_fasta example_amplicon_seq.fasta --out_dir . --exp_name testing --num_threads 4 --fwd_barcode_fasta example_barcodes.fasta --minimap2 path/to/minimap2\n\n# The barcode is beside reverse primer\npath/to/AmpBinner/ampBinner.py --in_fq example_data.fastq.gz --amp_seq_fasta example_amplicon_seq.fasta --out_dir . --exp_name testing --num_threads 4 --rev_barcode_fasta example_barcodes.fasta --minimap2 path/to/minimap2\n\n# The barcodes are on both ends. One sample have the same barcodes on both ends. Only one barcode is required to bin the reads.\npath/to/AmpBinner/ampBinner.py --in_fq example_data.fastq.gz --amp_seq_fasta example_amplicon_seq.fasta --out_dir . --exp_name testing --num_threads 4 --fwd_barcode_fasta example_barcodes.fasta --rev_barcode_fasta example_barcodes.fasta --minimap2 path/to/minimap2\n\n# The barcodes are on both ends. One sample may or may not have the same barcodes on both ends. Two barcodes are required to bin the reads.\npath/to/AmpBinner/ampBinner.py --in_fq example_data.fastq.gz --amp_seq_fasta example_amplicon_seq.fasta --out_dir . --exp_name testing --num_threads 4 --fwd_barcode_fasta example_barcodes.fasta --rev_barcode_fasta example_barcodes.fasta --require_two_barcodes --minimap2 path/to/minimap2\n\n# Input DNA is from a 10X Genomics single cell library\n/home/fangl/AmpBinner/ampBinner_10X.py --in_fq example.fastq.gz --barcode_list barcodes.txt --barcode_upstream_seq AATGATACGGCGACCACCGAGATCTACACTCTTTCCCTACACGACGCTCTTCCGATCT --out_prefix testing --num_threads 8 \n```\n\n### \u003ca name=\"Demultiplexing_regular_amplicons\"\u003e\u003c/a\u003e Demultiplexing regular amplicons\n\n```\n$ ./ampBinner.py --help \nusage: ampBinner.py [-h] [--in_fq FILE] [--in_fq_list FILE] --amp_seq_fasta\n                    FILE --out_dir PATH --exp_name STRING\n                    [--fwd_barcode_fasta FILE] [--rev_barcode_fasta FILE]\n                    [--require_two_barcodes] [--num_threads INT]\n                    [--minimap2 FILE] [--version]\n\nA barcode demultiplexer for Oxford Nanopore long-read sequencing data\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --in_fq FILE          input sequencing reads in one FASTQ(.gz) file\n  --in_fq_list FILE     a list file specifying all input FASTQ(.gz) files, one\n                        file per line\n  --amp_seq_fasta FILE  reference amplicon sequence in FASTA format\n  --out_dir PATH        output directory\n  --exp_name STRING     experimental name, used as prefix of output files\n  --fwd_barcode_fasta FILE\n                        barcode sequences of the forward primer (in FASTA\n                        format)\n  --rev_barcode_fasta FILE\n                        barcode sequences of the reverse primer (in FASTA\n                        format)\n  --require_two_barcodes\n                        require matched barcodes on both ends (default:\n                        False). Notice: this option is valid only if both '--\n                        fwd_barcode_fasta' and '--rev_barcode_fasta' are\n                        supplied.\n  --num_threads INT     number of threads (default: 1)\n  --minimap2 FILE       path to minimap2 (default: using environment default)\n  --version             show program's version number and exit\n\n```\nIf you have one single input fastq file, you can supply the input with `--in_fq`. \nIf you have multiple fastq files, you can supply a list file with `--in_fq_list`. The list file contains all input fastq files, one file per line. \n\n`--amp_seq_fasta` is the reference amplicon sequence in FASTA format. Sometimes the barcode sequence is not at the very begining of the long read. Sometimes the first a few bases of a read is truncated. Due to the sequencing error, the barcode matching is flexible and allows some mismatches. **`ampBinner.py` assumes the reference amplicon sequence is known and uses it to distinguish amplicon sequence and barcode sequence, thus eliminates random fuzzy matching inside the amplicon.** \n\n`--fwd_barcode_fasta` and `--rev_barcode_fasta` are barcode sequences in FASTA format. If you use the same barcodes on both ends, you can supply `--fwd_barcode_fasta` and `--rev_barcode_fasta` with the same file. An example of `--fwd_barcode_fasta` is shown below. We supplied FASTA files of official barcodes in the `AmpBinner/ONT_barcodes` folder.  \n\n```\n\u003eBC01\nCACAAAGACACCGACAACTTTCTT\n\u003eBC02\nACAGACGACTACAAACGGAATCGA\n\u003eBC03\nCCTGGTAACTGGGACACAAGACTC\n\u003eBC04\nTAGGGAAACACGATAGAATCCGAA\n\u003eBC05\nAAGGTTACACAAACCCTGGACAAG\n```\n\n`ampBinner.py` supports different barcoding strategies.  \n#### \u003ca name=\"case1\"\u003e\u003c/a\u003e Case 1. The barcode is next to the forward primer\n\nIn this case, the amplicon structure is shown below. \n\u003cp align=\"center\"\u003e\u003cimg src=\"images/fwd_only.png\" width=\"100%\"\u003e\u003c/p\u003e\n\nYou can use the `--fwd_barcode_fasta` argument to supply the barcode FASTA file and use the `--amp_seq_fasta` argument to supply reference amplicon FASTA file. Please note that **the `--amp_seq_fasta` file should INCLUDE the primer sequence but EXCLUDE the barcode sequence**.  An example command is shown below: \n\n```\n/home/fangl/AmpBinner/ampBinner.py --in_fq example_data.fastq.gz --amp_seq_fasta example_amplicon_seq.fasta --out_dir . --exp_name testing --num_threads 4 --fwd_barcode_fasta example_barcodes.fasta --minimap2 /home/fangl/software/minimap2-2.8_x64-linux/minimap2\n```\n\n#### \u003ca name=\"case2\"\u003e\u003c/a\u003e Case 2. The barcode is next to the reverse primer\nIn this case, the amplicon structure is shown below. \n\u003cp align=\"center\"\u003e\u003cimg src=\"images/rev_only.png\" width=\"100%\"\u003e\u003c/p\u003e\n\nSimilar to case 1, you can use the `--rev_barcode_fasta` argument to supply the barcode FASTA file and use the `--amp_seq_fasta` argument to supply reference amplicon FASTA file. Please note that **the `--amp_seq_fasta` file should INCLUDE the primer sequence but EXCLUDE the barcode sequence**.  An example command is shown below: \n\n```\n/home/fangl/AmpBinner/ampBinner.py --in_fq example_data.fastq.gz --amp_seq_fasta example_amplicon_seq.fasta --out_dir . --exp_name testing --num_threads 4 --rev_barcode_fasta example_barcodes.fasta --minimap2 /home/fangl/software/minimap2-2.8_x64-linux/minimap2\n```\n\n#### \u003ca name=\"case3\"\u003e\u003c/a\u003e Case 3. The barcodes are on both ends. One sample have the same barcodes on both ends. Only one barcode is required to bin the reads.\nThis might be the most common case. In this case, the amplicon structure is shown below. \n\u003cp align=\"center\"\u003e\u003cimg src=\"images/both_sides.png\" width=\"100%\"\u003e\u003c/p\u003e\n\nYou can supply `--fwd_barcode_fasta` and `--rev_barcode_fasta` with the same file, and use the `--amp_seq_fasta` argument to supply reference amplicon FASTA file. Please note that **the `--amp_seq_fasta` file should INCLUDE the primer sequence but EXCLUDE the barcode sequence**.  An example command is shown below: \n\n```\n/home/fangl/AmpBinner/ampBinner.py --in_fq example_data.fastq.gz --amp_seq_fasta example_amplicon_seq.fasta --out_dir . --exp_name testing --num_threads 4 --fwd_barcode_fasta example_barcodes.fasta --rev_barcode_fasta example_barcodes.fasta --minimap2 /home/fangl/software/minimap2-2.8_x64-linux/minimap2\n```\n\n#### \u003ca name=\"case4\"\u003e\u003c/a\u003e Case 4. The barcodes are on both ends. One sample may or may not have the same barcodes on both ends. Two barcodes are required to bin the reads.\nThis might be the most common case. In this case, the amplicon structure is shown below. \n\u003cp align=\"center\"\u003e\u003cimg src=\"images/both_sides.png\" width=\"100%\"\u003e\u003c/p\u003e\n\nYou can supply `--fwd_barcode_fasta` and `--rev_barcode_fasta` with the barcode FASTA file. The `--fwd_barcode_fasta` and `--rev_barcode_fasta` file may or may not be the same. **You want to use the `--require_two_barcodes` option to specify that two barcodes are required to bin the reads.**  You can use the `--amp_seq_fasta` argument to supply reference amplicon FASTA file. Please note that **the `--amp_seq_fasta` file should INCLUDE the primer sequence but EXCLUDE the barcode sequence**.  An example command is shown below: \n\n```\n/home/fangl/AmpBinner/ampBinner.py --in_fq example_data.fastq.gz --amp_seq_fasta example_amplicon_seq.fasta --out_dir . --exp_name testing --num_threads 4 --fwd_barcode_fasta example_barcodes.fasta --rev_barcode_fasta example_barcodes.fasta --require_two_barcodes --minimap2 /home/fangl/software/minimap2-2.8_x64-linux/minimap2\n```\n\n### \u003ca name=\"tenx\"\u003e\u003c/a\u003e Demultiplexing 10X Genomics Chromium Single Cell 3ʹ Gene Expression Libraries\nA 10X Genomics Chromium Single Cell 3ʹ Gene Expression Library often has several thousands of cellular barcodes. AmpBinner uses the sequence upstream of the barcode to help locate barcode position and eliminates random matching due to sequencing error. We provided a separate script file `ampBinner_10X.py` for 10X single cell libraries. The structure of the 10X Genomics single cell library is shown below. \n\u003cp align=\"center\"\u003e\u003cimg src=\"images/10X_lib.png\" width=\"100%\"\u003e\u003c/p\u003e\n\n```\n$ ./ampBinner_10X.py --help \nusage: ampBinner_10X.py [-h] [--in_fq FILE] [--in_fq_list FILE] --barcode_list\n                        FILE --barcode_upstream_seq STRING --out_prefix PATH\n                        [--num_threads INT] [--minimap2 FILE] [--version]\n\nA barcode demultiplexer for Oxford Nanopore long-read sequencing data with 10X\nGenomics Chromium barcodes\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --in_fq FILE          input sequencing reads in one FASTQ(.gz) file\n  --in_fq_list FILE     a list file specifying all input FASTQ(.gz) files, one\n                        file per line\n  --barcode_list FILE   a list file of all barcode sequences, one barcode\n                        sequence per line, no barcode name\n  --barcode_upstream_seq STRING\n                        known upstream sequence of the barcode\n  --out_prefix PATH     prefix of output files\n  --num_threads INT     number of threads (default: 1)\n  --minimap2 FILE       path to minimap2 (default: using environment default)\n  --version             show program's version number and exit\n```\n\nIf you have one single input fastq file, you can supply the input with `--in_fq`. \nIf you have multiple fastq files, you can supply a list file with `--in_fq_list`. The list file contains all input fastq files, one file per line. \n\nThe barcode upstream sequence can be supplied with the `--barcode_upstream_seq` argument. It can be either the TruSeq Read1 sequence or the concatenation of the P5 sequence and the TruSeq Read1 sequence. \n\nThe barcode list file is supplied via the `--barcode_list` argument. The barcode list file should contain all barcodes of the specific sample, one barcode sequence per line (No barcode name). An example of the barcode list file is shown below. \n\n\n```\nAAACCCACACATCATG\nAAACCCACATCATTGG\nAAACCCAGTAGTTCCA\nAAACCCAGTCGTTATG\nAAACCCAGTGCGGATA\nAAACCCAGTTCTTAGG\nAAACCCATCATGAGTC\nAAACCCATCTACTCAT\nAAACGAAAGGTAGTAT\nAAACGAACAACCCTAA\n```\n\nAn example command is: \n\n```\n/home/fangl/AmpBinner/ampBinner_10X.py --in_fq example.fastq.gz --barcode_list barcodes.txt --barcode_upstream_seq AATGATACGGCGACCACCGAGATCTACACTCTTTCCCTACACGACGCTCTTCCGATCT --out_prefix testing --num_threads 8 \n```\n\n`ampBinner_10X.py` will generate 3 files: `testing.demultiplexing.PASS.reads.txt`, `testing.demultiplexing.statistics.txt` and `testing.all_reads.txt`.\n\n`testing.demultiplexing.PASS.reads.txt` contains the barcodes of QC-passed reads. \n`testing.all_reads.txt` contains the barcodes of all reads (including QC-passed and QC-failed reads). \n`testing.demultiplexing.statistics.txt` is a summary file with number of reads per barcode. \n\n#### Limitation\n`ampBinner_10X.py` has been tested samples with less than 10,000 barcodes. You'd better have a short-read 10X Genomics sequencing data so that you can narrow down the barcode list to a few thousand. `ampBinner_10X.py` will not work well on a large barcode list (e.g. the complete barcode list which has \u003e 1 million barcodes).  \n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwglab%2Fampbinner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwglab%2Fampbinner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwglab%2Fampbinner/lists"}