Download & Installation

Desktop App

For the graphical interface, download a Windows, macOS, or Linux installer from GitHub Releases. The engine and runtimes are included. See the Desktop installation and visual quickstart for platform-specific instructions, and Desktop storage and removal for data locations, updates, uninstalling, and resetting local history.

Download DesktopDesktop guide

Command-Line Interface

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	Stable command-line release installed into an existing Perl environment.
C	Isolated Conda environment	Stable CPAN release without modifying the system Perl installation.
G	GitHub	Current development version, repository examples, or source access.
D	Docker	Reproducible environment with the CLI and companion utilities preinstalled.

The Perl CLI is tested on Linux, macOS, and Windows. Docker is the simplest way to obtain the full collection of Perl and Python utilities; CPAN and Conda are appropriate when you primarily need the pheno-ranker CLI.

Choose How to Run It

Method 1: CPAN (C)

Use CPAN when cpanm is already configured to install modules for your user. This installs pheno-ranker, bff-pxf-simulator, and csv2pheno-ranker:

cpanm --notest Pheno::Ranker
pheno-ranker --help

If cpanm reports a permission error or is not installed, follow the complete CPAN and user-local installation instructions.

Method 2: Conda (C)

Use an isolated Conda environment when you prefer Conda but do not want to modify the system Perl installation. Pheno-Ranker is installed from CPAN inside that environment; it is not a separate native Conda package.

The compiler package differs between Linux and macOS, so follow the platform-aware Conda instructions.

Method 3: 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.

Method 4: Docker Hub (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.

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

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.

Method 5: 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; replaced by the Desktop App from v1.09; see legacy Pheno-Ranker UI documentation

From v1.09, the Desktop App provides a local graphical interface. Desktop installation is separate from the CLI installation methods; their numbering and publication codes above remain unchanged.