Skip to main content

Getting Started with Python SDK

The preferred method for getting started with your data in the Python SDK is to use the notebooks environment. For information on the notebooks environment, see Getting Started with Notebooks in the LifeOmic Platform or Notebooks Overview.

The Python SDK is divided into two primary sections. The phc.easy modules allow a high-level interaction with our APIs geared towards the researcher or data scientist while the other modules like phc.services give lower level access to the APIs if more configuration is needed. Unless you're building an integration, the preferred method is the "easy" method.

# "Easy" method
import phc.easy as phc

# Direct API access
from phc.services import Files, Cohorts, ...

Authentication​

If the SDK is being used in the Notebooks environment, the SDK authentication is already handled. In this case, go ahead and skip to the Selecting a Project section.

For authentication, simply provide an account and token to the SDK.

  • Account - This parameter is the ID of your LifeOmic Platform account.
  • Token - This parameter is a generated API key for your user. To generate a token, see the API Keys guide.
import phc.easy as phc

phc.Auth.set({
    # Specify account name (or use the sandbox)
    "account": "sandbox",

    # Specify generated API token
    "token": "<insert-token-here>",

    # (Optional) Select project if known (e.g. BRCA Research)
    # "project_id": "34c0fb25-bbde-4eb1-87ed-dd4c7a1ac013"
})

Selecting a Project​

Nearly everything in the SDK occurs in the context of a project. Projects can be easily selected by searching for part of its name in any of your accounts.

import phc.easy as phc

# Search for project by name and set for all subsequent calls
phc.Project.set_current("BRCA Research")

If multiple projects match, a list of matching projects will be printed, and the specific identifier can be selected with this call.

phc.Auth.set({
    "project_id": "34c0fb25-bbde-4eb1-87ed-dd4c7a1ac013"
})

Fetching a Patient Resource​

The Python SDK aims to make fetching FHIR resources as easy as possible. For example, fetching patients is a single call that returns a sample of results.

phc.Patient.get_data_frame()
# => Retrieved 10/1098 results
# => <Pandas DataFrame>

This get_data_frame() call returns a pandas data frame that converts the nested FHIR data structure into a flat table of columns. Here's an example row from the Patient table.

{
  "id": "0045349c-69d9-4306-a403-c9c1fa836644",
  "name_given_0": "A1A0SB",
  "name_family": "LO",
  "extension.url
    __hl7.org/fhir/StructureDefinition/us-core-race
    __valueCodeableConcept_text": "race",
  "extension.url
    __hl7.org/fhir/StructureDefinition/us-core-race
    __valueCodeableConcept_coding_system
    __hl7.org/fhir/v3/Race
    __code": "2106-3",
  "extension.url
    __hl7.org/fhir/StructureDefinition/us-core-race
    __valueCodeableConcept_coding_system
    __hl7.org/fhir/v3/Race
    __display": "white",
  "extension.url
    __hl7.org/fhir/StructureDefinition/us-core-ethnicity
    __valueCodeableConcept_text": "ethnicity",
  "extension.url
    __hl7.org/fhir/StructureDefinition/us-core-ethnicity
    __valueCodeableConcept_coding_system
    __hl7.org/fhir/v3/Ethnicity
    __code": "2186-5",
  "extension.url
    __hl7.org/fhir/StructureDefinition/us-core-ethnicity
    __valueCodeableConcept_coding_system
    __hl7.org/fhir/v3/Ethnicity
    __display": "not hispanic or latino",
  "resourceType": "Patient",
  "gender": "female",
  "birthDate.tz": 0.0,
  "birthDate.local": "1937-04-10T00:00:00",
  "deceasedBoolean": false,
  "identifier.type_coding_system
    __hl7.org/fhir/v2/0203__code": "ANON",
  "identifier.type_coding_system
    __hl7.org/fhir/v2/0203__value": "LO-A1-A0SB",
  "meta.tag_system
    __lifeomic.com/fhir/dataset
    __code": "34c0fb25-bbde-4eb1-87ed-dd4c7a1ac013",
  "meta.tag_lastUpdated.tz": 0.0,
  "meta.tag_lastUpdated.local": "2020-06-18T17:30:56.660000",
  "address_country": "united states",
  "address_use": "home",
  "address_type": "physical"
}

This row was converted from the raw FHIR structure as seen below.

{
  "id": "0045349c-69d9-4306-a403-c9c1fa836644",
  "name": [{ "text": "A1A0SB LO", "given": ["A1A0SB"], "family": "LO" }],
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/us-core-race",
      "valueCodeableConcept": {
        "text": "race",
        "coding": [
          {
            "code": "2106-3",
            "system": "http://hl7.org/fhir/v3/Race",
            "display": "white"
          }
        ]
      }
    },
    {
      "url": "http://hl7.org/fhir/StructureDefinition/us-core-ethnicity",
      "valueCodeableConcept": {
        "text": "ethnicity",
        "coding": [
          {
            "code": "2186-5",
            "system": "http://hl7.org/fhir/v3/Ethnicity",
            "display": "not hispanic or latino"
          }
        ]
      }
    }
  ],
  "resourceType": "Patient",
  "gender": "female",
  "birthDate": "1937-04-10",
  "deceasedBoolean": false,
  "identifier": [
    {
      "type": {
        "coding": [{ "code": "ANON", "system": "http://hl7.org/fhir/v2/0203" }]
      },
      "value": "LO-A1-A0SB"
    }
  ],
  "meta": {
    "tag": [
      {
        "system": "http://lifeomic.com/fhir/dataset",
        "code": "34c0fb25-bbde-4eb1-87ed-dd4c7a1ac013"
      }
    ],
    "lastUpdated": "2020-06-18T17:30:56.660Z"
  },
  "address": [
    {
      "country": "united states",
      "use": "home",
      "type": "physical",
      "text": "united states"
    }
  ]
}

Fetching Other Resources​

Similar to patients, fetching other resources such as conditions is just as easy.

phc.Condition.get_data_frame()
# => Retrieved 10/1178 results
# => <Pandas DataFrame>

To find an available resource within a Jupyter environment, simply type phc. and press Shift-Tab to see the available autocomplete suggestions. Use the title case classes instead of the lower case module names. For example, use phc.MedicationAdministration and not phc.medication_administration.

There are many options that can be passed to these methods. Although most resources handle the same parameters for filtering, scrolling through results, and exanding the data structures, check the specific class documentation in the SDK docs for more information.

Here is a list of some of the resources currently available in the SDK: