Patient Mode

Patient mode ranks records in a reference cohort against a target patient or object. It uses the same flattened variables and binary-vector representation as cohort mode, but the output is a ranked table instead of an all-vs-all matrix.

Use patient mode when you want to find the closest matches to a patient profile, inspect which variables overlap, or assess match significance with Z-scores and p-values.

ComparesTarget against reference records

InputsReference cohort(s) and one target

Main outputrank.txt

Best forClosest matches and alignment review

What You Get

• rank.txt: ranked matches between the target and the reference cohort.
• Variable-level alignments for inspecting shared and differing terms when alignment output is enabled.
• Intermediate hashes, vectors, labels, and coverage statistics when intermediate export is enabled.
• Hamming distance, Jaccard similarity, Z-scores, p-values, and overlap statistics for each match.

For all-vs-all comparison instead, see Cohort Mode.

Usage

Both interfaces calculate the same metrics for the same inputs and settings.

Desktop

1. Select Patient ranking, then choose an input source. Examples > Load example supplies both reference and target records.
2. For your own data, select the reference cohort(s) and target under User files. Add any required configuration under Advanced settings.
3. Under Customize analysis, choose Rank by and Maximum ranked records, then select Run analysis.
4. Open the completed run and select a reference ID in the ranking to inspect its comparison with the target. Differences only focuses on mismatched terms.

Generate alignment is enabled by default under Output options. See the Desktop guide for the result viewer.

CLI

pheno-ranker -r individuals.json -t patient.json

This creates rank.txt, sorted by Hamming distance by default. Use --sort-by jaccard to rank by Jaccard similarity, --max-out to limit the reported matches, and --align to generate variable-level alignments. See the CLI Reference for all options.

CLI example: extract target records from a cohort

pheno-ranker -r t/data/individuals.json --patients-of-interest 107:week_0_arm_1 125:week_0_arm_1

This command will carry out a dry-run, creating 107:week_0_arm_1.json and 125:week_0_arm_1.json files. On Windows, characters that are invalid in filenames are percent-encoded, so 107:week_0_arm_1 is written as 107%3Aweek_0_arm_1.json. In the example above, I renamed 107:week_0_arm_1.json to patient.json by typing this:

mv 107:week_0_arm_1.json patient.json

Read the Ranking

The Desktop ranking table and the saved rank.txt use the same columns. The first rows are the best matches according to the selected sorting metric.

How to read rank.txt

Read the table in three steps:

1. Start with RANK and REFERENCE(ID) to identify the best matches.
2. Check the selected metric: lower HAMMING-DISTANCE values or higher JACCARD-INDEX values indicate more similar profiles.
3. Check INTERSECT-RATE(%) and COMPLETENESS(%) to confirm that the match is supported by enough shared information.

The Z-scores and p-values describe how each match relates to the comparisons in that run. They are supporting statistics rather than universal clinical significance thresholds. Their definitions are available in the full column reference below.

Full rank.txt column reference

Identifiers and run metadata

• RANK: Match order. A rank of 1 is the best match.
• REFERENCE(ID): The unique identifier (primary_key) for the reference individual.
• TARGET(ID): The unique identifier (primary_key) for the selected target individual.
• FORMAT: Input format used by the configuration, such as BFF, PXF, or CSV.
• WEIGHTED: Whether the calculation used variable weights.

Alignment size

• LENGTH: Count of variables that have a 1 in either the reference or the target. In other words, this is the size of the comparison space for that pair.

LENGTH example

REF: 0001001
TAR: 1000001

In this case, LENGTH is 3 because three positions have a 1 in at least one vector.

Similarity and distance metrics

• HAMMING-DISTANCE: Count of positions where the reference and target binary vectors differ. Lower values indicate more similar profiles.
• JACCARD-INDEX: Similarity between the reference and target vectors, calculated as the intersection divided by the union. Higher values indicate more similar profiles.

Metric definitions

Hamming distance counts mismatches between two binary strings of equal length.

Jaccard similarity focuses on shared 1 values:

$$\text{Jaccard} = \frac{\text{Intersection}}{\text{Union}}$$

Significance statistics

• DISTANCE-Z-SCORE: Empirical Z-score for the observed Hamming distance compared with all target-reference comparisons in the run.
• DISTANCE-P-VALUE: Statistical significance associated with DISTANCE-Z-SCORE.
• DISTANCE-Z-SCORE(RAND): Estimated Z-score for two random binary vectors, assuming the alignment size is equal to LENGTH.
• JACCARD-Z-SCORE: Empirical Z-score for the observed Jaccard index compared with all target-reference comparisons in the run.
• JACCARD-P-VALUE: Statistical significance associated with JACCARD-Z-SCORE.

DISTANCE-Z-SCORE(RAND) calculation

This value comes from the estimated mean and standard deviation of the Hamming distance for binary strings. It assumes that each position has a 50% chance of being a mismatch, independently of other positions.

The expected mean is:

$$\text{Estimated Average} = \text{Length} \times \text{Probability of Mismatch}$$

where the probability of mismatch is set to 0.5.

The standard deviation is:

$$\text{Estimated Standard Deviation} = \sqrt{\text{Length} \times \text{Probability of Mismatch} \times (1 - \text{Probability of Mismatch})}$$

Finally, the formula for the Z-score is:

$Z = \frac{(X - \mu)}{\sigma}$

where ( X ) is the observed value, ( \mu ) is the estimated mean, and ( \sigma ) is the estimated standard deviation.

Variable overlap

• REFERENCE-VARS: Total number of variables present in the reference.
• TARGET-VARS: Total number of variables present in the target.
• INTERSECT: Number of variables shared by the reference and target.
• INTERSECT-RATE(%): Percentage of target variables also present in the reference.
• COMPLETENESS(%): Percentage of reference variables also present in the target.

INTERSECT-RATE(%) calculation

INTERSECT-RATE(%) measures how much of the target profile is covered by the reference:

$$\text{INTERSECT-RATE(\%)} = \frac{\text{Intersection Count}}{\text{Number of Variables in Target}} \times 100$$

COMPLETENESS(%) calculation

COMPLETENESS(%) measures how much of the reference profile is covered by the target:

$$\text{COMPLETENESS(\%)} = \frac{\text{Intersection Count}}{\text{Number of Variables in Reference}} \times 100$$

See results from rank.txt

RANK	REFERENCE(ID)	TARGET(ID)	FORMAT	LENGTH	WEIGHTED	HAMMING-DISTANCE	DISTANCE-Z-SCORE	DISTANCE-P-VALUE	DISTANCE-Z-SCORE(RAND)	JACCARD-INDEX	JACCARD-Z-SCORE	JACCARD-P-VALUE	REFERENCE-VARS	TARGET-VARS	INTERSECT	INTERSECT-RATE(%)	COMPLETENESS(%)
1	107:week_0_arm_1	107:week_0_arm_1	BFF	77	False	0	-2.419	0.0077787	-8.7750	1.000	2.949	0.0256500	77	77	77	100.00	100.00
2	125:week_0_arm_1	107:week_0_arm_1	BFF	79	False	6	-1.924	0.0271576	-7.5381	0.924	2.269	0.1022693	75	77	73	94.81	97.33
3	275:week_0_arm_1	107:week_0_arm_1	BFF	86	False	14	-1.265	0.1030165	-6.2543	0.837	1.491	0.3117348	81	77	72	93.51	88.89
4	215:week_0_arm_1	107:week_0_arm_1	BFF	88	False	16	-1.100	0.1357515	-5.9696	0.818	1.321	0.3742868	83	77	72	93.51	86.75
5	305:week_0_arm_1	107:week_0_arm_1	BFF	89	False	18	-0.935	0.1749800	-5.6180	0.798	1.138	0.4452980	83	77	71	92.21	85.54
6	365:week_0_arm_1	107:week_0_arm_1	BFF	87	False	20	-0.770	0.2207314	-5.0389	0.770	0.890	0.5437899	77	77	67	87.01	87.01
7	125:week_14_arm_1	107:week_0_arm_1	BFF	78	False	23	-0.522	0.3007259	-3.6233	0.705	0.308	0.7555423	56	77	55	71.43	98.21
8	527:week_14_arm_1	107:week_0_arm_1	BFF	78	False	23	-0.522	0.3007259	-3.6233	0.705	0.308	0.7555423	56	77	55	71.43	98.21
9	107:week_14_arm_1	107:week_0_arm_1	BFF	78	False	23	-0.522	0.3007259	-3.6233	0.705	0.308	0.7555423	56	77	55	71.43	98.21
10	125:week_2_arm_1	107:week_0_arm_1	BFF	78	False	23	-0.522	0.3007259	-3.6233	0.705	0.308	0.7555423	56	77	55	71.43	98.21
11	107:week_2_arm_1	107:week_0_arm_1	BFF	78	False	24	-0.440	0.3300253	-3.3968	0.692	0.193	0.7901267	55	77	54	70.13	98.18
12	125:week_26_arm_1	107:week_0_arm_1	BFF	78	False	24	-0.440	0.3300253	-3.3968	0.692	0.193	0.7901267	55	77	54	70.13	98.18
13	527:week_2_arm_1	107:week_0_arm_1	BFF	78	False	24	-0.440	0.3300253	-3.3968	0.692	0.193	0.7901267	55	77	54	70.13	98.18
14	527:week_0_arm_1	107:week_0_arm_1	BFF	98	False	24	-0.440	0.3300253	-5.0508	0.755	0.756	0.5965581	95	77	74	96.10	77.89
15	365:week_2_arm_1	107:week_0_arm_1	BFF	79	False	25	-0.357	0.3604065	-3.2628	0.684	0.115	0.8120159	56	77	54	70.13	96.43
16	275:week_2_arm_1	107:week_0_arm_1	BFF	79	False	25	-0.357	0.3604065	-3.2628	0.684	0.115	0.8120159	56	77	54	70.13	96.43
17	305:week_26_arm_1	107:week_0_arm_1	BFF	79	False	26	-0.275	0.3916958	-3.0377	0.671	0.001	0.8410353	55	77	53	68.83	96.36
18	365:week_14_arm_1	107:week_0_arm_1	BFF	80	False	26	-0.275	0.3916958	-3.1305	0.675	0.038	0.8319440	57	77	54	70.13	94.74
19	215:week_2_arm_1	107:week_0_arm_1	BFF	78	False	27	-0.192	0.4237022	-2.7175	0.654	-0.151	0.8752035	52	77	51	66.23	98.08
20	215:week_26_arm_1	107:week_0_arm_1	BFF	78	False	27	-0.192	0.4237022	-2.7175	0.654	-0.151	0.8752035	52	77	51	66.23	98.08
21	257:week_0_arm_1	107:week_0_arm_1	BFF	102	False	29	-0.027	0.4890344	-4.3566	0.716	0.403	0.7249040	98	77	73	94.81	74.49
22	215:week_14_arm_1	107:week_0_arm_1	BFF	84	False	29	-0.027	0.4890344	-2.8368	0.655	-0.143	0.8735091	62	77	55	71.43	88.71
23	275:week_14_arm_1	107:week_0_arm_1	BFF	80	False	30	0.055	0.5219230	-2.2361	0.625	-0.410	0.9206854	53	77	50	64.94	94.34
24	365:week_26_arm_1	107:week_0_arm_1	BFF	83	False	30	0.055	0.5219230	-2.5246	0.639	-0.288	0.9011791	59	77	53	68.83	89.83
25	215:week_78_arm_1	107:week_0_arm_1	BFF	86	False	32	0.220	0.5870339	-2.3723	0.628	-0.384	0.9167688	63	77	54	70.13	85.71
26	527:week_26_arm_1	107:week_0_arm_1	BFF	86	False	32	0.220	0.5870339	-2.3723	0.628	-0.384	0.9167688	63	77	54	70.13	85.71
27	125:week_78_arm_1	107:week_0_arm_1	BFF	94	False	40	0.880	0.8104854	-1.4440	0.574	-0.862	0.9687183	71	77	54	70.13	76.06
28	527:week_52_arm_1	107:week_0_arm_1	BFF	98	False	43	1.127	0.8701495	-1.2122	0.561	-0.981	0.9761986	76	77	55	71.43	72.37
29	125:week_52_arm_1	107:week_0_arm_1	BFF	98	False	43	1.127	0.8701495	-1.2122	0.561	-0.981	0.9761986	76	77	55	71.43	72.37
30	365:week_52_arm_1	107:week_0_arm_1	BFF	99	False	45	1.292	0.9018282	-0.9045	0.545	-1.122	0.9830870	76	77	54	70.13	71.05
31	257:week_14_arm_1	107:week_0_arm_1	BFF	99	False	45	1.292	0.9018282	-0.9045	0.545	-1.122	0.9830870	76	77	54	70.13	71.05
32	305:week_52_arm_1	107:week_0_arm_1	BFF	99	False	45	1.292	0.9018282	-0.9045	0.545	-1.122	0.9830870	76	77	54	70.13	71.05
33	257:week_2_arm_1	107:week_0_arm_1	BFF	99	False	45	1.292	0.9018282	-0.9045	0.545	-1.122	0.9830870	76	77	54	70.13	71.05
34	215:week_52_arm_1	107:week_0_arm_1	BFF	104	False	49	1.622	0.9475899	-0.5883	0.529	-1.271	0.9884232	82	77	55	71.43	67.07
35	257:week_26_arm_1	107:week_0_arm_1	BFF	103	False	50	1.704	0.9558461	-0.2956	0.515	-1.399	0.9917759	79	77	53	68.83	67.09
36	275:week_52_arm_1	107:week_0_arm_1	BFF	105	False	51	1.787	0.9630202	-0.2928	0.514	-1.401	0.9918315	82	77	54	70.13	65.85

Multiple Reference Cohorts

In Desktop, select multiple files under Reference cohorts. The same target is compared against all selected reference records.

CLI example: rank against multiple cohorts

The process mirrors handling a single cohort; the main difference is that each reference cohort gets a prefix in its primary_key, making it possible to trace the origin of every individual.

We reuse individuals.json to simulate more than one cohort.

Example:

pheno-ranker -r individuals.json individuals.json individuals.json -t patient.json --max-out 10 -o rank_multiple.txt

This will create the text file rank_multiple.txt.

See results from rank_multiple.txt

RANK	REFERENCE(ID)	TARGET(ID)	FORMAT	LENGTH	WEIGHTED	HAMMING-DISTANCE	DISTANCE-Z-SCORE	DISTANCE-P-VALUE	DISTANCE-Z-SCORE(RAND)	JACCARD-INDEX	JACCARD-Z-SCORE	JACCARD-P-VALUE	REFERENCE-VARS	TARGET-VARS	INTERSECT	INTERSECT-RATE(%)	COMPLETENESS(%)
1	C2_107:week_0_arm_1	107:week_0_arm_1	BFF	77	False	1	-2.306	0.0105624	-8.5470	0.987	2.804	0.0356370	77	77	76	98.70	98.70
2	C3_107:week_0_arm_1	107:week_0_arm_1	BFF	77	False	1	-2.306	0.0105624	-8.5470	0.987	2.804	0.0356370	77	77	76	98.70	98.70
3	C1_107:week_0_arm_1	107:week_0_arm_1	BFF	77	False	1	-2.306	0.0105624	-8.5470	0.987	2.804	0.0356370	77	77	76	98.70	98.70
4	C1_125:week_0_arm_1	107:week_0_arm_1	BFF	78	False	5	-1.969	0.0244763	-7.6995	0.936	2.340	0.0901212	75	77	73	94.81	97.33
5	C3_125:week_0_arm_1	107:week_0_arm_1	BFF	78	False	5	-1.969	0.0244763	-7.6995	0.936	2.340	0.0901212	75	77	73	94.81	97.33
6	C2_125:week_0_arm_1	107:week_0_arm_1	BFF	78	False	5	-1.969	0.0244763	-7.6995	0.936	2.340	0.0901212	75	77	73	94.81	97.33
7	C2_275:week_0_arm_1	107:week_0_arm_1	BFF	85	False	13	-1.296	0.0975704	-6.3994	0.847	1.534	0.2966472	81	77	72	93.51	88.89
8	C1_275:week_0_arm_1	107:week_0_arm_1	BFF	85	False	13	-1.296	0.0975704	-6.3994	0.847	1.534	0.2966472	81	77	72	93.51	88.89
9	C3_275:week_0_arm_1	107:week_0_arm_1	BFF	85	False	13	-1.296	0.0975704	-6.3994	0.847	1.534	0.2966472	81	77	72	93.51	88.89
10	C1_215:week_0_arm_1	107:week_0_arm_1	BFF	87	False	15	-1.127	0.1298396	-6.1110	0.828	1.357	0.3603912	83	77	72	93.51	86.75

