What is Pheno-Ranker?

Pheno-Ranker is a command-line tool for individual-level comparison of phenotypic, clinical, and other categorical records. It was designed for GA4GH-oriented data such as Beacon v2 and Phenopackets v2, but it can also compare generic JSON, YAML, and CSV-derived datasets.

The primary interface is the pheno-ranker CLI. This makes it straightforward to use from a terminal, shell scripts, R/Python automation, workflow managers, and reproducible batch analyses. A legacy Web App UI remains supported until 2027 for interactive use.

Designed for scale

Pheno-Ranker is intended for analyses that are too large to inspect manually: thousands of records in all-vs-all cohort comparisons, and hundreds of thousands to millions of reference records in patient mode when the feature space, hardware, and output choices permit it.

The central idea is simple:

1. Hierarchical records are flattened into comparable variables.
2. Variables are transformed into one-hot encoded binary vectors.
3. Vectors are compared with metrics such as Hamming distance and Jaccard similarity.
4. Results can be used for cohort exploration, patient matching, clustering, multidimensional scaling, and graph analytics.

Structured fields are flattened into a reference-derived variable universe. Every record is then encoded against the same ordered columns, making position-wise comparison possible.

Pheno-Ranker is designed to be lightweight and fast for practical cohort analyses. The CLI workflow avoids database setup, uses compact binary representations internally, and can write sparse Matrix Market output for large all-vs-all comparisons when a dense matrix is unnecessary.

Main Workflows

Cohort mode requires n(n - 1) / 2 unique record-pair comparisons. Patient mode requires n target-to-reference comparisons before ranking.

Workflow	Purpose	Main output
Cohort mode	Compare all individuals or records in one or more cohorts.	matrix.txt
Patient mode	Rank reference records against a target patient or object.	rank.txt
Generic JSON	Compare non-GA4GH categorical records using a configuration file.	matrix.txt or rank.txt
Utilities	Prepare, simulate, plot, or encode data around the main ranking workflow.	Utility-specific files

For specialized analyses, the CLI also provides include/exclude filters, variable weights, optional HPO ancestor expansion, and inspectable intermediate exports. See Usage for the full set of controls.

How to Use Pheno-Ranker

Pheno-Ranker is built on a robust Perl module, offering multiple interfaces:

• Command-line Tool: The recommended interface for direct data processing and automation.
• Web App UI: A legacy interactive interface that will be supported until 2027.

Start with Download & Installation, then follow the Usage, Cohort mode, or Patient mode pages depending on your analysis.