Connectors

Overview

While many phenotype definitions combine the logic to extract one or more patients from a data source with the actual logic of the definition itself (e.g. an SQL statement that directly extracts patients based upon clinical codes), Phenoflow definitions purposefully separate these processes in order to allow definition logic to be executed against multiple data sources. The modular nature of workflows provides the ability to do this.

Execute an existing phenotype definition against a new dataset

Several existing connectors are available within Phenoflow for common standards (OMOP, FHIR, i2b2 and local CSV read), but it is also possible to author a new connector, for those standards used within an organisation:

1. Obtains credentials for the main Phenoflow library, or run a copy of the library locally.
2. If you are wishing to add a new connector to one or more existing phenotypes (e.g. to execute existing logic against a new data source), then first import those definitions.
3. Author a connector template with the required structure.
   1. Phenoflow connectors are single files written in a supported programming language (Javascript, Python or KNIME), which gather a set of all patient records from a data source and output them as a CSV file with a specific structure. Note that no processing of the data takes place within a connector.
   2. The structure of the output CSV file should be as follows:
      1. patient-id - Integer (e.g. 1) - A unique identifier for each patient
      2. dob - YYYY-MM-DD (e.g 1979-01-01) - The patient's DOB. Null if unknown.
      3. codes - ([Code],YYYY-MM-DD),* (e.g. "(X01,2020-01-01),(X02,2020-01-01)") - A comma-separated list of codes, matched to a relevant date (e.g. date of diagnosis)
      4. last-encounter - YYYY-MM-DD (e.g 1979-01-01) - Date of the last encounter with the patient. Null if unknown.
   3. Phenoflow connectors are treated as templates, which means that some of their contents will be substituted at runtime, typically depending on the definition for which they are being used. Template variables are indicated by square brackets.
      1. The name of the patient CSV file output by a connector should contain a variable, PHENOTYPE: [PHENOTYPE]-potential-cases.csv. An example of this can be found in the example template connectors, available here.
4. Issue an HTTP post request against the addConnector endpoint within the target Phenoflow instance (live or local), supplying the implementation template itself along with the other required details.
5. Visit the pages of those definitions to which the new connector has been applied to confirm the creation of the new connector. It should be listed as a 'switch to' option, underneath the first step in the definition.