Why the distance for 107:week_0_arm_1 is not 0 if the three cohorts are identical?

In Patient mode, the global vector is formed using variables solely from the reference cohort(s), not the patient's. The primary_key (id in this context) is automatically included, leading to a distance of 1 due to the mismatch in the individual's id field.

If you want to visualize the differences in all variables (i.e., the union of reference(s) and target), simply add the target as another cohort in --r. This way, the variables from the patient will be included in the reference vector.

Note that you can exclude id by adding --exclude-terms id.

Inspect a Pair

In Desktop, select a reference ID in the ranking to open the comparison grouped by entity. Each term shows its reference and target values, weight, and contribution to Hamming distance. Alignment output must be enabled for the run.

CLI alignment exports and example

Obtaining additional information on the alignments

You can create several files related to the reference-target alignment by adding --align. By default, this creates alignment* files in the current directory, but you can specify a </path/basename>. Example:

pheno-ranker -r individuals.json individuals.json -t patient.json --align

Or using a path + basename:

pheno-ranker -r individuals.json individuals.json -t patient.json --align /my/fav/dir/jobid-001-align

Find below an extract of the alignment (C1_107:week_0_arm_1 --- 107:week_0_arm_1) extracted from alignment.txt:

REF -- TAR
1 ----- 1 | (w:  1|d:  0|cd:  0|) diseases.NCIT:C3138.diseaseCode.id.NCIT:C3138 (Inflammatory Bowel Disease)
1 ----- 1 | (w:  1|d:  0|cd:  0|) ethnicity.id.NCIT:C41261 (Caucasian)
1 ----- 1 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C154329.exposureCode.id.NCIT:C154329 (Smoking)
1 ----- 1 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C154329.unit.id.NCIT:C65108 (Never Smoker)
0       0 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C154329.unit.id.NCIT:C67147 (Current Smoker)
0       0 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C154329.unit.id.NCIT:C67148 (Former Smoker)
1 ----- 1 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C2190.exposureCode.id.NCIT:C2190 (Alcohol)
0       0 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C2190.unit.id.NCIT:C126379 (Non-Drinker)
0       0 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C2190.unit.id.NCIT:C156821 (Alcohol Consumption More than 2 Drinks per Day for Men and More than 1 Drink per Day for Women)
1 ----- 1 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C2190.unit.id.NCIT:C17998 (Unknown)
0       0 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C73993.exposureCode.id.NCIT:C73993 (Pack Year)
0       0 | (w:  1|d:  0|cd:  0|) exposures.NCIT:C73993.unit.id.NCIT:C73993 (Pack Year)
1 xxx-- 0 | (w:  1|d:  1|cd:  1|) id.C1_107:week_0_arm_1 (id.C1_107:week_0_arm_1)
0       0 | (w:  1|d:  0|cd:  1|) id.C1_107:week_14_arm_1 (id.C1_107:week_14_arm_1)
0       0 | (w:  1|d:  0|cd:  1|) id.C1_107:week_2_arm_1 (id.C1_107:week_2_arm_1)
0       0 | (w:  1|d:  0|cd:  1|) id.C1_125:week_0_arm_1 (id.C1_125:week_0_arm_1)
0       0 | (w:  1|d:  0|cd:  1|) id.C1_125:week_14_arm_1 (id.C1_125:week_14_arm_1)
...