Proposal: Implementing Pheno-Ranker in a Federated Network

This proposal considers two deployment contexts for Pheno-Ranker: an inter-hospital network and a Beacon v2 network.

Federated network diagram

Image created by GPT-5.5

Use Case A: Inter-Hospital Network

The current version of Pheno-Ranker is designed for file-based operations and initiates calculations from scratch each time. To adapt the algorithm for use in multiple hospitals without directly sharing clinical data, we propose the following approach:

1. Preparation Stage:

Vector Standardization: Ensure all hospitals use a standardized vector format.

• Store each patient’s vector in a local-database.
  • “id_1": "1101010101010...n",
  • "id_2": "0101010101000...n
• Utilize a network aggregator to regularly update a global reference vector. Each update gets a new version identifier.
• Periodically update the vector database at each site to ensure current data.

Privacy Protocols: Set up differential privacy mechanisms or encryption protocols.

Threshold Agreement: Establish a common threshold for the Hamming distance (or other metric) for matches.

Preparation stage of Pheno-Ranker algorithm in an inter-hospital network

2. Query Initiation:

The querying hospital prepares a vector representation of the individual or set of individuals. The vector is processed using the agreed-upon privacy protocols.

3. Aggregator Mediation:

The querying hospital sends the processed vector to the network aggregator. The network aggregator distributes the query to all hospitals in the federated network.

4. Local Computation:

Each receiving hospital computes the Hamming distance against its local patient vectors. The computation is done entirely within the local environment of each hospital.

5. Thresholding:

Each hospital applies the agreed-upon thresholding to identify vectors that are considered a "match."

6. Response to Aggregator:

Each hospital sends its response (list of matching vectors, counts, etc.) back to the network aggregator.

7. Aggregation:

The network aggregator collects all the responses, processes them, and sends the aggregated result to the querying hospital.

8. Post-Processing:

The querying hospital undertakes further analysis, potentially reaching out to specific hospitals for more information based on the aggregated results, and decides on subsequent actions.

Pheno-Ranker algorithm in a federated network

Use Case B: Beacon v2 Network

Currently, the /individuals endpoint from the Beacon v2 API can be queried, and, as long as the user has appropriate access to the record-level data, the response can be parsed and saved as a text file (i.e., BFF). Pheno-Ranker can then be executed locally through the command-line interface (CLI), Perl module, or legacy Web App UI, which will be supported until the end of 2026. While this approach works, it becomes cumbersome when the goal is to search for similar patients across multiple Beacon instances.

Two POST query designs could support Pheno-Ranker within a Beacon v2 network:

1. The first method uses a precomputed vector, as in the inter-hospital model. A Beacon aggregator would periodically collect ontology terms from the filtering_terms endpoint of each Beacon v2 API to create a shared lookup table.

2. Alternatively, centers may submit BFF or PXF objects that meet the network's privacy and security requirements. The recipient site can compare them with precomputed data or run Pheno-Ranker on demand.

The response schema could follow the Beacon v2 specification or extend it with similarity metrics.

Draft Proposal for the JSON Schema of the phenoRanker Query Parameter

Note: In YAML format; subject to future modifications to align with Beacon v2 specifications.

$schema: "https://json-schema.org/draft/2020-12/schema"
type: object
properties:
  meta:
    type: object
    properties:
      apiVersion:
        type: string
        description: "The version of the Beacon API being used."
        enum: ["2.0", "2.1"]
    required:
      - apiVersion
  query:
    type: object
    properties:
      requestParameters:
        type: object
        properties:
          phenoRanker:
            type: array
            description: "An array of phenoRanker objects, all of the same type ('vector', 'bff', or 'pxf')."
            items:
              type: object
              properties:
                info:
                  type: string
                  description: "Optional additional information about the phenoRanker object."
              oneOf:
                - properties:
                    vector:
                      type: string
                      pattern: "^[01]+$"
                      description: "A binary string representing a vector."
                      example: "1010101"
                    version:
                      type: string
                      description: "Version of the vector data."
                      example: "1.0.0"
                  required:
                    - vector
                    - version
                - properties:
                    bff:
                      type: object
                      description: "An object representing BFF data."
                    version:
                      type: string
                      description: "Version of the BFF data."
                      example: "2.0"
                      enum: ["2.0"]
                  required:
                    - bff
                    - version
                - properties:
                    pxf:
                      type: object
                      description: "An object representing PXF data."
                    version:
                      type: string
                      description: "Version of the PXF data."
                      example: "2.0"
                      enum: ["2.0"]
                  required:
                    - pxf
                    - version
              description: "Each item must contain exactly one of 'vector', 'bff', or 'pxf'."
            minItems: 1
            additionalItems: false
          # Include other requestParameters as needed
        required:
          - phenoRanker
      # Include 'filters' or 'pagination' if necessary
    required:
      - requestParameters
required:
  - meta
  - query
description: "Schema for a Beacon v2 API query incorporating phenoRanker data."

Example Queries:

• Example with vector items

{
  "meta": {
    "apiVersion": "2.0"
  },
  "query": {
    "requestParameters": {
      "phenoRanker": [
        {
          "vector": "1010101",
          "version": "1.0.0",
          "info": "Sample vector data"
        },
        {
          "vector": "1110001",
          "version": "1.0.0",
          "info": "Another vector data"
        }
      ]
    }
  }
}

• Example with bff items

{
  "meta": {
    "apiVersion": "2.0"
  },
  "query": {
    "requestParameters": {
      "phenoRanker": [
        {
          "bff": { "someKey": "someValue1" },
          "version": "2.0"
        },
        {
          "bff": { "someKey": "someValue2" },
          "version": "2.0"
        }
      ]
    }
  }
}