Skip to content

1.0.0 #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChrisgKent merged 2 commits into from
Sep 4, 2025
Merged

1.0.0 #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15075e2
1.0.0
ChrisgKent Sep 4, 2025
158e292
1.0.0
ChrisgKent Sep 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@

::: primalbedtools.scheme
options:
heading: "Scheme"
toc_label: "Scheme"

::: primalbedtools.bedfiles
options:
heading: "Bedfiles"
toc_label: "Bedfiles"

::: primalbedtools.amplicons
options:
heading: "amplicons"
toc_label: "amplicons"

::: primalbedtools.scheme
heading: "Amplicons"
toc_label: "Amplicons"
2 changes: 1 addition & 1 deletion docs/how-to-guides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
65 changes: 63 additions & 2 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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
```

10 changes: 0 additions & 10 deletions docs/reference.md
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion uv.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.