humanin-finder 1.0.0b3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- humanin_finder-1.0.0b3/.github/workflows/tests.yml +51 -0
- humanin_finder-1.0.0b3/.zenodo.json +33 -0
- humanin_finder-1.0.0b3/CITATION.cff +36 -0
- humanin_finder-1.0.0b3/LICENSE +21 -0
- humanin_finder-1.0.0b3/MANIFEST.in +11 -0
- humanin_finder-1.0.0b3/PKG-INFO +419 -0
- humanin_finder-1.0.0b3/README.md +394 -0
- humanin_finder-1.0.0b3/environment.yml +27 -0
- humanin_finder-1.0.0b3/examples/pan_taxonomic_sample.fasta +6 -0
- humanin_finder-1.0.0b3/examples/rcrs_nc_012920_1.fasta +278 -0
- humanin_finder-1.0.0b3/pyproject.toml +71 -0
- humanin_finder-1.0.0b3/recipe/meta.yaml +61 -0
- humanin_finder-1.0.0b3/setup.cfg +4 -0
- humanin_finder-1.0.0b3/src/humanin_finder/__init__.py +4 -0
- humanin_finder-1.0.0b3/src/humanin_finder/cli.py +859 -0
- humanin_finder-1.0.0b3/src/humanin_finder/core.py +1014 -0
- humanin_finder-1.0.0b3/src/humanin_finder/data/Humanin_core.hmm +658 -0
- humanin_finder-1.0.0b3/src/humanin_finder/data/MT-RNR2.hmm +5083 -0
- humanin_finder-1.0.0b3/src/humanin_finder/data/PF15040.hmm +102 -0
- humanin_finder-1.0.0b3/src/humanin_finder/data/mdp_locus_profiles.json +189 -0
- humanin_finder-1.0.0b3/src/humanin_finder/data/shlp_references.json +99 -0
- humanin_finder-1.0.0b3/src/humanin_finder/fasta_lint.py +548 -0
- humanin_finder-1.0.0b3/src/humanin_finder/shlp.py +84 -0
- humanin_finder-1.0.0b3/src/humanin_finder.egg-info/PKG-INFO +419 -0
- humanin_finder-1.0.0b3/src/humanin_finder.egg-info/SOURCES.txt +33 -0
- humanin_finder-1.0.0b3/src/humanin_finder.egg-info/dependency_links.txt +1 -0
- humanin_finder-1.0.0b3/src/humanin_finder.egg-info/entry_points.txt +3 -0
- humanin_finder-1.0.0b3/src/humanin_finder.egg-info/requires.txt +3 -0
- humanin_finder-1.0.0b3/src/humanin_finder.egg-info/top_level.txt +1 -0
- humanin_finder-1.0.0b3/tests/__init__.py +1 -0
- humanin_finder-1.0.0b3/tests/test_cli.py +133 -0
- humanin_finder-1.0.0b3/tests/test_core.py +101 -0
- humanin_finder-1.0.0b3/tests/test_fasta_lint.py +33 -0
- humanin_finder-1.0.0b3/tests/test_regressions.py +515 -0
- humanin_finder-1.0.0b3/tests/test_shlp.py +71 -0
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
name: tests
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
pull_request:
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
core:
|
|
9
|
+
name: suite (python ${{ matrix.python-version }})
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
fail-fast: false
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.10", "3.11", "3.12"]
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v4
|
|
17
|
+
- uses: actions/setup-python@v5
|
|
18
|
+
with:
|
|
19
|
+
python-version: ${{ matrix.python-version }}
|
|
20
|
+
- run: pip install . pytest ruff
|
|
21
|
+
- run: ruff check src tests
|
|
22
|
+
- run: pytest
|
|
23
|
+
|
|
24
|
+
packaged:
|
|
25
|
+
# The working tree is not what users receive. This job builds the sdist and the wheel, then runs
|
|
26
|
+
# the suite from the *unpacked sdist* in a directory of its own, which is how Bioconda and any
|
|
27
|
+
# reviewer validates the package. Without it, a sdist missing examples/ or tests/__init__.py
|
|
28
|
+
# passes CI and fails for everyone else -- which is exactly what happened before 1.0.0b1.
|
|
29
|
+
name: suite from the built sdist
|
|
30
|
+
runs-on: ubuntu-latest
|
|
31
|
+
steps:
|
|
32
|
+
- uses: actions/checkout@v4
|
|
33
|
+
- uses: actions/setup-python@v5
|
|
34
|
+
with:
|
|
35
|
+
python-version: "3.12"
|
|
36
|
+
- run: pip install build pytest
|
|
37
|
+
- run: python -m build
|
|
38
|
+
- name: Unpack the sdist where the working tree cannot help it
|
|
39
|
+
run: |
|
|
40
|
+
mkdir -p /tmp/fromsdist
|
|
41
|
+
tar xzf dist/*.tar.gz -C /tmp/fromsdist --strip-components=1
|
|
42
|
+
- name: Install the built wheel and run the sdist's own suite
|
|
43
|
+
run: |
|
|
44
|
+
pip install dist/*.whl
|
|
45
|
+
cd /tmp/fromsdist
|
|
46
|
+
pytest -q
|
|
47
|
+
- uses: actions/upload-artifact@v4
|
|
48
|
+
with:
|
|
49
|
+
name: distributions
|
|
50
|
+
path: dist/*
|
|
51
|
+
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"title": "HumaninFinder: homology-first location and annotation of Humanin and SHLP1-6",
|
|
3
|
+
"upload_type": "software",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"creators": [
|
|
6
|
+
{
|
|
7
|
+
"name": "Menegidio, Fabiano Bezerra",
|
|
8
|
+
"affiliation": "Universidade de Mogi das Cruzes"
|
|
9
|
+
},
|
|
10
|
+
{
|
|
11
|
+
"name": "LaBiOmicS"
|
|
12
|
+
}
|
|
13
|
+
],
|
|
14
|
+
"keywords": [
|
|
15
|
+
"Humanin",
|
|
16
|
+
"mitochondrial-derived peptides",
|
|
17
|
+
"SHLP",
|
|
18
|
+
"MT-RNR2",
|
|
19
|
+
"NUMT"
|
|
20
|
+
],
|
|
21
|
+
"description": "Locates Humanin and SHLP1-6 by their position in MT-RNR2 (multi-clade vertebrate profiles) in mitogenomes, contigs and nuclear assemblies, and reports each species' own reading frame with explicit in silico evidence.",
|
|
22
|
+
"related_identifiers": [
|
|
23
|
+
{
|
|
24
|
+
"identifier": "https://github.com/LaBiOmicS/humaninfinder",
|
|
25
|
+
"relation": "isSupplementTo",
|
|
26
|
+
"scheme": "url"
|
|
27
|
+
}
|
|
28
|
+
],
|
|
29
|
+
"version": "1.0.0b3",
|
|
30
|
+
"publication_date": "2026-11-10",
|
|
31
|
+
"access_right": "open",
|
|
32
|
+
"notes": "Beta release accompanying a manuscript in preparation."
|
|
33
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use HumaninFinder, please cite the paper (preferred-citation) and, for the exact\n version you ran, this software record."
|
|
3
|
+
title: "HumaninFinder: homology-first location and annotation of Humanin and SHLP1-6"
|
|
4
|
+
version: 1.0.0b3
|
|
5
|
+
date-released: 2026-11-10
|
|
6
|
+
license: MIT
|
|
7
|
+
authors:
|
|
8
|
+
# Software authorship for 1.0.0b3. The paper's author list is not settled yet; when it is, update
|
|
9
|
+
# preferred-citation.authors (and, if the team decides so, this list).
|
|
10
|
+
- family-names: Menegidio
|
|
11
|
+
given-names: Fabiano Bezerra
|
|
12
|
+
affiliation: "Universidade de Mogi das Cruzes"
|
|
13
|
+
- name: LaBiOmicS
|
|
14
|
+
keywords:
|
|
15
|
+
- Humanin
|
|
16
|
+
- mitochondrial-derived peptides
|
|
17
|
+
- SHLP
|
|
18
|
+
- MT-RNR2
|
|
19
|
+
- NUMT
|
|
20
|
+
- bioinformatics
|
|
21
|
+
repository-code: "https://github.com/LaBiOmicS/humaninfinder"
|
|
22
|
+
|
|
23
|
+
# Without this block, anyone citing the software fails to cite the paper. The entry is deliberately
|
|
24
|
+
# marked unpublished: fill in the full author list, journal, year and doi at submission and switch
|
|
25
|
+
# the type to article. Never invent a DOI here -- a wrong one propagates into reference managers.
|
|
26
|
+
preferred-citation:
|
|
27
|
+
type: unpublished
|
|
28
|
+
title: "HumaninFinder: homology-based location and annotation of Humanin and SHLP1-6 in
|
|
29
|
+
mitochondrial genomes and NUMTs"
|
|
30
|
+
authors:
|
|
31
|
+
- family-names: Menegidio
|
|
32
|
+
given-names: Fabiano Bezerra
|
|
33
|
+
affiliation: "Universidade de Mogi das Cruzes"
|
|
34
|
+
year: 2026
|
|
35
|
+
notes: "Manuscript in preparation. Replace with the published reference before tagging a
|
|
36
|
+
non-beta release."
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HumaninFinder Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# The sdist must carry everything the test suite needs, or `pip install sdist && pytest` fails for
|
|
2
|
+
# anyone validating the package -- which is how Bioconda and reviewers check it.
|
|
3
|
+
# tests/__init__.py matters specifically: tests/test_cli.py does `from tests.test_core import ...`.
|
|
4
|
+
recursive-include examples *.fasta
|
|
5
|
+
recursive-include tests *.py
|
|
6
|
+
recursive-include tests/data *.json
|
|
7
|
+
include recipe/meta.yaml
|
|
8
|
+
include CITATION.cff
|
|
9
|
+
include .zenodo.json
|
|
10
|
+
recursive-include .github *.yml
|
|
11
|
+
include environment.yml
|
|
@@ -0,0 +1,419 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: humanin-finder
|
|
3
|
+
Version: 1.0.0b3
|
|
4
|
+
Summary: Homology-based location and annotation of Humanin and SHLP1-6 mitochondrial-derived peptides in mitogenomes and nuclear genomes
|
|
5
|
+
Author: Fabiano Bezerra Menegidio, LaBiOmicS
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/LaBiOmicS/humaninfinder
|
|
8
|
+
Project-URL: Repository, https://github.com/LaBiOmicS/humaninfinder
|
|
9
|
+
Project-URL: Issues, https://github.com/LaBiOmicS/humaninfinder/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/LaBiOmicS/humaninfinder/releases
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: biopython<2,>=1.83
|
|
22
|
+
Requires-Dist: click<9,>=8.1.0
|
|
23
|
+
Requires-Dist: pyhmmer<0.13,>=0.12.0
|
|
24
|
+
Dynamic: license-file
|
|
25
|
+
|
|
26
|
+
<div align="center">
|
|
27
|
+
|
|
28
|
+
# HumaninFinder
|
|
29
|
+
|
|
30
|
+
**Homology-based location and annotation of Humanin and SHLP1-6 in mitogenomes, contigs and nuclear assemblies**
|
|
31
|
+
|
|
32
|
+
[](https://github.com/LaBiOmicS/humaninfinder/actions/workflows/tests.yml)
|
|
33
|
+
[](https://pypi.org/project/humanin-finder/)
|
|
34
|
+
[](pyproject.toml)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
[](#project-status)
|
|
37
|
+
|
|
38
|
+
[Website](https://labiomics.github.io/humaninfinder/) •
|
|
39
|
+
[Run in the browser](https://labiomics.github.io/humaninfinder/app/) •
|
|
40
|
+
[Installation](#installation) •
|
|
41
|
+
[Quick start](#quick-start) •
|
|
42
|
+
[Usage](#usage) •
|
|
43
|
+
[Method](#method) •
|
|
44
|
+
[Outputs](#outputs) •
|
|
45
|
+
[Limitations](#limitations) •
|
|
46
|
+
[Citation](#citation)
|
|
47
|
+
|
|
48
|
+
</div>
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Overview
|
|
53
|
+
|
|
54
|
+
Humanin and the six **small humanin-like peptides (SHLP1-6)** are mitochondrial-derived peptides
|
|
55
|
+
encoded by short open reading frames inside the 16S rRNA gene, `MT-RNR2`. Because they overlap a
|
|
56
|
+
structural RNA, ordinary gene finders miss them, and because `MT-RNR2` has many nuclear copies
|
|
57
|
+
(NUMTs), a sequence match alone does not tell where a copy comes from or whether its frame is intact.
|
|
58
|
+
|
|
59
|
+
HumaninFinder locates each peptide by its **position in MT-RNR2**, using profile HMMs of the gene built
|
|
60
|
+
from vertebrate mitogenomes of several clades, and then reads **the species' own reading frame** at that
|
|
61
|
+
position. Every reported frame states which evidence supports it and how far that evidence goes.
|
|
62
|
+
|
|
63
|
+
> [!IMPORTANT]
|
|
64
|
+
> All evidence produced by HumaninFinder is **in silico homology**. A reported frame is a candidate:
|
|
65
|
+
> HumaninFinder makes no claim that a peptide is transcribed, translated or functional.
|
|
66
|
+
|
|
67
|
+
### Features
|
|
68
|
+
|
|
69
|
+
- **Position first.** Peptides are located by their homologous position in `MT-RNR2` (`nhmmer`
|
|
70
|
+
against whole-gene and Humanin-core profiles), not by matching the human peptide sequence, so
|
|
71
|
+
divergent orthologues are still found.
|
|
72
|
+
- **Species' own frame.** The ORF is read from the local start codon, under the genetic code you
|
|
73
|
+
choose, and classified as `Complete`, `Incomplete` or `Interrupted`.
|
|
74
|
+
- **Graded evidence.** Names tell how far the evidence goes (`Humanin`, `Humanin_position`,
|
|
75
|
+
`Humanin_domain`), and the Pfam domain PF15040 is reported as independent support.
|
|
76
|
+
- **Mitogenomes and NUMTs.** `predict` returns the best frame per record; `scan` returns every locus,
|
|
77
|
+
for contigs and chromosomes carrying nuclear copies.
|
|
78
|
+
- **Circular genomes.** Loci that cross the origin of a circular mitogenome are read through it and
|
|
79
|
+
written with the GFF3 convention for circular sequences.
|
|
80
|
+
- **Standard outputs.** CSV, FASTA, GFF3 and BED, plus a JSON provenance record with the command,
|
|
81
|
+
the options and the SHA-256 of the input.
|
|
82
|
+
- **No external binaries.** HMMER runs in memory through [pyhmmer](https://github.com/althonos/pyhmmer);
|
|
83
|
+
every profile ships with the package.
|
|
84
|
+
|
|
85
|
+
### Peptides
|
|
86
|
+
|
|
87
|
+
Reference peptides on the revised Cambridge Reference Sequence (rCRS, NC_012920.1), as reported by
|
|
88
|
+
HumaninFinder on the bundled example. Coordinates are 1-based and include the stop codon.
|
|
89
|
+
|
|
90
|
+
| Peptide | Strand | rCRS coordinates | Code | Length | Sequence | Literature tier¹ |
|
|
91
|
+
|---|:-:|---|:-:|:-:|---|:-:|
|
|
92
|
+
| Humanin | + | 2633-2698 | 2 | 21 aa | `MAPRGFSCLLLLTSEIDLPVK` | — |
|
|
93
|
+
| SHLP1 | − | 2485-2559 | 1 | 24 aa | `MCHWAGGASNTGDARGDVFGKQAG` | E3 |
|
|
94
|
+
| SHLP2 | − | 2088-2168 | 1 | 26 aa | `MGVKFFTLSTRFFPSVQRAVPLWTNS` | E4 |
|
|
95
|
+
| SHLP3 | − | 1703-1819 | 1 | 38 aa | `MLGYNFSSFPCGTISIAPGFNFYRLYFIWVNGLAKVVW` | E4 |
|
|
96
|
+
| SHLP4 | − | 2442-2522 | 1 | 26 aa | `MLEVMFLVNRRGKICRVPFTFFNLSL` | E4 |
|
|
97
|
+
| SHLP5 | − | 2780-2854 | 1 | 24 aa | `MYCSEVGFCSEVAPTEIFNAGLVV` | E2 |
|
|
98
|
+
| SHLP6 | + | 2990-3052 | 1 | 20 aa | `MLDQDIPMVQPLLKVRLFND` | E4 |
|
|
99
|
+
|
|
100
|
+
¹ Cobb *et al.* 2016: E2 transcript detected, E3 peptide detected, E4 exogenous biological activity.
|
|
101
|
+
Humanin read under the cytosolic code (Table 1) gives the 24-aa form `MAPRGFSCLLLLTSEIDLPVKRRA`.
|
|
102
|
+
|
|
103
|
+
## Installation
|
|
104
|
+
|
|
105
|
+
HumaninFinder requires Python ≥ 3.10. Its dependencies are Biopython, click and pyhmmer.
|
|
106
|
+
|
|
107
|
+
**No installation: in the browser.** The [web version](https://labiomics.github.io/humaninfinder/app/)
|
|
108
|
+
runs the same code in your browser through [Pyodide](https://pyodide.org), with a WebAssembly build of
|
|
109
|
+
pyhmmer ([pyhmmer-pyodide](https://github.com/LaBiOmicS/pyhmmer-pyodide)). Sequences stay on your
|
|
110
|
+
computer. Its outputs are byte-identical to the installed tool's on the validation sets; it runs on one
|
|
111
|
+
thread and suits up to a few hundred mitogenomes per run.
|
|
112
|
+
|
|
113
|
+
**From PyPI**
|
|
114
|
+
|
|
115
|
+
```sh
|
|
116
|
+
pip install humanin-finder
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
**From Bioconda** (recipe under review in
|
|
120
|
+
[bioconda-recipes#71446](https://github.com/bioconda/bioconda-recipes/pull/71446))
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
conda install -c conda-forge -c bioconda humanin-finder
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
**From source**
|
|
127
|
+
|
|
128
|
+
```sh
|
|
129
|
+
git clone https://github.com/LaBiOmicS/humaninfinder.git
|
|
130
|
+
cd humaninfinder
|
|
131
|
+
pip install .
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
**From source, in a conda environment**
|
|
135
|
+
|
|
136
|
+
[`environment.yml`](environment.yml) creates an environment named `humaninfinder` with every
|
|
137
|
+
dependency from conda-forge and Bioconda, plus pytest and ruff, and installs the clone in editable mode:
|
|
138
|
+
|
|
139
|
+
```sh
|
|
140
|
+
git clone https://github.com/LaBiOmicS/humaninfinder.git
|
|
141
|
+
cd humaninfinder
|
|
142
|
+
micromamba env create -f environment.yml # or: conda env create -f environment.yml
|
|
143
|
+
micromamba activate humaninfinder
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Then check that the installation and every bundled data file are usable:
|
|
147
|
+
|
|
148
|
+
```console
|
|
149
|
+
$ humanin-finder setup
|
|
150
|
+
[*] Verifying HumaninFinder v1.0.0b3 prerequisites...
|
|
151
|
+
[+] pyhmmer (in-memory HMMER 0.12.3) verified.
|
|
152
|
+
[+] PF15040 Humanin domain: gathering threshold 27.0 bits.
|
|
153
|
+
[+] SHLP references: SHLP1, SHLP2, SHLP3, SHLP4, SHLP5, SHLP6.
|
|
154
|
+
[+] MT-RNR2 locus profiles: MT-RNR2 (1686 states, >= 140 bits), Humanin_core (211 states, >= 105 bits)
|
|
155
|
+
[+] Vertebrate-like density (Humanin vs Humanin_position): MT-RNR2 >= 0.587 bits/column
|
|
156
|
+
|
|
157
|
+
[!] Setup inspection complete: all bundled data files verified.
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
> [!NOTE]
|
|
161
|
+
> pyhmmer is pinned below its next minor version on purpose: it carries the semantics of the bundled
|
|
162
|
+
> profiles. Bounds are raised only after the test and validation suites pass against a new release.
|
|
163
|
+
|
|
164
|
+
The package installs two equivalent commands, `humanin-finder` and `humaninfinder`.
|
|
165
|
+
|
|
166
|
+
## Quick start
|
|
167
|
+
|
|
168
|
+
Run HumaninFinder on the human reference mitogenome bundled in `examples/`, under the vertebrate
|
|
169
|
+
mitochondrial code, treating the record as circular:
|
|
170
|
+
|
|
171
|
+
```console
|
|
172
|
+
$ humanin-finder predict -i examples/rcrs_nc_012920_1.fasta -o rcrs -g 2 --circular
|
|
173
|
+
-----------------------------------------------------------------------------------------------------
|
|
174
|
+
Sequence ID | Peptide | Status | 1-Based Coords | Locus bits | HMM Score
|
|
175
|
+
-----------------------------------------------------------------------------------------------------
|
|
176
|
+
NC_012920.1 | Humanin | Complete | 2633-2698 | 1341 | 57.2
|
|
177
|
+
NC_012920.1 | SHLP3 | Complete | 1703-1819 | 1341 | -
|
|
178
|
+
NC_012920.1 | SHLP2 | Complete | 2088-2168 | 1341 | -
|
|
179
|
+
NC_012920.1 | SHLP4 | Complete | 2442-2522 | 1341 | -
|
|
180
|
+
NC_012920.1 | SHLP1 | Complete | 2485-2559 | 1341 | -
|
|
181
|
+
NC_012920.1 | SHLP5 | Complete | 2780-2854 | 1341 | -
|
|
182
|
+
NC_012920.1 | SHLP6 | Complete | 2990-3052 | 1341 | -
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
This writes `rcrs_results.{csv,fasta,gff3,bed}` and `rcrs_run.json`: seven `Complete` frames, Humanin
|
|
186
|
+
and SHLP1-6, all at the vertebrate-like `MT-RNR2` locus.
|
|
187
|
+
|
|
188
|
+
```console
|
|
189
|
+
$ cat rcrs_results.fasta
|
|
190
|
+
>NC_012920.1|Humanin|Complete|coords_2633-2698|evidence_Synteny+HMM
|
|
191
|
+
MAPRGFSCLLLLTSEIDLPVK
|
|
192
|
+
>NC_012920.1|SHLP3|Complete|coords_1703-1819|evidence_Synteny
|
|
193
|
+
MLGYNFSSFPCGTISIAPGFNFYRLYFIWVNGLAKVVW
|
|
194
|
+
...
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## Usage
|
|
198
|
+
|
|
199
|
+
### Commands
|
|
200
|
+
|
|
201
|
+
| Command | Use |
|
|
202
|
+
|---|---|
|
|
203
|
+
| `predict` | Best Humanin frame per genetic code, plus SHLP1-6, for each record. The usual choice for mitogenomes. |
|
|
204
|
+
| `scan` | Every non-redundant locus per record: mitochondrial and NUMT copies in contigs or chromosomes. |
|
|
205
|
+
| `lint` | Validate a FASTA file without changing it. |
|
|
206
|
+
| `setup` | Verify the installation and the bundled data files. |
|
|
207
|
+
|
|
208
|
+
Run `humanin-finder <command> --help` for the full list of options.
|
|
209
|
+
|
|
210
|
+
### Options of `predict` and `scan`
|
|
211
|
+
|
|
212
|
+
| Option | Description |
|
|
213
|
+
|---|---|
|
|
214
|
+
| `-i`, `--input FILE` | FASTA, plain or gzip-compressed. It is linted first; an invalid file stops the run. |
|
|
215
|
+
| `-o`, `--output TEXT` | Output prefix. |
|
|
216
|
+
| `-g`, `--table TEXT` | NCBI genetic code(s), e.g. `2` or `2,1`. Default `auto`: Table 2 for mitochondrial records (the header says *mitochondri*, or the record is ≤ 50 kb), Table 1 otherwise. |
|
|
217
|
+
| `--circular` | Treat records ≤ 50 kb as circular, so a locus crossing the origin is read through it. Longer records are always linear. |
|
|
218
|
+
| `--no-hmm` | Skip the PF15040 domain search. |
|
|
219
|
+
| `--no-rescue` | Skip the HMM-guided rescue of interrupted frames. |
|
|
220
|
+
| `--no-shlp` | Skip the SHLP1-6 annotation. |
|
|
221
|
+
| `--no-synteny` | Skip the `MT-RNR2` locus search (domain search only). |
|
|
222
|
+
| `--all-candidates` (`predict`) | Report every non-redundant candidate instead of the best one per code. |
|
|
223
|
+
| `--best-only` (`scan`) | Report only the best candidate per code (the default for `scan` is every candidate). |
|
|
224
|
+
|
|
225
|
+
> [!TIP]
|
|
226
|
+
> `auto` only covers vertebrates. For other mitogenomes pass the code explicitly, e.g. `-g 5` for
|
|
227
|
+
> insects or `-g 9` for echinoderms. A NUMT inside a short nuclear contig needs `-g 1`.
|
|
228
|
+
|
|
229
|
+
### Common recipes
|
|
230
|
+
|
|
231
|
+
```sh
|
|
232
|
+
# Complete mitogenomes (any assembly origin): read through the origin
|
|
233
|
+
humanin-finder predict -i mitogenomes.fasta -o mito -g 2 --circular
|
|
234
|
+
|
|
235
|
+
# Compare the mitochondrial and the cytosolic reading of the same loci
|
|
236
|
+
humanin-finder predict -i mitogenomes.fasta -o mito_t2t1 -g 2,1
|
|
237
|
+
|
|
238
|
+
# NUMTs: every MT-RNR2 copy in a nuclear assembly, read under the standard code
|
|
239
|
+
humanin-finder scan -i genome.fa.gz -o numts -g 1
|
|
240
|
+
|
|
241
|
+
# Non-vertebrate mitogenome, explicit code
|
|
242
|
+
humanin-finder predict -i drosophila_mt.fasta -o dmel -g 5 --circular
|
|
243
|
+
|
|
244
|
+
# Check a FASTA before a long run
|
|
245
|
+
humanin-finder lint genome.fa.gz
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
## Method
|
|
249
|
+
|
|
250
|
+
```mermaid
|
|
251
|
+
flowchart LR
|
|
252
|
+
A[FASTA input] --> B[lint]
|
|
253
|
+
B --> C["nhmmer: MT-RNR2 and<br/>Humanin-core profiles"]
|
|
254
|
+
C --> D["Map the start codon<br/>of each peptide"]
|
|
255
|
+
D --> E["Read the species' own ORF<br/>under the chosen code"]
|
|
256
|
+
E --> F["Status:<br/>Complete / Incomplete / Interrupted"]
|
|
257
|
+
A --> G["PF15040 domain search<br/>(hmmsearch)"]
|
|
258
|
+
G --> H
|
|
259
|
+
F --> H["Name by evidence:<br/>Humanin / _position / _domain"]
|
|
260
|
+
H --> I[CSV · FASTA · GFF3 · BED · JSON]
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
1. **Locus.** The record is searched with `nhmmer` against two profiles: the whole `MT-RNR2` gene and
|
|
264
|
+
the Humanin core. Each profile hit at or above the profile's evidence threshold maps the start codon
|
|
265
|
+
of every peptide. The threshold is calibrated above the paralogous bacterial and plastid 23S and the
|
|
266
|
+
nuclear 28S rRNAs.
|
|
267
|
+
2. **Frame.** The species' own ORF is read from the start codon nearest the mapped one (within 6
|
|
268
|
+
codons either way). Humanin is read under the requested code. SHLP1-6 are read under the cytosolic
|
|
269
|
+
code (Table 1) in every record: SHLP1-4 give their published sequences only under it, and SHLP5-6,
|
|
270
|
+
identical under Tables 1 and 2 in human, follow the family. Cobb *et al.* 2016 do not name a code;
|
|
271
|
+
the reasoning is recorded in `shlp_references.json` (`translation_table_note`).
|
|
272
|
+
3. **Status.** Structure only, with no functional claim:
|
|
273
|
+
|
|
274
|
+
| Status | Meaning |
|
|
275
|
+
|---|---|
|
|
276
|
+
| `Complete` | Start codon through an in-frame stop. The start is the species' own and may sit up to 6 codons from the human one (`start_offset_codons`), with any initiator of the code, so `Complete` does not mean that the human start codon is conserved. |
|
|
277
|
+
| `Incomplete` | No start codon, or no stop within 60 codons. |
|
|
278
|
+
| `Interrupted` | An in-frame stop inside the homologous span under the evaluated code. |
|
|
279
|
+
|
|
280
|
+
4. **Name.** How far the evidence goes:
|
|
281
|
+
|
|
282
|
+
| Name | Evidence |
|
|
283
|
+
|---|---|
|
|
284
|
+
| `Humanin`, `SHLP<n>` | At a vertebrate-like `MT-RNR2` locus. For Humanin, the name is also given to a locus whose frame carries the PF15040 domain at the Pfam gathering threshold. |
|
|
285
|
+
| `Humanin_position`, `SHLP<n>_position` | At an `MT-RNR2` locus outside the vertebrate pattern. Only the homologous position is marked. |
|
|
286
|
+
| `Humanin_domain` | A PF15040 domain outside any `MT-RNR2` locus. Only the domain is supported. |
|
|
287
|
+
|
|
288
|
+
With several codes (`-g 2,1`) names carry a suffix such as `_T2`.
|
|
289
|
+
|
|
290
|
+
A peptide can be absent from the table even though its locus is present: its start codon may fall in
|
|
291
|
+
a deletion or an assembly gap, leaving no frame to read. Those cases are listed in `<prefix>_gaps.csv`
|
|
292
|
+
and announced at the end of the run.
|
|
293
|
+
|
|
294
|
+
## Outputs
|
|
295
|
+
|
|
296
|
+
| File | Content |
|
|
297
|
+
|---|---|
|
|
298
|
+
| `<prefix>_results.csv` | One row per reported frame (columns below). |
|
|
299
|
+
| `<prefix>_results.fasta` | Peptides; header `sample\|name\|status\|coords_<start>-<end>\|evidence_<source>`. |
|
|
300
|
+
| `<prefix>_results.gff3` | `ORF` features, 1-based inclusive. Circular records get a `region` with `Is_circular=true`. |
|
|
301
|
+
| `<prefix>_results.bed` | 0-based half-open. A feature crossing the origin is split into two blocks with the same name. |
|
|
302
|
+
| `<prefix>_gaps.csv` | Peptides whose start codon aligns to a gap (written only when there are any). |
|
|
303
|
+
| `<prefix>_run.json` | Provenance: command, options, input SHA-256, version and row counts. |
|
|
304
|
+
|
|
305
|
+
<details>
|
|
306
|
+
<summary><b>Columns of <code><prefix>_results.csv</code></b></summary>
|
|
307
|
+
|
|
308
|
+
| Group | Columns | Meaning |
|
|
309
|
+
|---|---|---|
|
|
310
|
+
| Identity | `sample_id`, `name`, `status`, `seq`, `length` | Record, peptide name, status, peptide sequence and length (aa). |
|
|
311
|
+
| Location | `strand`, `frame`, `start_0based`, `end_0based`, `start_1based`, `end_1based` | Half-open 0-based and inclusive 1-based coordinates; they include the stop codon of a `Complete` frame. |
|
|
312
|
+
| Circularity | `circular_wrap` | `True` when the feature crosses the origin; `end` then exceeds the record length (GFF3 convention). |
|
|
313
|
+
| `MT-RNR2` locus | `synteny_score`, `locus_profile`, `locus_density`, `locus_mode` | Bitscore of the locus profile, the profile that produced it, bits per aligned profile column, and how the frame was located. |
|
|
314
|
+
| PF15040 domain | `hmm_bitscore`, `hmm_evalue`, `hmm_supported` | Domain score; E-value of a single comparison (Z = 1), so the same domain gets the same value in a short or a long record; whether it reaches the gathering threshold. |
|
|
315
|
+
| Evidence | `evidence_source`, `evidence_tier`, `reference_evidence_tier` | `Synteny`, `HMM` or both; `E1` (in silico homology); the literature tier of the human peptide, given only for a `Complete` frame identical to it. |
|
|
316
|
+
| Comparison | `identity_to_reference` | Ungapped identity of the homologous span to the human peptide. Descriptive only; it does not enter the status. |
|
|
317
|
+
| Reading | `start_offset_codons`, `genetic_code`, `table_1_pep` | Local start relative to the mapped human start; the code used; the cytosolic reading of a Table 2 sORF that starts with a Table 1 initiator. |
|
|
318
|
+
|
|
319
|
+
</details>
|
|
320
|
+
|
|
321
|
+
### Evidence tiers
|
|
322
|
+
|
|
323
|
+
| Tier | Meaning | Where |
|
|
324
|
+
|---|---|---|
|
|
325
|
+
| E1 | In silico, homologous position conserved across clades | `evidence_tier`, every frame HumaninFinder reports |
|
|
326
|
+
| E2 | Transcript detected (RT-PCR, RNA-seq) | `reference_evidence_tier` (literature) |
|
|
327
|
+
| E3 | Peptide detected (antibody, mass spectrometry) | `reference_evidence_tier` (literature) |
|
|
328
|
+
| E4 | Exogenous biological activity shown (cell or animal assays) | `reference_evidence_tier` (literature) |
|
|
329
|
+
|
|
330
|
+
HumaninFinder never assigns more than E1 to a frame it finds. The literature tier describes the human
|
|
331
|
+
peptide and is copied only when the frame found is identical to it.
|
|
332
|
+
|
|
333
|
+
## Limitations
|
|
334
|
+
|
|
335
|
+
- **Homology only.** Evidence is the position in `MT-RNR2` and/or the PF15040 domain. Expression and
|
|
336
|
+
function have to be shown experimentally.
|
|
337
|
+
- **Vertebrate profiles.** The profiles were built from vertebrate mitogenomes. Outside vertebrates a
|
|
338
|
+
locus is named `_position` at most.
|
|
339
|
+
- **`auto` code.** It treats records ≤ 50 kb as mitochondrial and covers vertebrate codes only.
|
|
340
|
+
- **Origin and the domain search.** The PF15040 search itself is linear. A Humanin locus crossing the
|
|
341
|
+
origin still gets its PF15040 score, computed from the peptide that was read.
|
|
342
|
+
|
|
343
|
+
## Project status
|
|
344
|
+
|
|
345
|
+
HumaninFinder **1.0.0b3** is a beta that accompanies a manuscript in preparation (1.0.0b1 was the first
|
|
346
|
+
tagged release; 1.0.0b2 added this documentation and fixed the rat record of the example set; 1.0.0b3
|
|
347
|
+
corrects the strand of SHLP6 in the documentation and adds the web version and `environment.yml`): the
|
|
348
|
+
command-line interface and output formats are expected to stay stable, but they may still change before
|
|
349
|
+
1.0.0. Changes are listed on the [releases page](https://github.com/LaBiOmicS/humaninfinder/releases).
|
|
350
|
+
|
|
351
|
+
## Development
|
|
352
|
+
|
|
353
|
+
```sh
|
|
354
|
+
git clone https://github.com/LaBiOmicS/humaninfinder.git
|
|
355
|
+
cd humaninfinder
|
|
356
|
+
pip install -e . pytest ruff # or: micromamba env create -f environment.yml
|
|
357
|
+
ruff check src tests
|
|
358
|
+
pytest
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
Continuous integration runs the suite on Python 3.10, 3.11 and 3.12, and once more from the built
|
|
362
|
+
source distribution, which is how Bioconda and reviewers install the package.
|
|
363
|
+
|
|
364
|
+
```text
|
|
365
|
+
src/humanin_finder/
|
|
366
|
+
├── cli.py # commands, options and output writers
|
|
367
|
+
├── core.py # locus search, frame reading, status and naming
|
|
368
|
+
├── shlp.py # SHLP1-6 annotation
|
|
369
|
+
├── fasta_lint.py # FASTA validation
|
|
370
|
+
└── data/ # profile HMMs (MT-RNR2, Humanin core, PF15040) and reference tables
|
|
371
|
+
examples/ # rCRS reference mitogenome and a small test set
|
|
372
|
+
tests/ # unit and regression tests
|
|
373
|
+
recipe/ # Bioconda recipe
|
|
374
|
+
environment.yml # conda environment for a clone
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
### Contributing
|
|
378
|
+
|
|
379
|
+
Bug reports and suggestions are welcome on the
|
|
380
|
+
[issue tracker](https://github.com/LaBiOmicS/humaninfinder/issues). For a wrong or missing call,
|
|
381
|
+
please attach the FASTA record (or its accession), the exact command and the `<prefix>_run.json` file.
|
|
382
|
+
Pull requests should keep `ruff check` and `pytest` passing and add a test for the behaviour they
|
|
383
|
+
change.
|
|
384
|
+
|
|
385
|
+
## Citation
|
|
386
|
+
|
|
387
|
+
If you use HumaninFinder, please cite the software version you ran. The accompanying article is in
|
|
388
|
+
preparation; this section will be updated when it is published. Machine-readable metadata are in
|
|
389
|
+
[`CITATION.cff`](CITATION.cff) (GitHub's "Cite this repository" button).
|
|
390
|
+
|
|
391
|
+
```bibtex
|
|
392
|
+
@software{humaninfinder,
|
|
393
|
+
author = {Menegidio, Fabiano Bezerra and {LaBiOmicS}},
|
|
394
|
+
title = {{HumaninFinder}: homology-first location and annotation of Humanin and SHLP1-6},
|
|
395
|
+
version = {1.0.0b3},
|
|
396
|
+
year = {2026},
|
|
397
|
+
url = {https://github.com/LaBiOmicS/humaninfinder}
|
|
398
|
+
}
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
Please also cite the resources HumaninFinder builds on:
|
|
402
|
+
|
|
403
|
+
- Cobb LJ, Lee C, Xiao J, *et al.* Naturally occurring mitochondrial-derived peptides are
|
|
404
|
+
age-dependent regulators of apoptosis, insulin sensitivity, and inflammatory markers.
|
|
405
|
+
*Aging (Albany NY)* 2016;8(4):796-809. PMID: 27070352.
|
|
406
|
+
- Larralde M, Zeller G. PyHMMER: a Python library binding to HMMER for efficient sequence analysis.
|
|
407
|
+
*Bioinformatics* 2023;39(5):btad214.
|
|
408
|
+
- Mistry J, *et al.* Pfam: The protein families database in 2021. *Nucleic Acids Res* 2021;49(D1):D412-D419.
|
|
409
|
+
|
|
410
|
+
## License
|
|
411
|
+
|
|
412
|
+
HumaninFinder is released under the [MIT License](LICENSE). The bundled PF15040 profile comes from
|
|
413
|
+
Pfam (CC0). The rCRS reference (NC_012920.1) is from NCBI RefSeq.
|
|
414
|
+
|
|
415
|
+
## Contact
|
|
416
|
+
|
|
417
|
+
Developed at **LaBiOmicS**, Universidade de Mogi das Cruzes (UMC), Brazil.
|
|
418
|
+
Maintainer: Prof. Dr. Fabiano Bezerra Menegidio. Questions and reports go through the
|
|
419
|
+
[issue tracker](https://github.com/LaBiOmicS/humaninfinder/issues).
|