Documentation overview
Compare cohorts or rank reference records against a target.
Pheno-Ranker compares structured phenotypic, clinical, and categorical
records. This documentation covers Desktop and CLI use, input preparation,
interpretation, and downstream analysis.
What Pheno-Ranker Does
Pheno-Ranker answers two questions:
- Which records in one or more cohorts are most similar to each other?
- Which records in a reference cohort are most similar to a target patient or object?
The Desktop App provides interactive analysis and result exploration
from v1.09. The same engine is available through the pheno-ranker CLI for shell
scripts, R, Python, notebooks, workflow managers, and batch analyses.
It reads Beacon v2 and Phenopackets v2 directly. Other clinical standards can be converted to BFF, while generic JSON, YAML, and CSV-derived categorical datasets use a small configuration.
A Small Example
Suppose a reference cohort contains two records and the target has fever and
cough:
| Record | Present features |
|---|---|
| Reference A | fever, cough |
| Reference B | fever, rash |
| Target | fever, cough |
In Patient ranking, select the reference cohort and target, then run the
analysis. The ranking, also saved as rank.txt, places Reference A first:
| Rank | Reference | Hamming distance | Jaccard index |
|---|---|---|---|
| 1 | Reference A | 0 | 1.000 |
| 2 | Reference B | 2 | 0.333 |
Reference A has the same categorical profile as the target. Reference B shares
fever, but differs on cough and rash. The same principle applies to larger
clinical records and reference cohorts.
Main Workflows
| Workflow | Purpose | Main output |
|---|---|---|
| Cohort mode | Compare all records in one or more cohorts. | matrix.txt |
| Patient mode | Rank reference records against a target. | rank.txt |
| Clinical formats | Convert supported clinical standards to BFF before comparison. | BFF individuals.json |
| Generic JSON | Compare configured categorical records outside BFF/PXF. | matrix.txt or rank.txt |
How the comparison works
- Hierarchical records are flattened into comparable categorical variables.
- Every record is encoded against the same ordered variable list.
- The resulting binary vectors are compared with Hamming distance or Jaccard similarity.
- The analysis produces an all-vs-all matrix or a target-to-reference ranking.
Pheno-Ranker requires no database setup and uses compact binary representations internally. Patient mode performs one comparison per reference record, whereas cohort mode compares every unique pair. Runtime and memory therefore depend on the cohort size, number of variables, metric, and output format. See the Algorithm page for the complete method.
Next Steps
- Choose an input format for native BFF/PXF, converted clinical data, CSV, or generic JSON/YAML.
- Start with Desktop or install and run the CLI.
- Read the CLI reference or follow the visual User Workflow.
- Continue with Use from R, use cases, or companion utilities.
Project Status
The documentation follows the current GitHub version; the latest CPAN release can differ between releases. Consult the Changes file for version-specific updates. The CLI remains supported. From v1.09, the Desktop App replaces the legacy Web App UI as the graphical interface.
Project Links
GitHub repository · CPAN distribution · Publication and citation · Legacy Web App UI · Legacy UI documentation
The legacy Web App UI remains available for browser-based use; see the FAQ.