ldpart 0.1.0__tar.gz

ldpart-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gennady Khvorykh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ldpart-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: ldpart
+Version: 0.1.0
+Summary: Certified multicollinearity partitioning of LD matrices into blocks of correlated SNPs
+Author-email: Gennady Khvorykh <info@inzilico.com>
+License: MIT
+Project-URL: Homepage, https://github.com/gkhvorykh/ldpart
+Project-URL: Documentation, https://github.com/gkhvorykh/ldpart#readme
+Keywords: linkage disequilibrium,LD blocks,multicollinearity,variance inflation factor,population genetics,genetics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: h5py>=3.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# Linkage Disequilibrium Partition (ldpart)
+
+Certified multicollinearity partitioning of linkage disequilibrium (LD) matrices: group SNPs
+into contiguous blocks of correlated SNPs with greedy criteria built
+on classical multicollinearity diagnostics.
+
+Every saved block is **certified** — its submatrix of the LD matrix
+provably satisfies the criterion — and the monotone criteria
+(determinant, condition number, maximal VIF) additionally certify that
+every block is **maximal**: no neighbouring SNP could join it without
+violating the criterion. NaN values never extend a block.
+
+## Criteria
+
+| function | method | criterion | certified | maximal | cost per candidate |
+|---|---|---|---|---|---|
+| `partition_by_determinant` | `fast` | det(block) > θ (Schur updates) | yes | yes (det is monotone under growth) | O(k²) |
+| `partition_by_determinant_slogdet` | `slogdet` | det(block) > θ (LAPACK reference) | yes | yes | O(k³) |
+| `partition_by_condition` | `condition` | κ(block) = λmax/\|λmin\| ≤ θ | yes | yes (Cauchy interlacing) | O(k³) |
+| `partition_by_vif` | `vif` | max VIF = max diag(R⁻¹) ≤ θ | yes | yes (nested regressions) | O(k³) |
+| `partition_by_reciprocal_eigenvalues` | `reciprocal` | Σ 1/λq ≤ θ·k | yes | no (the ratio can recover) | O(k³) |
+| `partition_by_pairwise` | `pairwise` | max r2(candidate, member) ≥ θ | yes (pairwise sense) | — marginal screen | O(k) |
+
+Classical operating points: det θ = 0.001, κ = 1000 (squared Belsley
+CN ≈ 31.6), VIF 5/10, Σ1/λ ≈ 5·k (Chatterjee & Price), pairwise
+r² = 0.8.
+
+The determinant, condition, VIF and reciprocal criteria certify that
+a block is **not too jointly redundant** (joint criteria); the
+pairwise criterion groups SNPs that **are** in LD (marginal screen).
+Their cuts land in different places — the joint criteria cut inside
+strong LD where redundancy accumulates, the pairwise criterion cuts
+where LD has decayed.
+
+## Install
+
+```bash
+pip install ldpart
+```
+
+## Python API
+
+The input is a square symmetric LD matrix (r or r2, 1 on the
+diagonal, SNPs ordered as the rows and columns) — a numpy array or an
+open h5py dataset (the matrix is streamed row by row, never copied).
+
+```python
+import h5py
+from ldpart import partition_by_determinant, labels_to_blocks
+
+with h5py.File("ld.h5", "r") as f:
+    matrix = f["r2"]
+    labels, nblocks = partition_by_determinant(matrix, min_det=0.001)
+
+blocks = labels_to_blocks(labels)   # [(block, [snp indexes]), ...]
+```
+
+Every function returns `(labels, nblocks)`, where labels is a per-SNP
+list of `[index, block]` with blocks numbered from 1.
+
+## Command line
+
+```bash
+ldpart -i ld.h5 -o labels.txt                       # det 0.001
+ldpart -i ld.h5 -o labels.txt -m condition -c 1000
+ldpart -i ld.h5 -o labels.txt -m vif -v 10
+ldpart -i ld.h5 -o labels.txt -m reciprocal -r 5
+ldpart -i ld.h5 -o labels.txt -m pairwise -p 0.8
+```
+
+The output has two columns, the zero-based SNP index and the block
+label.
+
+## Semantics
+
+- **Greedy growth:** the block starting at SNP i1 is extended by the
+  candidate SNP j only while the criterion holds over the window
+  matrix[i1:j+1, i1:j+1] *including the candidate*; the first failing
+  candidate seeds the next block, so blocks are contiguous and every
+  block satisfies its criterion at its final size and at every prefix.
+- **Certified maximality:** the determinant can only decrease when a
+  SNP is added (Schur complement: each step multiplies it by
+  1 − R² ≤ 1), the condition number cannot recover (Cauchy
+  interlacing), the maximal VIF cannot recover (nested regressions) —
+  so the greedy cut yields the largest admissible block. The sum of
+  reciprocal eigenvalues per window size can recover, so its blocks
+  are certified but not maximal.
+- **NaN semantics:** a NaN anywhere in the candidate window (or the
+  candidate's row segment for the pairwise screen) fails the
+  extension — NaN never silently extends a block. A SNP with a NaN
+  diagonal stays a singleton seed.
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest tests
+```
+
+The suite holds property tests on random correlation matrices:
+certification of every block by independent LAPACK recomputation,
+maximality of the monotone criteria against brute force, the NaN
+semantics, fast/slogdet agreement, numpy/h5py equivalence, and the
+command line interface end to end.
+
+## References
+
+- Rogers & Huff (2008), *Heredity* — the r² estimator used in the
+  companion study.
+- Belsley, Kuh & Welsch (1980) — regression diagnostics, condition
+  indices.
+- Chatterjee & Price (1977); Dillon & Goldstein (1984) — the
+  sum-of-reciprocal-eigenvalues rule.
+- Khvorykh, G., Khrunin, A., 2025. Determinant-based grouping of SNPs and its application for detecting disease-associated genomic loci. NAR Genomics and Bioinformatics 7. https://doi.org/10.1093/nargab/lqaf024
+- The method is developed and validated in the LD matrix partition study (in preparation)
+
+  
+## License
+
+MIT © Gennady Khvorykh
+
+## Author
+
+Gennady Khvorykh, info [at] inzilico.com

ldpart-0.1.0/README.md

@@ -0,0 +1,124 @@
+# Linkage Disequilibrium Partition (ldpart)
+
+Certified multicollinearity partitioning of linkage disequilibrium (LD) matrices: group SNPs
+into contiguous blocks of correlated SNPs with greedy criteria built
+on classical multicollinearity diagnostics.
+
+Every saved block is **certified** — its submatrix of the LD matrix
+provably satisfies the criterion — and the monotone criteria
+(determinant, condition number, maximal VIF) additionally certify that
+every block is **maximal**: no neighbouring SNP could join it without
+violating the criterion. NaN values never extend a block.
+
+## Criteria
+
+| function | method | criterion | certified | maximal | cost per candidate |
+|---|---|---|---|---|---|
+| `partition_by_determinant` | `fast` | det(block) > θ (Schur updates) | yes | yes (det is monotone under growth) | O(k²) |
+| `partition_by_determinant_slogdet` | `slogdet` | det(block) > θ (LAPACK reference) | yes | yes | O(k³) |
+| `partition_by_condition` | `condition` | κ(block) = λmax/\|λmin\| ≤ θ | yes | yes (Cauchy interlacing) | O(k³) |
+| `partition_by_vif` | `vif` | max VIF = max diag(R⁻¹) ≤ θ | yes | yes (nested regressions) | O(k³) |
+| `partition_by_reciprocal_eigenvalues` | `reciprocal` | Σ 1/λq ≤ θ·k | yes | no (the ratio can recover) | O(k³) |
+| `partition_by_pairwise` | `pairwise` | max r2(candidate, member) ≥ θ | yes (pairwise sense) | — marginal screen | O(k) |
+
+Classical operating points: det θ = 0.001, κ = 1000 (squared Belsley
+CN ≈ 31.6), VIF 5/10, Σ1/λ ≈ 5·k (Chatterjee & Price), pairwise
+r² = 0.8.
+
+The determinant, condition, VIF and reciprocal criteria certify that
+a block is **not too jointly redundant** (joint criteria); the
+pairwise criterion groups SNPs that **are** in LD (marginal screen).
+Their cuts land in different places — the joint criteria cut inside
+strong LD where redundancy accumulates, the pairwise criterion cuts
+where LD has decayed.
+
+## Install
+
+```bash
+pip install ldpart
+```
+
+## Python API
+
+The input is a square symmetric LD matrix (r or r2, 1 on the
+diagonal, SNPs ordered as the rows and columns) — a numpy array or an
+open h5py dataset (the matrix is streamed row by row, never copied).
+
+```python
+import h5py
+from ldpart import partition_by_determinant, labels_to_blocks
+
+with h5py.File("ld.h5", "r") as f:
+    matrix = f["r2"]
+    labels, nblocks = partition_by_determinant(matrix, min_det=0.001)
+
+blocks = labels_to_blocks(labels)   # [(block, [snp indexes]), ...]
+```
+
+Every function returns `(labels, nblocks)`, where labels is a per-SNP
+list of `[index, block]` with blocks numbered from 1.
+
+## Command line
+
+```bash
+ldpart -i ld.h5 -o labels.txt                       # det 0.001
+ldpart -i ld.h5 -o labels.txt -m condition -c 1000
+ldpart -i ld.h5 -o labels.txt -m vif -v 10
+ldpart -i ld.h5 -o labels.txt -m reciprocal -r 5
+ldpart -i ld.h5 -o labels.txt -m pairwise -p 0.8
+```
+
+The output has two columns, the zero-based SNP index and the block
+label.
+
+## Semantics
+
+- **Greedy growth:** the block starting at SNP i1 is extended by the
+  candidate SNP j only while the criterion holds over the window
+  matrix[i1:j+1, i1:j+1] *including the candidate*; the first failing
+  candidate seeds the next block, so blocks are contiguous and every
+  block satisfies its criterion at its final size and at every prefix.
+- **Certified maximality:** the determinant can only decrease when a
+  SNP is added (Schur complement: each step multiplies it by
+  1 − R² ≤ 1), the condition number cannot recover (Cauchy
+  interlacing), the maximal VIF cannot recover (nested regressions) —
+  so the greedy cut yields the largest admissible block. The sum of
+  reciprocal eigenvalues per window size can recover, so its blocks
+  are certified but not maximal.
+- **NaN semantics:** a NaN anywhere in the candidate window (or the
+  candidate's row segment for the pairwise screen) fails the
+  extension — NaN never silently extends a block. A SNP with a NaN
+  diagonal stays a singleton seed.
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest tests
+```
+
+The suite holds property tests on random correlation matrices:
+certification of every block by independent LAPACK recomputation,
+maximality of the monotone criteria against brute force, the NaN
+semantics, fast/slogdet agreement, numpy/h5py equivalence, and the
+command line interface end to end.
+
+## References
+
+- Rogers & Huff (2008), *Heredity* — the r² estimator used in the
+  companion study.
+- Belsley, Kuh & Welsch (1980) — regression diagnostics, condition
+  indices.
+- Chatterjee & Price (1977); Dillon & Goldstein (1984) — the
+  sum-of-reciprocal-eigenvalues rule.
+- Khvorykh, G., Khrunin, A., 2025. Determinant-based grouping of SNPs and its application for detecting disease-associated genomic loci. NAR Genomics and Bioinformatics 7. https://doi.org/10.1093/nargab/lqaf024
+- The method is developed and validated in the LD matrix partition study (in preparation)
+
+  
+## License
+
+MIT © Gennady Khvorykh
+
+## Author
+
+Gennady Khvorykh, info [at] inzilico.com

ldpart-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ldpart"
+version = "0.1.0"
+description = "Certified multicollinearity partitioning of LD matrices into blocks of correlated SNPs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Gennady Khvorykh", email = "info@inzilico.com" }]
+keywords = [
+    "linkage disequilibrium",
+    "LD blocks",
+    "multicollinearity",
+    "variance inflation factor",
+    "population genetics",
+    "genetics",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "numpy>=1.20",
+    "h5py>=3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/gkhvorykh/ldpart"
+Documentation = "https://github.com/gkhvorykh/ldpart#readme"
+
+[project.scripts]
+ldpart = "ldpart.cli:main"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

ldpart-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ldpart-0.1.0/src/ldpart/__init__.py

@@ -0,0 +1,36 @@
+"""
+ldpart: certified multicollinearity partitioning of LD matrices.
+
+Group SNPs into contiguous blocks of correlated SNPs from a square LD
+matrix (r or r2 with 1 on the diagonal, SNPs ordered as the rows and
+columns), with six greedy criteria built on classical
+multicollinearity diagnostics: the determinant (fast Schur updates
+and the LAPACK slogdet reference), the condition number, the maximal
+variance inflation factor, the sum of reciprocal eigenvalues, and the
+marginal pairwise r2 screen. Every saved block is certified: it
+satisfies its criterion, and the monotone criteria additionally
+certify maximality. See partitioner for the semantics.
+"""
+
+from .partitioner import (
+    partition_by_determinant,
+    partition_by_determinant_slogdet,
+    partition_by_condition,
+    partition_by_vif,
+    partition_by_reciprocal_eigenvalues,
+    partition_by_pairwise,
+    labels_to_blocks,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "partition_by_determinant",
+    "partition_by_determinant_slogdet",
+    "partition_by_condition",
+    "partition_by_vif",
+    "partition_by_reciprocal_eigenvalues",
+    "partition_by_pairwise",
+    "labels_to_blocks",
+    "__version__",
+]

ldpart-0.1.0/src/ldpart/cli.py

@@ -0,0 +1,115 @@
+"""
+Command line interface of ldpart: partition a square LD matrix into
+blocks of correlated SNPs by a multicollinearity criterion. The input
+file holds the matrix (1 on the diagonal, SNPs ordered as the rows and
+columns) in HDF5; the output holds two columns, the zero-based SNP
+index and the block label of every SNP, the format consumed by the
+reproducibility layer of the ld-matrix-partition-01 project.
+
+Installed as the console script `ldpart`:
+
+    ldpart -i LD.h5 -o labels.txt -m fast -d 0.001
+    ldpart -i LD.h5 -o labels.txt -m condition -c 1000
+    ldpart -i LD.h5 -o labels.txt -m vif -v 10
+    ldpart -i LD.h5 -o labels.txt -m reciprocal -r 5
+    ldpart -i LD.h5 -o labels.txt -m pairwise -p 0.8
+"""
+
+import argparse
+import time
+
+import numpy as np
+import h5py
+
+from . import __version__
+from .helpers import (attach_matrix, check_input_files,
+                      check_output_dir, show_time_elapsed)
+from .partitioner import (
+    partition_by_determinant,
+    partition_by_determinant_slogdet,
+    partition_by_condition,
+    partition_by_vif,
+    partition_by_reciprocal_eigenvalues,
+    partition_by_pairwise,
+)
+
+# Method -> (partition function, criterion argument, printed label)
+METHODS = {
+    "fast": (partition_by_determinant, "min_det", "Minimal determinant"),
+    "slogdet": (partition_by_determinant_slogdet, "min_det",
+                "Minimal determinant"),
+    "condition": (partition_by_condition, "max_cond",
+                  "Maximal condition number"),
+    "vif": (partition_by_vif, "max_vif", "Maximal VIF"),
+    "reciprocal": (partition_by_reciprocal_eigenvalues, "max_ratio",
+                   "Maximal sum of reciprocal eigenvalues per block "
+                   "size"),
+    "pairwise": (partition_by_pairwise, "min_r2",
+                 "Minimal pairwise r2"),
+}
+
+
+def parser_args(argv=None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="ldpart",
+        description="Partition a square LD matrix into blocks of "
+                    "correlated SNPs by a multicollinearity criterion")
+    parser.add_argument("-i", "--input", required=True,
+                        help="/path/to/input.h5 with the matrix in "
+                             "HDF5 format")
+    parser.add_argument("-o", "--output", required=True,
+                        help="/path/to/output.txt for the block labels")
+    parser.add_argument("-d", "--min_det", type=float, default=0.001,
+                        help="minimal determinant of a block submatrix, "
+                             "methods fast and slogdet (default 0.001)")
+    parser.add_argument("-c", "--max_cond", type=float, default=1000.0,
+                        help="maximal condition number of a block "
+                             "submatrix, method condition "
+                             "(default 1000)")
+    parser.add_argument("-v", "--max_vif", type=float, default=10.0,
+                        help="maximal variance inflation factor of a "
+                             "block submatrix, method vif (default 10)")
+    parser.add_argument("-r", "--max_ratio", type=float, default=5.0,
+                        help="maximal sum of reciprocal eigenvalues "
+                             "per block size, method reciprocal "
+                             "(default 5)")
+    parser.add_argument("-p", "--min_r2", type=float, default=0.8,
+                        help="minimal pairwise r2 between the "
+                             "candidate and a block member, method "
+                             "pairwise (default 0.8)")
+    parser.add_argument("-m", "--method", choices=tuple(METHODS),
+                        default="fast",
+                        help="partition function: fast, slogdet, "
+                             "condition, vif, reciprocal or pairwise "
+                             "(default fast)")
+    parser.add_argument("--version", action="version",
+                        version=f"ldpart {__version__}")
+    return parser.parse_args(argv)
+
+
+def main(argv=None) -> None:
+    args = parser_args(argv)
+    ts = time.time()
+
+    check_input_files([args.input])
+    check_output_dir(args.output)
+
+    print("Input:", args.input)
+    print("Output:", args.output)
+    print("Method:", args.method)
+
+    fun, arg_name, label = METHODS[args.method]
+    params = {arg_name: getattr(args, arg_name)}
+    print(label + ":", params[arg_name])
+
+    with h5py.File(args.input, "r") as f:
+        matrix = attach_matrix(f)
+        labels, nblocks = fun(matrix, **params)
+
+    np.savetxt(args.output, labels, delimiter=" ", fmt="%d")
+    print("Number of blocks:", nblocks)
+    show_time_elapsed(ts)
+
+
+if __name__ == "__main__":
+    main()

ldpart-0.1.0/src/ldpart/helpers.py

@@ -0,0 +1,57 @@
+"""
+Assisting functions of the ldpart command line interface: the LD
+matrix is read straight from its HDF5 dataset (no copy into memory),
+and the small file and folder checks live here. Trimmed from the
+helpers of the ld-matrix-partition-01 project, pandas free.
+"""
+
+import os
+import sys
+import time
+from typing import Union
+
+import h5py
+
+
+def attach_matrix(file_obj: h5py.File) -> Union[h5py.Dataset,
+                                                h5py.Group]:
+    """
+    The square matrix of the first object of an open HDF5 file: a
+    plain dataset, or a group of chunked pandas arrays
+    (block0_values).
+    """
+    key = list(file_obj.keys())[0]
+    obj = file_obj[key]
+    if isinstance(obj, h5py.Dataset):
+        ds_obj = obj
+    elif isinstance(obj, h5py.Group):
+        ds_obj = obj["block0_values"]
+    else:
+        print("Unknown type of dataset")
+        sys.exit(1)
+
+    n, m = ds_obj.shape[0], ds_obj.shape[1]
+    if n != m:
+        print("Dataset is not a square matrix")
+        sys.exit(1)
+    print(f"Dataset shape: {n} x {m}")
+    return ds_obj
+
+
+def check_output_dir(output: str) -> None:
+    # Create the folder holding an output path when missing
+    dir_name = os.path.dirname(output)
+    if dir_name:
+        os.makedirs(dir_name, exist_ok=True)
+
+
+def check_input_files(files: list) -> None:
+    for file in files:
+        if file and not os.path.isfile(file):
+            print(f"{file} doesn't exist")
+            sys.exit(1)
+
+
+def show_time_elapsed(ts: float) -> None:
+    dur = time.strftime("%H:%M:%S", time.gmtime(time.time() - ts))
+    print("Time spent:", dur)