PyHLicorn

PyHLicorn is an efficient Python library for inferring cooperative Gene Regulatory Networks (GRNs) directly from transcriptomic expression data, based on the hybrid h-LICORN algorithm.

By modeling combinatorial interactions among transcription factors (TFs)—identifying co-activator and co-repressor complexes—PyHLicorn bridges discrete pattern mining and continuous expression modeling. It features vertical bitset candidate mining, compact integer representation, exact concordance pre-screening, a native C scoring kernel, and scalable multicore execution.

Key Features

• Exact Model Parity: Mathematically reproduces the model selection of the reference R implementation (R-hLICORN / CoRegNet) while eliminating legacy bottlenecks.
• High Performance: Achieves up to 26.2× speedups and over 82% peak memory reduction on real bulk transcriptomic cohorts (e.g., TCGA breast cancer).
• Scalable Multicore Execution: Seamless parallelization across CPU cores via Joblib (loky backend) with optional distributed PySpark support.
• Adaptive Memory Management: Automatically manages candidate regulator pools with in-memory arrays and spill-to-disk safeguards for large combinatorial spaces.
• Command-Line Interface: Installed pyhlicorn command and bundled run_inference.py script for automated batch processing and pipeline execution.
• Self-Contained Demo: Packaged example dataset accessible via Python (pyhlicorn.load_example_data()) or CLI (pyhlicorn --demo).

Installation

From PyPI (Recommended)

Install the released package directly via pip:

pip install pyhlicorn

Pre-compiled binary wheels are distributed for common architectures (Linux x86_64, macOS Apple Silicon, macOS Intel, and Windows).

Compiler Requirements for Source Distributions

When installing from source (.tar.gz) or if a pre-compiled wheel is unavailable for your specific platform/Python version, pip compiles the high-performance C scoring kernel during installation. This requires a standard C compiler and Python development headers:

• Linux (Ubuntu/Debian): sudo apt-get install build-essential python3-dev
• Linux (RHEL/CentOS/Fedora): sudo dnf install gcc python3-devel
• macOS: xcode-select --install
• Windows: Microsoft C++ Build Tools (MSVC 14.0 or newer)

From Source (Development)

Clone the repository and install in editable mode:

git clone https://github.com/wajdidhifli/PyHLicorn.git
cd PyHLicorn
pip install -e .

Optional Dependencies

• Distributed PySpark execution: pip install 'pyhlicorn[spark]'
• Memory profiling & monitoring: pip install 'pyhlicorn[monitor]'

Quickstart

1. Python API

import pyhlicorn

# 1. Load data (use bundled example dataset, or pass custom pandas DataFrames/CSVs)
expression, tfs = pyhlicorn.load_example_data()

# 2. Configure HLicorn with recommended algorithmic parameters
inference = pyhlicorn.HLicorn(
    min_gene_support=0.10,     # Gene non-zero variation cutoff
    min_coreg_support=0.10,    # Minimum co-regulator support
    max_coreg=3,               # Maximum co-regulator complex size (K=3)
    search_thresh=1/3,          # Target-regulator concordance cutoff
    nGRN=100                   # Rank cutoff per target
)

# 3. Configure execution backend and scoring model
inference.setJoblib(n_jobs=4, backend='loky')  # Parallel multicore execution
inference.setLinearModel('lm')                 # Ordinary Least Squares (or 'cvlm')

# 4. Fit regulatory models (auto-discretizes if discrete matrix is omitted)
network = inference.fit(
    numerical_expression=expression,
    tf_list=tfs
)

# 5. Inspect and export results
print(network.GRN.head())
network.save_as_json('inferred_network.json')

2. Command-Line Interface (pyhlicorn)

When installed via pip, the pyhlicorn command is added directly to your environment:

# Instant verification on bundled demonstration data:
pyhlicorn --demo

# Basic run with your own expression and TF files:
pyhlicorn \
    --expr path/to/expression.csv \
    --tf path/to/tfs.txt \
    --n-jobs 4

# Advanced run with custom outputs and fit-quality filtering:
pyhlicorn \
    --expr data/CIT_BLCA_EXP.csv \
    --tf data/HumanTF.csv \
    --max-coreg 3 \
    --min-coreg-support 0.10 \
    --n-jobs 8 \
    --min-r2 0.30 \
    --out-csv inferred_grn.csv \
    --out-json inferred_network.json.gz \
    --compact-json

(Note: In a cloned repository checkout, python run_inference.py provides the identical CLI functionality.)

Configuration & Parameters

1. Mandatory Inputs

These inputs are strictly required for network inference (unless using --demo):

2. Recommended Parameters

These parameters govern the combinatorial search space, regulatory biology, and parallel execution:

3. Optional & Advanced Parameters

These options allow customizing discretization, restricting target genes, managing memory, and exporting results:

Testing & Verification

The test suite validates pattern mining, mathematical equivalence, and memory policies:

pytest tests/ -v

References & Attribution

If you use PyHLicorn in your research, please cite:

• PyHLicorn: Dhifli, W., Abu Awad, M., Kotob, J., Karabadji, N. E., Assi, A., & Elati, M. (2026). PyHLicorn: efficient cooperative gene regulatory network inference in Python. (Manuscript under review).
• h-LICORN: Chebil, I., Nicolle, R., Santini, G., Rouveirol, C., & Elati, M. (2014). Hybrid method inference for the construction of cooperative regulatory network in human. IEEE Transactions on NanoBioscience, 13(2), 97–103. DOI: 10.1109/TNB.2014.2316920.
• LICORN: Elati, M., Neuvial, P., Bolotin-Fukuhara, M., Barillot, E., Radvanyi, F., & Rouveirol, C. (2007). LICORN: learning cooperative regulation networks from gene expression data. Bioinformatics, 23(18), 2407–2414. DOI: 10.1093/bioinformatics/btm352.
• CoRegNet: Nicolle, R., Radvanyi, F., & Elati, M. (2015). CoRegNet: reconstruction and integrated analysis of co-regulatory networks. Bioinformatics, 31(18), 3066–3068. DOI: 10.1093/bioinformatics/btv305.

License

This project is licensed under the GNU General Public License v3.0.