Download & Installation

Choose one installation path, verify the CLI, and then continue to First Run. The D, G, and C codes retain the nomenclature used in Additional file 2, Supporting Table 2 of the paper.

Try it before installing

The Google Colab tutorial runs the actual pheno-ranker CLI in a browser. A Google account is required to execute the cells, but no local dependency setup is needed.

Code	Installation path	Best fit
C	CPAN / Conda	Stable command-line release, installed directly or in an isolated Conda environment.
D	Docker	Reproducible environment with the CLI and companion utilities preinstalled.
G	GitHub	Current development version, repository examples, or source access.

Choose How to Run It

CPAN (C)

Use CPAN when you need pheno-ranker, bff-pxf-simulator, and csv2pheno-ranker without the repository-only Python utilities. With cpanm installed:

cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
cpanm --notest Pheno::Ranker
pheno-ranker --help

See the complete CPAN and system-dependency instructions.

Docker (D)

Use Docker when you want the full utility environment without managing Perl or Python dependencies:

docker pull manuelrueda/pheno-ranker:latest
docker image tag manuelrueda/pheno-ranker:latest cnag/pheno-ranker:latest

See the complete Docker instructions.

GitHub (G)

Install the current GitHub version directly with cpanm:

cpanm --notest https://github.com/CNAG-Biomedical-Informatics/pheno-ranker.git
pheno-ranker --help

Use a repository checkout when you need the Python utilities, local examples, tests, or editable source. See the complete GitHub installation instructions.

First Run

Download a small reference cohort and one target patient:

curl -L https://raw.githubusercontent.com/CNAG-Biomedical-Informatics/pheno-ranker/main/examples/quickstart/individuals.json -o individuals.json
curl -L https://raw.githubusercontent.com/CNAG-Biomedical-Informatics/pheno-ranker/main/examples/quickstart/patient.json -o patient.json

For a CPAN or GitHub installation (C or G), run:

pheno-ranker -r individuals.json -t patient.json -o rank.txt

For the Docker image (D), run the same analysis in the container:

docker run --rm \
  --volume "$PWD:/data" \
  --workdir /data \
  cnag/pheno-ranker:latest \
  /usr/share/pheno-ranker/bin/pheno-ranker \
  -r individuals.json -t patient.json -o rank.txt

A successful run creates rank.txt in the current directory. Its first data row is the closest reference match to the target under the default Hamming-distance ranking. Continue with Patient Mode to interpret the columns or change the analysis.

Additional Installation Methods

Isolated Conda Environment (C)

Use this method when Conda is your preferred local environment and you do not want to use Docker or modify the system Perl installation. Conda isolates the build dependencies, while Pheno-Ranker is installed from CPAN inside the environment. This remains publication installation path C; it is not a separate native Conda package. See the complete Conda environment instructions.

Developer Checkout (G)

Clone the repository when you need to inspect or modify the source, run tests, or use files that are not part of the CPAN distribution. Follow the developer checkout instructions.

Build with the Dockerfile (D)

Build locally when you need to inspect or customize the image:

docker build -f docker/Dockerfile -t cnag/pheno-ranker:latest .

Run this command from the repository root. Multi-architecture and runtime instructions are in docker/README.md.

Compatibility and Component Availability

Operating-system and component reference

The Perl CLI is tested on Linux, macOS, and Windows via GitHub Actions.

Operating system	Support
Linux	Recommended for CLI, Docker, and utility workflows.
macOS	Supported for non-containerized CLI use.
Windows	Supported for the Perl CLI; use Docker, WSL, or a Perl environment such as Strawberry Perl.

Python utilities under utils/ and external R plotting scripts are not part of the CPAN-centered Windows test matrix. For those workflows, Docker or a GitHub checkout is recommended.

Component	Available installation paths
pheno-ranker CLI	D, G, C
bff-pxf-simulator	D, G, C
csv2pheno-ranker	D, G, C
bff-pxf-plot	D, G
QR-code/PDF utilities	D, G
Web App UI (legacy)	D; supported until the end of 2026; see Pheno-Ranker UI