From 15075e242120c56a2e428092d672e223f0d0a4e8 Mon Sep 17 00:00:00 2001 From: ChrisKent Date: Thu, 4 Sep 2025 12:30:18 +0100 Subject: [PATCH 1/2] 1.0.0 --- docs/api.md | 11 +++++--- docs/how-to-guides.md | 2 +- docs/index.md | 65 +++++++++++++++++++++++++++++++++++++++++-- mkdocs.yml | 2 +- pyproject.toml | 2 +- uv.lock | 2 +- 6 files changed, 74 insertions(+), 10 deletions(-) diff --git a/docs/api.md b/docs/api.md index bd941f7..c992f10 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,4 +1,9 @@ +::: primalbedtools.scheme + options: + heading: "Scheme" + toc_label: "Scheme" + ::: primalbedtools.bedfiles options: heading: "Bedfiles" @@ -6,7 +11,5 @@ ::: primalbedtools.amplicons options: - heading: "amplicons" - toc_label: "amplicons" - -::: primalbedtools.scheme \ No newline at end of file + heading: "Amplicons" + toc_label: "Amplicons" diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md index bf441f0..0d21339 100644 --- a/docs/how-to-guides.md +++ b/docs/how-to-guides.md @@ -97,7 +97,7 @@ ValueError: Invalid amplicon_prefix: (test_invalid). Must be alphanumeric or hyp During development of primer.bed files multiple versions have been used. -The current version (v2) uses a primername in the form of `{amplicon_prefix}_{amplicon_number}_{strand}_{primer_number}` (eg `SARS-CoV-2_1_RIGHT_1`). +The current version (**v3**) uses a primername in the form of `{amplicon_prefix}_{amplicon_number}_{strand}_{primer_number}` (eg `SARS-CoV-2_1_RIGHT_1`). The old form typically used `{amplicon_prefix}_{amplicon_number}` or `{amplicon_prefix}_{amplicon_number}_alt1` (eg `SARS-CoV-2_1_RIGHT` | `SARS-CoV-2_1_RIGHT_alt`) to represent multiple primers for a site. diff --git a/docs/index.md b/docs/index.md index 7f0aff1..5288170 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,32 @@ -# Primalbedtools! +# Quick start -This is a low dependency python library for the validation of primerschemes! Mainly the primer.bed and the reference.fasta files. +## Summary +Primalbedtools is no dependency python library for the validation of primerschemes files (primer.bed + reference.fasta). It has been designed to carry out validation, common operation and file reading / writing. +## History +Over the years, the file that describes the primers for amplicon sequencing has undergone a lot of changes. However, they typically are text files, which each line representing a single primer in the PCR reaction. + +The initial version (informally **v1**) was utilised in 2016 to 2018, had 6 columns to describe the location of the primer but did not include the primer sequence. + +!!! warning "**v1** is now fully depreciated. We view primers sequences essential for reproducibility and therefore they are required" + +The next iteration (informally **v2**) added a 7th column which contained the primer sequence. It also provided some structure for __primerName__ (unique identifier for each primer in 4th column) `{schemeName|uuid}_{ampliconNumber}_{LEFT|RIGHT}` and an optional `{_alt}` to denote spike in primers. + +!!! info "**v2** has been superseded and should be updated to **v3**. For legacy uses `primalbedtools` can happily parse **v2** and even convert to **v3**" + +The current generation (**v3.0.0**) has been formalised (see [here](https://github.com/artic-network/primerscheme-specs/blob/20816ff7cd53bdfaab7a605dee06de1c80be759f/pdf/primerscheme.pdf) for detailed specification) but to briefly summarise; + +- Probe based qPCR assays can be described with the `PROBE` class + +- Comment lines starting with `#` are supported + +- An optional 8th col can include primer key-value metadata. For example a primer's gc content and score (ps) could be encoded as `gc=0.60;ps=100` + +- primerNames must be in the form `{schemeName|uuid}_{ampliconNumber}_{LEFT|RIGHT|PROBE}_{primerNumber}` + +!!! info "**v3** is the current file format. Most of ARTICnetwork's tools expect **v3** primer.bed files, but most use primalbedtools and hence should be able to use **v2**" + ## Installation Install primalbedtools using pip: @@ -26,3 +50,40 @@ uv sync uv run primalbedtools ``` +## Example bedfile + +Here is a example bedfile, slightly modified for easy viewing. +``` +# chrom start end primername pool strand sequence primerAttributes +MN908947.3 47 78 SARS-CoV-2_1_LEFT_1 1 + CTCTTGTAGATCTT... pw=1.0;ps=100 +MN908947.3 419 447 SARS-CoV-2_1_RIGHT_1 1 - AAAACGCCTTTCAA... pw=0.8;ps=90 +MN908947.3 344 366 SARS-CoV-2_2_LEFT_0 2 + TCGTACGTCTTTGG... pw=1.0;ps=105 +MN908947.3 707 732 SARS-CoV-2_2_RIGHT_0 2 - TCTTCAAGGATCAG... pw=1.2;ps=104 +``` + +In primalbedtools each primer is represented by a BedLine object (see BedLine section for detailed docs). + +The BedLine provides access to all expected fields. +```python +>>> bl.primername +'SARS-CoV-2_1_LEFT_1' +>>> bl.sequence +'CTCTTGTAGATCTGTTCTCTAAACGAACTTT' +>>> bl.attributes +{'pw': 1.0, 'ps': '100'} +``` + +Alongside some calculated ones. +```python +>>> bl.length +31 +>>> bl.primer_class_str +'LEFT' +>>> bl.amplicon_number +1 +>>> bl.primer_suffix +1 +>>> bl.ipool +0 +``` + diff --git a/mkdocs.yml b/mkdocs.yml index 16e1c25..313303e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,7 +20,7 @@ markdown_extensions: - admonition nav: - - primalbedtools: index.md + - Quick Start: index.md - How To Guides: how-to-guides.md - Command Line Interface: cli.md - API: api.md diff --git a/pyproject.toml b/pyproject.toml index 13a504f..9cd9a95 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "primalbedtools" -version = "0.11.1" +version = "1.0.0" description = "A collection of tools for working with primer.bed files" authors = [{ name = "ChrisKent", email = "chrisgkent@gmail.com" }] requires-python = ">=3.9, <4" diff --git a/uv.lock b/uv.lock index 4523def..f7dd70a 100644 --- a/uv.lock +++ b/uv.lock @@ -596,7 +596,7 @@ wheels = [ [[package]] name = "primalbedtools" -version = "0.11.1" +version = "1.0.0" source = { editable = "." } [package.dev-dependencies] From 158e292eecba09a45e4f71f73eec99b9848fb342 Mon Sep 17 00:00:00 2001 From: ChrisKent Date: Thu, 4 Sep 2025 12:30:18 +0100 Subject: [PATCH 2/2] 1.0.0 --- docs/reference.md | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100644 docs/reference.md diff --git a/docs/reference.md b/docs/reference.md deleted file mode 100644 index 4f13727..0000000 --- a/docs/reference.md +++ /dev/null @@ -1,10 +0,0 @@ - -::: primalbedtools.bedfiles - options: - heading: "Bedfiles" - toc_label: "Bedfiles" - -::: primalbedtools.primerpairs - options: - heading: "PrimerPairs" - toc_label: "PrimerPairs" \ No newline at end of file