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.
Files changed (35) hide show
  1. humanin_finder-1.0.0b3/.github/workflows/tests.yml +51 -0
  2. humanin_finder-1.0.0b3/.zenodo.json +33 -0
  3. humanin_finder-1.0.0b3/CITATION.cff +36 -0
  4. humanin_finder-1.0.0b3/LICENSE +21 -0
  5. humanin_finder-1.0.0b3/MANIFEST.in +11 -0
  6. humanin_finder-1.0.0b3/PKG-INFO +419 -0
  7. humanin_finder-1.0.0b3/README.md +394 -0
  8. humanin_finder-1.0.0b3/environment.yml +27 -0
  9. humanin_finder-1.0.0b3/examples/pan_taxonomic_sample.fasta +6 -0
  10. humanin_finder-1.0.0b3/examples/rcrs_nc_012920_1.fasta +278 -0
  11. humanin_finder-1.0.0b3/pyproject.toml +71 -0
  12. humanin_finder-1.0.0b3/recipe/meta.yaml +61 -0
  13. humanin_finder-1.0.0b3/setup.cfg +4 -0
  14. humanin_finder-1.0.0b3/src/humanin_finder/__init__.py +4 -0
  15. humanin_finder-1.0.0b3/src/humanin_finder/cli.py +859 -0
  16. humanin_finder-1.0.0b3/src/humanin_finder/core.py +1014 -0
  17. humanin_finder-1.0.0b3/src/humanin_finder/data/Humanin_core.hmm +658 -0
  18. humanin_finder-1.0.0b3/src/humanin_finder/data/MT-RNR2.hmm +5083 -0
  19. humanin_finder-1.0.0b3/src/humanin_finder/data/PF15040.hmm +102 -0
  20. humanin_finder-1.0.0b3/src/humanin_finder/data/mdp_locus_profiles.json +189 -0
  21. humanin_finder-1.0.0b3/src/humanin_finder/data/shlp_references.json +99 -0
  22. humanin_finder-1.0.0b3/src/humanin_finder/fasta_lint.py +548 -0
  23. humanin_finder-1.0.0b3/src/humanin_finder/shlp.py +84 -0
  24. humanin_finder-1.0.0b3/src/humanin_finder.egg-info/PKG-INFO +419 -0
  25. humanin_finder-1.0.0b3/src/humanin_finder.egg-info/SOURCES.txt +33 -0
  26. humanin_finder-1.0.0b3/src/humanin_finder.egg-info/dependency_links.txt +1 -0
  27. humanin_finder-1.0.0b3/src/humanin_finder.egg-info/entry_points.txt +3 -0
  28. humanin_finder-1.0.0b3/src/humanin_finder.egg-info/requires.txt +3 -0
  29. humanin_finder-1.0.0b3/src/humanin_finder.egg-info/top_level.txt +1 -0
  30. humanin_finder-1.0.0b3/tests/__init__.py +1 -0
  31. humanin_finder-1.0.0b3/tests/test_cli.py +133 -0
  32. humanin_finder-1.0.0b3/tests/test_core.py +101 -0
  33. humanin_finder-1.0.0b3/tests/test_fasta_lint.py +33 -0
  34. humanin_finder-1.0.0b3/tests/test_regressions.py +515 -0
  35. 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
+ [![tests](https://github.com/LaBiOmicS/humaninfinder/actions/workflows/tests.yml/badge.svg)](https://github.com/LaBiOmicS/humaninfinder/actions/workflows/tests.yml)
33
+ [![PyPI](https://img.shields.io/pypi/v/humanin-finder.svg)](https://pypi.org/project/humanin-finder/)
34
+ [![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](pyproject.toml)
35
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
36
+ [![Status: beta](https://img.shields.io/badge/status-beta-orange.svg)](#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>&lt;prefix&gt;_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).