# palamedes
   
This repo contains a python package and CLI entrypoint which can be used to generate a list of [HGVS](https://github.com/biocommons/hgvs) variants representing the difference between 2 sequences, using a global alignment. The idea is to leverage the HGVS spec for more applications, since it provides a solid framework for maintaining a consistent set of rules and logic
around variants.
## Documentation
Documentation for the project can be found [here](https://mammothbio-os-palamedes.readthedocs.io/en/stable/)
## Installing
Palamedes uses the [hgvs](https://github.com/biocommons/hgvs) package as a dependency. At this time, `hgvs` requires `postgresql` system dependencies to be installed before use. Please see the [README](https://github.com/biocommons/hgvs/blob/main/README.md#installing-hgvs-locally) for install instructions if needed.
Palamedes itself is packaged in PyPI, to install simply run: `pip install palamedes`
## Usage - CLI
Palamedes includes a CLI entrypoint, which is mostly useful for debugging and exploration. Once installed, simply run `palamedes` and provide a reference and alternate sequence:
```shell
palamedes PFKISIHL TPFKISIH
[2024-03-25 11:40:59,904] {cli.py:39} INFO - Running with args: Namespace(ref='PFKISIHL', alt='TPFKISIH', molecule_type='protein')
[2024-03-25 11:40:59,906] {align.py:179} INFO - Found 2 alignments with max score, returning last in the list (3\' end rule)
[2024-03-25 11:40:59,907] {cli.py:45} INFO - Found best alignment with score = 5.0
[2024-03-25 11:40:59,909] {cli.py:46} INFO - Alignment:
ref 0 -PFKISIHL 8
0 -|||||||- 9
alt 0 TPFKISIH- 8
[2024-03-25 11:40:59,909] {cli.py:49} INFO - 2 Variant blocks generated
[2024-03-25 11:40:59,909] {cli.py:54} INFO - VariantBlock(alignment_block=Block(start=0, end=1, bases='i'), reference_blocks=[], alternate_blocks=[Block(start=0, end=1, bases='T')]), categorized as: extension
[2024-03-25 11:40:59,910] {cli.py:57} INFO - As HGVS: ref:p.Pro1extThr-1
[2024-03-25 11:40:59,910] {cli.py:54} INFO - VariantBlock(alignment_block=Block(start=8, end=9, bases='d'), reference_blocks=[Block(start=7, end=8, bases='L')], alternate_blocks=[]), categorized as: deletion
[2024-03-25 11:40:59,910] {cli.py:57} INFO - As HGVS: ref:p.Leu8del
```
## Usage - Python
Palamedes currently includes a single public function that provides the alignment to HGVS functionality. All other functions should
be treated as internal and private. No assurances are offered for their consistency and functionality from version to version. The function accepts either raw sequences or biopython `SeqRecord` objects.
```python
>>> from Bio.Seq import Seq
>>> from Bio.SeqRecord import SeqRecord
>>> from palamedes import generate_hgvs_variants
# using raw strings
>>> generate_hgvs_variants("PFKISIHL", "TPFKISIH")
[
SequenceVariant(ac=ref, type=p, posedit=Pro1extThr-1, gene=None),
SequenceVariant(ac=ref, type=p, posedit=Leu8del, gene=None),
]
# using SeqRecord objects, note the molecule_type annotation must be provided and set to a supported type
# protein is the default and only supported option at this time
>>> ref = SeqRecord(Seq("PFKISIHL"), id="Jelleine-I", annotations={"molecule_type": "protein"})
>>> alt = SeqRecord(Seq("TPFKISIH"), id="Jelleine-IV", annotations={"molecule_type": "protein"})
>>> generate_hgvs_variants(ref, alt)
[
SequenceVariant(ac=Jelleine-I, type=p, posedit=Pro1extThr-1, gene=None),
SequenceVariant(ac=Jelleine-I, type=p, posedit=Leu8del, gene=None)
]
```
The `generate_hgvs_variants` also accepts a pre-built biopython `PairwiseAligner` instance to give the caller more control of the alignment parameters via the `aligner` keyword argument. The default settings are:
- mode: "global" (note this must be set to global on a custom aligner to ensure and end to end alignment)
- match_score: 1
- mismatch_score: -1
- open_gap_score: -1
- extend_gap_score: -0.1
## Name
The package is named after [Palamedes](https://en.wikipedia.org/wiki/Palamedes_(mythology)), a figure from Greek mythology. Palamedes was associated with the invention of the Greek letters and alphabet as well as with the invention of dice. Palamedes dedicated the first set of dice to the Greek goddess Tyche, who was the goddess of chance and randomness.
Raw data
{
"_id": null,
"home_page": "https://github.com/mammothbio-os/palamedes",
"name": "palamedes",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "bioinformatics, alignment, hgvs, variant, amino acid",
"author": null,
"author_email": "open-source@mammothbiosci.com",
"download_url": "https://files.pythonhosted.org/packages/6b/86/b0066de55d7e642771965f14bfc7a155b29153f66f84d28888d3f696a90c/palamedes-0.0.8.tar.gz",
"platform": null,
"description": "# palamedes\n\n   \n\nThis repo contains a python package and CLI entrypoint which can be used to generate a list of [HGVS](https://github.com/biocommons/hgvs) variants representing the difference between 2 sequences, using a global alignment. The idea is to leverage the HGVS spec for more applications, since it provides a solid framework for maintaining a consistent set of rules and logic\naround variants.\n\n## Documentation\n\nDocumentation for the project can be found [here](https://mammothbio-os-palamedes.readthedocs.io/en/stable/)\n\n## Installing\n\nPalamedes uses the [hgvs](https://github.com/biocommons/hgvs) package as a dependency. At this time, `hgvs` requires `postgresql` system dependencies to be installed before use. Please see the [README](https://github.com/biocommons/hgvs/blob/main/README.md#installing-hgvs-locally) for install instructions if needed.\n\nPalamedes itself is packaged in PyPI, to install simply run: `pip install palamedes`\n\n## Usage - CLI\n\nPalamedes includes a CLI entrypoint, which is mostly useful for debugging and exploration. Once installed, simply run `palamedes` and provide a reference and alternate sequence:\n```shell\npalamedes PFKISIHL TPFKISIH\n[2024-03-25 11:40:59,904] {cli.py:39} INFO - Running with args: Namespace(ref='PFKISIHL', alt='TPFKISIH', molecule_type='protein')\n[2024-03-25 11:40:59,906] {align.py:179} INFO - Found 2 alignments with max score, returning last in the list (3\\' end rule)\n[2024-03-25 11:40:59,907] {cli.py:45} INFO - Found best alignment with score = 5.0\n[2024-03-25 11:40:59,909] {cli.py:46} INFO - Alignment:\nref 0 -PFKISIHL 8\n 0 -|||||||- 9\nalt 0 TPFKISIH- 8\n\n[2024-03-25 11:40:59,909] {cli.py:49} INFO - 2 Variant blocks generated\n[2024-03-25 11:40:59,909] {cli.py:54} INFO - VariantBlock(alignment_block=Block(start=0, end=1, bases='i'), reference_blocks=[], alternate_blocks=[Block(start=0, end=1, bases='T')]), categorized as: extension\n[2024-03-25 11:40:59,910] {cli.py:57} INFO - As HGVS: ref:p.Pro1extThr-1\n[2024-03-25 11:40:59,910] {cli.py:54} INFO - VariantBlock(alignment_block=Block(start=8, end=9, bases='d'), reference_blocks=[Block(start=7, end=8, bases='L')], alternate_blocks=[]), categorized as: deletion\n[2024-03-25 11:40:59,910] {cli.py:57} INFO - As HGVS: ref:p.Leu8del\n```\n\n## Usage - Python\n\nPalamedes currently includes a single public function that provides the alignment to HGVS functionality. All other functions should\nbe treated as internal and private. No assurances are offered for their consistency and functionality from version to version. The function accepts either raw sequences or biopython `SeqRecord` objects.\n\n```python\n>>> from Bio.Seq import Seq\n>>> from Bio.SeqRecord import SeqRecord\n>>> from palamedes import generate_hgvs_variants\n\n# using raw strings\n>>> generate_hgvs_variants(\"PFKISIHL\", \"TPFKISIH\")\n[\n SequenceVariant(ac=ref, type=p, posedit=Pro1extThr-1, gene=None),\n SequenceVariant(ac=ref, type=p, posedit=Leu8del, gene=None),\n]\n\n# using SeqRecord objects, note the molecule_type annotation must be provided and set to a supported type\n# protein is the default and only supported option at this time\n>>> ref = SeqRecord(Seq(\"PFKISIHL\"), id=\"Jelleine-I\", annotations={\"molecule_type\": \"protein\"})\n>>> alt = SeqRecord(Seq(\"TPFKISIH\"), id=\"Jelleine-IV\", annotations={\"molecule_type\": \"protein\"})\n>>> generate_hgvs_variants(ref, alt)\n[\n SequenceVariant(ac=Jelleine-I, type=p, posedit=Pro1extThr-1, gene=None),\n SequenceVariant(ac=Jelleine-I, type=p, posedit=Leu8del, gene=None)\n]\n```\n\nThe `generate_hgvs_variants` also accepts a pre-built biopython `PairwiseAligner` instance to give the caller more control of the alignment parameters via the `aligner` keyword argument. The default settings are:\n- mode: \"global\" (note this must be set to global on a custom aligner to ensure and end to end alignment)\n- match_score: 1\n- mismatch_score: -1\n- open_gap_score: -1\n- extend_gap_score: -0.1\n\n## Name\n\nThe package is named after [Palamedes](https://en.wikipedia.org/wiki/Palamedes_(mythology)), a figure from Greek mythology. Palamedes was associated with the invention of the Greek letters and alphabet as well as with the invention of dice. Palamedes dedicated the first set of dice to the Greek goddess Tyche, who was the goddess of chance and randomness.\n",
"bugtrack_url": null,
"license": null,
"summary": "Palamedes: HGVS variants from a sequence alignment",
"version": "0.0.8",
"project_urls": {
"Homepage": "https://github.com/mammothbio-os/palamedes"
},
"split_keywords": [
"bioinformatics",
" alignment",
" hgvs",
" variant",
" amino acid"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a8ae3310bae381dc2ef01113149851f1c5c3c2828e9334a41d3bd71365463e4",
"md5": "88727df241d2f9ceeb0857731d50c3ac",
"sha256": "e874c36842cba616cd982a4f83cd2687ed80e0af858995f54db9a47d547ff479"
},
"downloads": -1,
"filename": "palamedes-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88727df241d2f9ceeb0857731d50c3ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 26212,
"upload_time": "2024-06-13T17:50:01",
"upload_time_iso_8601": "2024-06-13T17:50:01.473991Z",
"url": "https://files.pythonhosted.org/packages/4a/8a/e3310bae381dc2ef01113149851f1c5c3c2828e9334a41d3bd71365463e4/palamedes-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6b86b0066de55d7e642771965f14bfc7a155b29153f66f84d28888d3f696a90c",
"md5": "a2945bbb2249c06e3c4d494356144d64",
"sha256": "48b262f9c2755e8bf1652e75417c19d2f4b0d25a335620da3f2a0eb589861252"
},
"downloads": -1,
"filename": "palamedes-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "a2945bbb2249c06e3c4d494356144d64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 22551,
"upload_time": "2024-06-13T17:50:03",
"upload_time_iso_8601": "2024-06-13T17:50:03.286640Z",
"url": "https://files.pythonhosted.org/packages/6b/86/b0066de55d7e642771965f14bfc7a155b29153f66f84d28888d3f696a90c/palamedes-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-13 17:50:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mammothbio-os",
"github_project": "palamedes",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "biopython",
"specs": [
[
"~=",
"1.83"
]
]
},
{
"name": "hgvs",
"specs": [
[
"~=",
"1.5.4"
]
]
}
],
"lcname": "palamedes"
}
JSON
