Documentation overview
Compare cohorts or rank reference records against a target.
Pheno-Ranker compares structured phenotypic, clinical, and categorical
records. This documentation covers input preparation, command-line use,
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 primary interface is the pheno-ranker command-line tool, which can be used
directly or called from 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 |
Patient mode runs one command:
pheno-ranker -r cohort.json -t target.json
The resulting 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 CLI writes 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.
- Install and complete a first run.
- 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 is the primary interface. The legacy Web App remains supported until the end of 2026.
Project Links
GitHub repository · CPAN distribution · Publication and citation · Web App UI