pharmacoml docs
Reference

Command and API reference

This page collects the detailed usage patterns for the current release: installation commands, benchmark commands, the main HybridScreener workflow, output methods, and the experimental consensus namespace.

Installation commands

Install from PyPI

pip install pharmacoml

Install from GitHub

pip install git+https://github.com/s-rani1/pharmacoml.git

Editable install for development

git clone https://github.com/s-rani1/pharmacoml.git
cd pharmacoml
pip install -e ".[dev]"

Optional extras

pip install -e ".[dev,dl,symbolic]"

Main API

The default production path is HybridScreener.

from pharmacoml.covselect import HybridScreener

report = HybridScreener(
    include_scm=True,
    rfe_enabled=True,
    shrinkage_awareness=True,
    include_interactions=False,
    include_symbolic=False,
).fit(
    ebes=ebes,
    covariates=covariates,
    parameter_shrinkage={"CL": 0.12, "V": 0.28},
)

Required inputs

  • ebes: one row per subject, columns such as CL, V, KA, or other subject-level parameters
  • covariates: one row per subject, aligned to ebes

Optional credibility inputs

  • parameter_shrinkage: explicit shrinkage values from the base model
  • preserve_proxy_pairs: user-specified biologically distinct proxy pairs
  • include_interactions: post-RFE interaction screening

Common HybridScreener options

Option Default Purpose When to change it
include_scm True Enable the SCM-style confirmation layer Turn this off only if you want a pure screening pass without the confirmation step.
rfe_enabled True Use the benchmark-backed recursive feature elimination path Keep this on for most users. Disable it only if you want a faster, less-pruned first-pass screen.
shrinkage_awareness True Apply shrinkage-aware calibration when shrinkage information or low-information proxy signals are available Leave this on for real PMx work. Turn it off only for method comparison or if you explicitly want unadjusted screening behavior.
parameter_shrinkage None Pass known per-parameter shrinkage values from your base model Provide this whenever you have trusted shrinkage values from a base NONMEM, nlmixr2, or similar run. It improves credibility for weak-ETA parameters.
include_interactions False Generate and screen pairwise interaction terms after the main-effect RFE path Turn this on when you suspect meaningful interaction effects or want to test non-additive relationships after the main-effect shortlist is stable.
interaction_top_n 5 Limit interaction generation to the strongest retained main effects Reduce this for smaller datasets or when interactions become noisy; increase it only if you have enough subjects and a strong reason to search more pairs.
preserve_proxy_pairs None Keep biologically distinct but highly correlated covariates such as AGE and PMA Use this when you already know specific correlated covariates should both remain visible in the shortlist for domain reasons.
preserve_biological_distinctness False Auto-preserve near-deterministic but biologically distinct covariate pairs Enable this when you want the workflow to be more permissive with pairs like AGE/PMA without enumerating them manually.
include_symbolic False Enable symbolic structure search Turn this on when you want interpretable functional-form suggestions beyond the standard screening outputs.
symbolic_backend "basis" Select basis, gplearn, or pysr when symbolic screening is enabled Use basis for lightweight default behavior; use gplearn or pysr only when you explicitly want experimental symbolic-regression backends installed.

The current defaults are benchmark-backed. For most users, the main knobs worth changing first are parameter_shrinkage, include_interactions, and preserve_proxy_pairs.

Output methods

Method Meaning Typical use
summary() Full row-level screening table Detailed inspection and debugging
confirmed_covariates() Compact confirmed answer Daily-use summary
candidate_covariates() Broader shortlist Carry forward to formal PMx confirmation
core_covariates() Strongest ML-supported signals Inspect the AI/ML layer directly
proxy_groups() Correlated alternatives Interpretation and deduplication
interaction_covariates() Surviving interaction terms Interaction review when enabled
to_nonmem_candidates() Text export for downstream workflows NONMEM-style candidate block generation
For most users, the practical order is: confirmed_covariates() → candidate_covariates() → proxy_groups() → to_nonmem_candidates().

Benchmark commands

# Run the fixed public benchmark suite and generate reports
PYTHONPATH=. python benchmarks/run_public_benchmarks.py
# Enforce the pinned release gate
PYTHONPATH=. python benchmarks/run_public_benchmarks.py --check
# Write reports to a custom directory
PYTHONPATH=. python benchmarks/run_public_benchmarks.py --report-dir docs/reports
# Skip report artifacts
PYTHONPATH=. python benchmarks/run_public_benchmarks.py --no-report

The benchmark runner writes Markdown, CSV, and JSON report artifacts by default.

Experimental namespace

Use the experimental module for advanced benchmarking and model-family comparison. The default daily-use recommendation remains HybridScreener. 

from pharmacoml.covselect.experimental import MultiModelConsensusScreener

report = MultiModelConsensusScreener(
    top_k=3,
    n_bootstrap=8,
    include_neural=False,
).fit(ebes, covariates)

report.consensus_covariates()
report.selection_frequency_table()
report.family_summary()
report.compare_with_hybrid(ebes, covariates)

Practical guidance

Use HybridScreener when:

  • you want a benchmark-backed shortlist for routine PMx work
  • you have EBEs or individual parameters from a base model
  • you want a compact confirmed answer plus a broader shortlist

Use the experimental namespace when:

  • you want model-family comparison
  • you are benchmarking or stress-testing the hybrid workflow
  • you are comfortable with a research-oriented interface