alp-na 1.0.0__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.
- alp_na-1.0.0/.gitignore +5 -0
- alp_na-1.0.0/CHANGELOG.md +7 -0
- alp_na-1.0.0/CMakeLists.txt +64 -0
- alp_na-1.0.0/PKG-INFO +149 -0
- alp_na-1.0.0/README.md +140 -0
- alp_na-1.0.0/alp/__init__.py +23 -0
- alp_na-1.0.0/alp/_core.py +519 -0
- alp_na-1.0.0/alp/_matrices.py +120 -0
- alp_na-1.0.0/lib/alp/LICENSE +20 -0
- alp_na-1.0.0/lib/alp/njn_approx.hpp +89 -0
- alp_na-1.0.0/lib/alp/njn_doubletype.hpp +64 -0
- alp_na-1.0.0/lib/alp/njn_dynprogprob.cpp +295 -0
- alp_na-1.0.0/lib/alp/njn_dynprogprob.hpp +236 -0
- alp_na-1.0.0/lib/alp/njn_dynprogproblim.cpp +195 -0
- alp_na-1.0.0/lib/alp/njn_dynprogproblim.hpp +165 -0
- alp_na-1.0.0/lib/alp/njn_dynprogprobproto.cpp +41 -0
- alp_na-1.0.0/lib/alp/njn_dynprogprobproto.hpp +84 -0
- alp_na-1.0.0/lib/alp/njn_function.hpp +117 -0
- alp_na-1.0.0/lib/alp/njn_integer.hpp +228 -0
- alp_na-1.0.0/lib/alp/njn_ioutil.cpp +167 -0
- alp_na-1.0.0/lib/alp/njn_ioutil.hpp +146 -0
- alp_na-1.0.0/lib/alp/njn_localmaxstat.cpp +215 -0
- alp_na-1.0.0/lib/alp/njn_localmaxstat.hpp +198 -0
- alp_na-1.0.0/lib/alp/njn_localmaxstatmatrix.cpp +157 -0
- alp_na-1.0.0/lib/alp/njn_localmaxstatmatrix.hpp +144 -0
- alp_na-1.0.0/lib/alp/njn_localmaxstatutil.cpp +533 -0
- alp_na-1.0.0/lib/alp/njn_localmaxstatutil.hpp +170 -0
- alp_na-1.0.0/lib/alp/njn_matrix.hpp +656 -0
- alp_na-1.0.0/lib/alp/njn_memutil.hpp +127 -0
- alp_na-1.0.0/lib/alp/njn_random.cpp +102 -0
- alp_na-1.0.0/lib/alp/njn_random.hpp +55 -0
- alp_na-1.0.0/lib/alp/njn_root.hpp +486 -0
- alp_na-1.0.0/lib/alp/njn_uniform.hpp +76 -0
- alp_na-1.0.0/lib/alp/njn_vector.hpp +362 -0
- alp_na-1.0.0/lib/alp/readme.txt +10 -0
- alp_na-1.0.0/lib/alp/sls_alignment_evaluer.cpp +1151 -0
- alp_na-1.0.0/lib/alp/sls_alignment_evaluer.hpp +217 -0
- alp_na-1.0.0/lib/alp/sls_alp.cpp +2366 -0
- alp_na-1.0.0/lib/alp/sls_alp.hpp +364 -0
- alp_na-1.0.0/lib/alp/sls_alp_data.cpp +1654 -0
- alp_na-1.0.0/lib/alp/sls_alp_data.hpp +937 -0
- alp_na-1.0.0/lib/alp/sls_alp_regression.cpp +723 -0
- alp_na-1.0.0/lib/alp/sls_alp_regression.hpp +174 -0
- alp_na-1.0.0/lib/alp/sls_alp_sim.cpp +4549 -0
- alp_na-1.0.0/lib/alp/sls_alp_sim.hpp +579 -0
- alp_na-1.0.0/lib/alp/sls_basic.cpp +196 -0
- alp_na-1.0.0/lib/alp/sls_basic.hpp +222 -0
- alp_na-1.0.0/lib/alp/sls_normal_distr_array.hpp +151 -0
- alp_na-1.0.0/lib/alp/sls_pvalues.cpp +1301 -0
- alp_na-1.0.0/lib/alp/sls_pvalues.hpp +306 -0
- alp_na-1.0.0/pyproject.toml +88 -0
- alp_na-1.0.0/src/alp_api.cpp +159 -0
- alp_na-1.0.0/src/alp_api.h +125 -0
- alp_na-1.0.0/tests/test_alp.py +243 -0
- alp_na-1.0.0/uv.lock +1697 -0
alp_na-1.0.0/.gitignore
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
cmake_minimum_required(VERSION 3.15)
|
|
2
|
+
project(alp LANGUAGES CXX)
|
|
3
|
+
|
|
4
|
+
set(CMAKE_CXX_STANDARD 17)
|
|
5
|
+
set(CMAKE_CXX_STANDARD_REQUIRED ON)
|
|
6
|
+
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
|
|
7
|
+
# Link the MSVC C++ runtime statically: Python ships vcruntime140.dll but not
|
|
8
|
+
# msvcp140.dll, so a dynamically linked libalp.dll could fail to load.
|
|
9
|
+
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded")
|
|
10
|
+
|
|
11
|
+
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
|
|
12
|
+
set(CMAKE_BUILD_TYPE Release)
|
|
13
|
+
endif()
|
|
14
|
+
|
|
15
|
+
set(ALP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/lib/alp)
|
|
16
|
+
set(ALP_SRCS
|
|
17
|
+
${ALP_DIR}/njn_dynprogprob.cpp
|
|
18
|
+
${ALP_DIR}/njn_dynprogproblim.cpp
|
|
19
|
+
${ALP_DIR}/njn_dynprogprobproto.cpp
|
|
20
|
+
${ALP_DIR}/njn_ioutil.cpp
|
|
21
|
+
${ALP_DIR}/njn_localmaxstat.cpp
|
|
22
|
+
${ALP_DIR}/njn_localmaxstatmatrix.cpp
|
|
23
|
+
${ALP_DIR}/njn_localmaxstatutil.cpp
|
|
24
|
+
${ALP_DIR}/njn_random.cpp
|
|
25
|
+
${ALP_DIR}/sls_alignment_evaluer.cpp
|
|
26
|
+
${ALP_DIR}/sls_alp.cpp
|
|
27
|
+
${ALP_DIR}/sls_alp_data.cpp
|
|
28
|
+
${ALP_DIR}/sls_alp_regression.cpp
|
|
29
|
+
${ALP_DIR}/sls_alp_sim.cpp
|
|
30
|
+
${ALP_DIR}/sls_basic.cpp
|
|
31
|
+
${ALP_DIR}/sls_pvalues.cpp
|
|
32
|
+
)
|
|
33
|
+
# Third-party public-domain NCBI code: silence its warnings.
|
|
34
|
+
if(MSVC)
|
|
35
|
+
set_source_files_properties(${ALP_SRCS} PROPERTIES COMPILE_OPTIONS "/w")
|
|
36
|
+
else()
|
|
37
|
+
set_source_files_properties(${ALP_SRCS} PROPERTIES COMPILE_OPTIONS "-w")
|
|
38
|
+
endif()
|
|
39
|
+
|
|
40
|
+
add_library(alp SHARED src/alp_api.cpp ${ALP_SRCS})
|
|
41
|
+
target_include_directories(alp PRIVATE ${ALP_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/src)
|
|
42
|
+
# File name is libalp.so / libalp.dylib / libalp.dll. The library is loaded with
|
|
43
|
+
# ctypes, so all symbols are exported on Windows, and the output goes straight
|
|
44
|
+
# into the build dir (the $<0:> genex suppresses per-config subdirectories).
|
|
45
|
+
set_target_properties(alp PROPERTIES
|
|
46
|
+
PREFIX "lib"
|
|
47
|
+
WINDOWS_EXPORT_ALL_SYMBOLS ON
|
|
48
|
+
LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}$<0:>"
|
|
49
|
+
RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}$<0:>"
|
|
50
|
+
)
|
|
51
|
+
if(MSVC)
|
|
52
|
+
target_compile_options(alp PRIVATE /O2)
|
|
53
|
+
else()
|
|
54
|
+
target_compile_options(alp PRIVATE -O2)
|
|
55
|
+
endif()
|
|
56
|
+
if(NOT WIN32)
|
|
57
|
+
target_link_libraries(alp PRIVATE m)
|
|
58
|
+
endif()
|
|
59
|
+
|
|
60
|
+
# Used by scikit-build-core to place the library inside the `alp` package.
|
|
61
|
+
install(TARGETS alp
|
|
62
|
+
LIBRARY DESTINATION alp
|
|
63
|
+
RUNTIME DESTINATION alp
|
|
64
|
+
)
|
alp_na-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
Metadata-Version: 2.2
|
|
2
|
+
Name: alp-na
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Gumbel (Karlin-Altschul) parameters for local alignment scores via the NCBI ALP library
|
|
5
|
+
Author: NaturalAntibody
|
|
6
|
+
Project-URL: Homepage, https://github.com/NaturalAntibody/alp
|
|
7
|
+
Requires-Python: >=3.9
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
|
|
10
|
+
# alp
|
|
11
|
+
|
|
12
|
+
Standalone Python wrapper over the NCBI **ALP** library ([Sheetlin & Frith, ALP & FALP: C++ libraries for pairwise local alignment E-values](https://academic.oup.com/bioinformatics/article/32/2/304/1744607)) for computing the Gumbel / Karlin–Altschul parameters
|
|
13
|
+
(λ, K and the finite-size corrections a, b, α, β, σ, τ) of local alignment
|
|
14
|
+
scores. Use these parameters to turn raw Smith–Waterman scores into bit-scores
|
|
15
|
+
and E-values.
|
|
16
|
+
|
|
17
|
+
The directory is self-contained: it ships its own copy of ALP (`lib/alp`), a
|
|
18
|
+
small C API (`src/alp_api.{h,cpp}`), a CMake build and a ctypes package
|
|
19
|
+
with **no runtime Python dependencies**.
|
|
20
|
+
|
|
21
|
+
## Install
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install alp-na # prebuilt wheels for Linux, macOS and Windows
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The distribution is named `alp-na` on PyPI (`alp` is taken by an unrelated
|
|
28
|
+
project); the import name is still `alp`.
|
|
29
|
+
|
|
30
|
+
## Development
|
|
31
|
+
|
|
32
|
+
The project is managed with [uv](https://docs.astral.sh/uv/) and built with
|
|
33
|
+
[scikit-build-core](https://scikit-build-core.readthedocs.io/) (CMake). You need
|
|
34
|
+
a C++17 compiler; CMake is installed into the isolated build environment
|
|
35
|
+
automatically.
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
uv sync # create .venv, build libalp, install dev deps
|
|
39
|
+
uv run pytest # run the tests
|
|
40
|
+
uv build # build the sdist and a wheel for this machine into dist/
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`uv sync` rebuilds the library whenever `CMakeLists.txt` or a C++ source
|
|
44
|
+
changes; the CMake build tree is kept in `build/` so rebuilds are incremental.
|
|
45
|
+
|
|
46
|
+
The shared library (`libalp.so` / `libalp.dylib` / `libalp.dll`) is looked up in
|
|
47
|
+
the package directories, then in `./build/` (a plain
|
|
48
|
+
`cmake -B build && cmake --build build`); `ALP_LIB=/path/to/libalp.so`
|
|
49
|
+
overrides both.
|
|
50
|
+
|
|
51
|
+
## Releasing
|
|
52
|
+
|
|
53
|
+
Every push to `master` runs `.github/workflows/ci.yml`: python-semantic-release
|
|
54
|
+
bumps the version from the conventional commits (and refreshes `uv.lock`),
|
|
55
|
+
cibuildwheel builds one `py3-none` wheel each for Linux (x86_64, aarch64), macOS
|
|
56
|
+
(universal2) and Windows (AMD64), `uv build --sdist` builds the sdist, and
|
|
57
|
+
`uv publish` uploads everything to PyPI with trusted publishing.
|
|
58
|
+
|
|
59
|
+
## Usage
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
from alp import compute_gumbel_params
|
|
63
|
+
|
|
64
|
+
# Built-in BLOSUM (45/50/62/80/90) with Robinson & Robinson background freqs
|
|
65
|
+
p = compute_gumbel_params("blosum62", gap_open=11, gap_extend=1)
|
|
66
|
+
p.lambda_, p.K # (0.2741, 0.0494)
|
|
67
|
+
|
|
68
|
+
# Any dict-of-dicts matrix, e.g. from the `blosum` package
|
|
69
|
+
import blosum
|
|
70
|
+
p = compute_gumbel_params(blosum.BLOSUM(62), gap_open=11, gap_extend=1)
|
|
71
|
+
|
|
72
|
+
# Square integer array (list of lists / numpy) + optional alphabet
|
|
73
|
+
p = compute_gumbel_params(my_matrix, alphabet="ACGT", bg_freqs=[.3, .2, .2, .3],
|
|
74
|
+
gap_open=5, gap_extend=2)
|
|
75
|
+
|
|
76
|
+
# Match / mismatch scoring (default alphabet ACGT, uniform frequencies)
|
|
77
|
+
p = compute_gumbel_params(match=2, mismatch=3, gap_open=5, gap_extend=2)
|
|
78
|
+
|
|
79
|
+
# Omit gap penalties for (exact, analytic) gapless statistics
|
|
80
|
+
p = compute_gumbel_params("blosum62")
|
|
81
|
+
|
|
82
|
+
# Statistics
|
|
83
|
+
p.bit_score(55)
|
|
84
|
+
p.evalue(55, query_length=120, subject_length=1_000_000) # ALP finite-size corrected
|
|
85
|
+
p.pvalue(55, 120, 1_000_000)
|
|
86
|
+
p.to_dict(), p.as_tuple(), p.errors # errors = ALP std. errors
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`GumbelParams(*stored_tuple)` rebuilds a parameter set from saved values, so
|
|
90
|
+
the (sub-second to ~1 min) simulation only needs to run once per scoring
|
|
91
|
+
system. Within a process, results are also memoised.
|
|
92
|
+
|
|
93
|
+
### Options
|
|
94
|
+
|
|
95
|
+
| argument | default | meaning |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| `alphabet` | auto | symbol order; for dict matrices the 20 standard amino acids are used when present (B/Z/X/\* are dropped) |
|
|
98
|
+
| `bg_freqs`, `bg_freqs2` | Robinson for 20 AA, else uniform | `"uniform"`, `"robinson"`/`"blast"` (BLAST's Robinson & Robinson), `"blosum62"`/`"mmseqs"` (BLOSUM62 background, as in MMseqs2), a mapping, or a sequence; `bg_freqs2` for sequence #2 |
|
|
99
|
+
| `gap_convention` | `"ncbi"` | `"ncbi"`: gap of length k costs `open + k·extend` (ALP, BLAST, MMseqs2). `"open_includes_extend"`: `open + (k−1)·extend` (SSW, parasail); converted before calling ALP |
|
|
100
|
+
| `n_samples` | 20000 | fixed number of simulation samples, so results are bit-identical for given inputs and seed. `None` = ALP's adaptive mode (see below) |
|
|
101
|
+
| `n_preliminary_samples` | 200 | samples per preliminary stage (fixed mode) |
|
|
102
|
+
| `lambda_tolerance`, `k_tolerance` | 0.01, 0.05 | target relative errors (adaptive mode only) |
|
|
103
|
+
| `max_seconds` | `None` | no time limit by default. If set, it is a hard timeout (`ALPError`) in fixed and gapless mode; in adaptive mode it is ALP's planning budget (default 60 s) |
|
|
104
|
+
| `max_mem_mb` | 500 | memory limit |
|
|
105
|
+
| `seed` | 42 | random seed |
|
|
106
|
+
|
|
107
|
+
`ValueError` is raised for invalid input, including scoring systems with no
|
|
108
|
+
valid local statistics (no positive score or non-negative expected score).
|
|
109
|
+
`ALPError` is raised when ALP itself fails.
|
|
110
|
+
|
|
111
|
+
## Notes
|
|
112
|
+
|
|
113
|
+
* **Reproducibility.** By default ALP chooses its sample sizes adaptively,
|
|
114
|
+
from the tolerances *and* from measured run time. With a binding time
|
|
115
|
+
limit, results then depend on machine speed and load: BLOSUM62 9/1 on a
|
|
116
|
+
loaded machine gave K and α values 3.5% and 10% different. This package
|
|
117
|
+
therefore defaults to a fixed plan (`n_samples=20000`). Results are
|
|
118
|
+
bit-identical across runs, load and `max_seconds`. They depend only on
|
|
119
|
+
the inputs, the seed and the build: across platforms and compilers the
|
|
120
|
+
random sample paths are the same, but floating-point rounding differs in
|
|
121
|
+
the last digits (~1e-14 relative; checked in CI on Linux, macOS and Windows).
|
|
122
|
+
* **Accuracy vs `n_samples`.** Statistical error is roughly ∝ 1/√n and
|
|
123
|
+
runtime is linear in n. At 20000, λ is good to ≤0.5% and K to ≤2%. The
|
|
124
|
+
finite-size α/σ converge more slowly and are biased low at small n for
|
|
125
|
+
low gap costs. Raise `n_samples` (e.g. 100000) when E-values for short
|
|
126
|
+
sequences matter. Runtime at 20000 is ~2.5 s for BLOSUM62 11/1, ~10 s for
|
|
127
|
+
9/1 and ~36 s for BLOSUM45 16/1.
|
|
128
|
+
* `n_samples=None` (seed 42, tolerances 0.01/0.05, 60 s) reproduces
|
|
129
|
+
MMseqs2's ALP settings.
|
|
130
|
+
* `lib/alp` is vendored NCBI ALP with one patch (`sls_alignment_evaluer.cpp`,
|
|
131
|
+
marked "alp-python patch"). In fixed-plan mode, the gapless pre-step
|
|
132
|
+
originally had a hard-coded 120 s cap; it now honours `max_seconds`, and has
|
|
133
|
+
no limit when that is unset.
|
|
134
|
+
* Gapless parameters are exact. They reproduce BLAST's ungapped rows with
|
|
135
|
+
Robinson frequencies and MMseqs2's gapless BLOSUM62 entry with
|
|
136
|
+
`bg_freqs="mmseqs"`.
|
|
137
|
+
* C API: see `src/alp_api.h` (`gumbel_compute`, `gumbel_evalue`).
|
|
138
|
+
|
|
139
|
+
## Comparison with BLAST and MMseqs2 tables
|
|
140
|
+
|
|
141
|
+
`scripts/compare_blast.py` recomputes every precomputed row in BLAST's
|
|
142
|
+
`blast_stat.c` (BLOSUM45–90, all blastn reward/penalty tables). It also adds
|
|
143
|
+
MMseqs2's hard-coded entries from `EvalueComputation.h` where they exist:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
python scripts/compare_blast.py path/to/blast_stat.c \
|
|
147
|
+
--mmseqs path/to/EvalueComputation.h --csv cmp.csv --md cmp.md \
|
|
148
|
+
[--n-samples 100000] # or --n-samples 0 for ALP adaptive mode
|
|
149
|
+
```
|
alp_na-1.0.0/README.md
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# alp
|
|
2
|
+
|
|
3
|
+
Standalone Python wrapper over the NCBI **ALP** library ([Sheetlin & Frith, ALP & FALP: C++ libraries for pairwise local alignment E-values](https://academic.oup.com/bioinformatics/article/32/2/304/1744607)) for computing the Gumbel / Karlin–Altschul parameters
|
|
4
|
+
(λ, K and the finite-size corrections a, b, α, β, σ, τ) of local alignment
|
|
5
|
+
scores. Use these parameters to turn raw Smith–Waterman scores into bit-scores
|
|
6
|
+
and E-values.
|
|
7
|
+
|
|
8
|
+
The directory is self-contained: it ships its own copy of ALP (`lib/alp`), a
|
|
9
|
+
small C API (`src/alp_api.{h,cpp}`), a CMake build and a ctypes package
|
|
10
|
+
with **no runtime Python dependencies**.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pip install alp-na # prebuilt wheels for Linux, macOS and Windows
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The distribution is named `alp-na` on PyPI (`alp` is taken by an unrelated
|
|
19
|
+
project); the import name is still `alp`.
|
|
20
|
+
|
|
21
|
+
## Development
|
|
22
|
+
|
|
23
|
+
The project is managed with [uv](https://docs.astral.sh/uv/) and built with
|
|
24
|
+
[scikit-build-core](https://scikit-build-core.readthedocs.io/) (CMake). You need
|
|
25
|
+
a C++17 compiler; CMake is installed into the isolated build environment
|
|
26
|
+
automatically.
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
uv sync # create .venv, build libalp, install dev deps
|
|
30
|
+
uv run pytest # run the tests
|
|
31
|
+
uv build # build the sdist and a wheel for this machine into dist/
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`uv sync` rebuilds the library whenever `CMakeLists.txt` or a C++ source
|
|
35
|
+
changes; the CMake build tree is kept in `build/` so rebuilds are incremental.
|
|
36
|
+
|
|
37
|
+
The shared library (`libalp.so` / `libalp.dylib` / `libalp.dll`) is looked up in
|
|
38
|
+
the package directories, then in `./build/` (a plain
|
|
39
|
+
`cmake -B build && cmake --build build`); `ALP_LIB=/path/to/libalp.so`
|
|
40
|
+
overrides both.
|
|
41
|
+
|
|
42
|
+
## Releasing
|
|
43
|
+
|
|
44
|
+
Every push to `master` runs `.github/workflows/ci.yml`: python-semantic-release
|
|
45
|
+
bumps the version from the conventional commits (and refreshes `uv.lock`),
|
|
46
|
+
cibuildwheel builds one `py3-none` wheel each for Linux (x86_64, aarch64), macOS
|
|
47
|
+
(universal2) and Windows (AMD64), `uv build --sdist` builds the sdist, and
|
|
48
|
+
`uv publish` uploads everything to PyPI with trusted publishing.
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from alp import compute_gumbel_params
|
|
54
|
+
|
|
55
|
+
# Built-in BLOSUM (45/50/62/80/90) with Robinson & Robinson background freqs
|
|
56
|
+
p = compute_gumbel_params("blosum62", gap_open=11, gap_extend=1)
|
|
57
|
+
p.lambda_, p.K # (0.2741, 0.0494)
|
|
58
|
+
|
|
59
|
+
# Any dict-of-dicts matrix, e.g. from the `blosum` package
|
|
60
|
+
import blosum
|
|
61
|
+
p = compute_gumbel_params(blosum.BLOSUM(62), gap_open=11, gap_extend=1)
|
|
62
|
+
|
|
63
|
+
# Square integer array (list of lists / numpy) + optional alphabet
|
|
64
|
+
p = compute_gumbel_params(my_matrix, alphabet="ACGT", bg_freqs=[.3, .2, .2, .3],
|
|
65
|
+
gap_open=5, gap_extend=2)
|
|
66
|
+
|
|
67
|
+
# Match / mismatch scoring (default alphabet ACGT, uniform frequencies)
|
|
68
|
+
p = compute_gumbel_params(match=2, mismatch=3, gap_open=5, gap_extend=2)
|
|
69
|
+
|
|
70
|
+
# Omit gap penalties for (exact, analytic) gapless statistics
|
|
71
|
+
p = compute_gumbel_params("blosum62")
|
|
72
|
+
|
|
73
|
+
# Statistics
|
|
74
|
+
p.bit_score(55)
|
|
75
|
+
p.evalue(55, query_length=120, subject_length=1_000_000) # ALP finite-size corrected
|
|
76
|
+
p.pvalue(55, 120, 1_000_000)
|
|
77
|
+
p.to_dict(), p.as_tuple(), p.errors # errors = ALP std. errors
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`GumbelParams(*stored_tuple)` rebuilds a parameter set from saved values, so
|
|
81
|
+
the (sub-second to ~1 min) simulation only needs to run once per scoring
|
|
82
|
+
system. Within a process, results are also memoised.
|
|
83
|
+
|
|
84
|
+
### Options
|
|
85
|
+
|
|
86
|
+
| argument | default | meaning |
|
|
87
|
+
|---|---|---|
|
|
88
|
+
| `alphabet` | auto | symbol order; for dict matrices the 20 standard amino acids are used when present (B/Z/X/\* are dropped) |
|
|
89
|
+
| `bg_freqs`, `bg_freqs2` | Robinson for 20 AA, else uniform | `"uniform"`, `"robinson"`/`"blast"` (BLAST's Robinson & Robinson), `"blosum62"`/`"mmseqs"` (BLOSUM62 background, as in MMseqs2), a mapping, or a sequence; `bg_freqs2` for sequence #2 |
|
|
90
|
+
| `gap_convention` | `"ncbi"` | `"ncbi"`: gap of length k costs `open + k·extend` (ALP, BLAST, MMseqs2). `"open_includes_extend"`: `open + (k−1)·extend` (SSW, parasail); converted before calling ALP |
|
|
91
|
+
| `n_samples` | 20000 | fixed number of simulation samples, so results are bit-identical for given inputs and seed. `None` = ALP's adaptive mode (see below) |
|
|
92
|
+
| `n_preliminary_samples` | 200 | samples per preliminary stage (fixed mode) |
|
|
93
|
+
| `lambda_tolerance`, `k_tolerance` | 0.01, 0.05 | target relative errors (adaptive mode only) |
|
|
94
|
+
| `max_seconds` | `None` | no time limit by default. If set, it is a hard timeout (`ALPError`) in fixed and gapless mode; in adaptive mode it is ALP's planning budget (default 60 s) |
|
|
95
|
+
| `max_mem_mb` | 500 | memory limit |
|
|
96
|
+
| `seed` | 42 | random seed |
|
|
97
|
+
|
|
98
|
+
`ValueError` is raised for invalid input, including scoring systems with no
|
|
99
|
+
valid local statistics (no positive score or non-negative expected score).
|
|
100
|
+
`ALPError` is raised when ALP itself fails.
|
|
101
|
+
|
|
102
|
+
## Notes
|
|
103
|
+
|
|
104
|
+
* **Reproducibility.** By default ALP chooses its sample sizes adaptively,
|
|
105
|
+
from the tolerances *and* from measured run time. With a binding time
|
|
106
|
+
limit, results then depend on machine speed and load: BLOSUM62 9/1 on a
|
|
107
|
+
loaded machine gave K and α values 3.5% and 10% different. This package
|
|
108
|
+
therefore defaults to a fixed plan (`n_samples=20000`). Results are
|
|
109
|
+
bit-identical across runs, load and `max_seconds`. They depend only on
|
|
110
|
+
the inputs, the seed and the build: across platforms and compilers the
|
|
111
|
+
random sample paths are the same, but floating-point rounding differs in
|
|
112
|
+
the last digits (~1e-14 relative; checked in CI on Linux, macOS and Windows).
|
|
113
|
+
* **Accuracy vs `n_samples`.** Statistical error is roughly ∝ 1/√n and
|
|
114
|
+
runtime is linear in n. At 20000, λ is good to ≤0.5% and K to ≤2%. The
|
|
115
|
+
finite-size α/σ converge more slowly and are biased low at small n for
|
|
116
|
+
low gap costs. Raise `n_samples` (e.g. 100000) when E-values for short
|
|
117
|
+
sequences matter. Runtime at 20000 is ~2.5 s for BLOSUM62 11/1, ~10 s for
|
|
118
|
+
9/1 and ~36 s for BLOSUM45 16/1.
|
|
119
|
+
* `n_samples=None` (seed 42, tolerances 0.01/0.05, 60 s) reproduces
|
|
120
|
+
MMseqs2's ALP settings.
|
|
121
|
+
* `lib/alp` is vendored NCBI ALP with one patch (`sls_alignment_evaluer.cpp`,
|
|
122
|
+
marked "alp-python patch"). In fixed-plan mode, the gapless pre-step
|
|
123
|
+
originally had a hard-coded 120 s cap; it now honours `max_seconds`, and has
|
|
124
|
+
no limit when that is unset.
|
|
125
|
+
* Gapless parameters are exact. They reproduce BLAST's ungapped rows with
|
|
126
|
+
Robinson frequencies and MMseqs2's gapless BLOSUM62 entry with
|
|
127
|
+
`bg_freqs="mmseqs"`.
|
|
128
|
+
* C API: see `src/alp_api.h` (`gumbel_compute`, `gumbel_evalue`).
|
|
129
|
+
|
|
130
|
+
## Comparison with BLAST and MMseqs2 tables
|
|
131
|
+
|
|
132
|
+
`scripts/compare_blast.py` recomputes every precomputed row in BLAST's
|
|
133
|
+
`blast_stat.c` (BLOSUM45–90, all blastn reward/penalty tables). It also adds
|
|
134
|
+
MMseqs2's hard-coded entries from `EvalueComputation.h` where they exist:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
python scripts/compare_blast.py path/to/blast_stat.c \
|
|
138
|
+
--mmseqs path/to/EvalueComputation.h --csv cmp.csv --md cmp.md \
|
|
139
|
+
[--n-samples 100000] # or --n-samples 0 for ALP adaptive mode
|
|
140
|
+
```
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""Gumbel (Karlin-Altschul) parameters for local alignment via NCBI ALP."""
|
|
2
|
+
|
|
3
|
+
from ._core import (
|
|
4
|
+
ALPError,
|
|
5
|
+
GumbelParams,
|
|
6
|
+
BLOSUM62_FREQS,
|
|
7
|
+
ROBINSON_FREQS,
|
|
8
|
+
compute_gumbel_params,
|
|
9
|
+
match_mismatch_matrix,
|
|
10
|
+
)
|
|
11
|
+
from ._matrices import AA_ALPHABET, BLOSUM
|
|
12
|
+
|
|
13
|
+
__all__ = [
|
|
14
|
+
"AA_ALPHABET",
|
|
15
|
+
"ALPError",
|
|
16
|
+
"BLOSUM",
|
|
17
|
+
"GumbelParams",
|
|
18
|
+
"BLOSUM62_FREQS",
|
|
19
|
+
"ROBINSON_FREQS",
|
|
20
|
+
"compute_gumbel_params",
|
|
21
|
+
"match_mismatch_matrix",
|
|
22
|
+
]
|
|
23
|
+
__version__ = "1.0.0"
|