Genotype object

Genotype is a JSON object that links genetic data to a Sample object. Main property of Genotype data object is a path to genotype data file that is stored in Platform's secured genotype storage (genotype::source_uri):

curl --request GET \
  --url "https://se1.lifenome.com/platform-api/api/samples-api/samples/${SAMPLE_ID}/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

{
    "id": "312235f8-...-c8b71648471d",
    "created_at": "2022-11-17T15:49:54.911283Z",
    "genotype": {
      "assembly": "grch37",
      "source_uri": "gs://platform--staging/samples/312235f8-...-c8b71648471d/genotype/{GENOTYPE_FILENAME}",
      "state": "processed",
      "created_at": "2022-11-21T19:37:18.653792Z"
    }
}

Second important property is the genotype processing state (genotype::state) which keeps current state of the file processing pipeline.

State transitions are illustrated by following figure:

If uploaded genotype file does not contain valid genotype data, then state transition diagram might look like:

Importing genotype data

• File upload
  • upload using file upload API endpoint
  • direct upload into GCS bucket (only for tenants that are configured to use private bucket)
• DNA Kit
  • linking registerd DNAKit to sample

Genotype lifecycle (state diagram)

2. Upload genotype file to temporarily signed URL

Once a signed upload URL for the corresponding sample (SAMPLE_ID) and genotype file (GENOTYPE_FILENAME) is obtained, file uploading can be started directly to UPLOAD_URL with:

curl --request PUT \
  --url ${UPLOAD_URL} \
  --data-binary @${PATH_TO_GENOTYPE_FILE}/${GENOTYPE_FILENAME}

Please note that complete path must be given when uploading the file, while only file name is needed to get signed URL.

When uploading is completed, genotype file is added to the Sample which can be confirmed by reading sample details again:

{
  "id": "312235f8-...-c8b71648471d",
  "created_at": "2022-11-17T15:49:54.911283Z",
  "genotype": {
    "assembly": "grch37",
    "source_uri": "gs://platform--staging/samples/312235f8-...-c8b71648471d/genotype/{GENOTYPE_FILENAME}",
    "state": "data-valid",
    "created_at": "2022-11-21T19:37:18.653792Z"
  }
}

Until file is not completely uploaded, state is not-available. Once file upload completes, state transitions to available.

Next, genotype data stored in the file is automatically validated. If a valid genotype file is uploaded, the state of genotype transitions to data-valid:

Finally, when uploaded file is completely processed, state will be processed:

As mentioned before, if provided genotype file is not recognized, state will be data-invalid. See :doc:/basics/supported-genetic-files for more information about what kind of files with genotype data are supported.

Import genotype data from 3rd party genotype data providers

This section describes how to import genotype from 3rd party providers. Currently, only GxG is supported.

GxG

GxG Import is a process of importing data from GxG API (docs <https://demo-api.genebygene.com/swagger/index.html?urls.primaryName=V2>_). This operation can be a long running process which can take up to few weeks between sending sample to GxG lab and obtaining genotype data. In order to support long running operation and various problems that can occur during operation's lifetype, import operation is modeled by ImportTask resource. Client can create ImportTask for given Sample, check status of the ImportTask, delete and restart failed ImportTask etc.

ImportTask resource is managed using Genotype Gxg Import Endpoint <https://se1.lifenome.com/platform-api/api/schema/redoc/#tag/samples-api.genotype.gxgimport>_

Create GxgImport Task

curl --request PUT \
  --url "https://se1.lifenome.com/platform-api/api/samples-api/samples/${SAMPLE_ID}/genotype/tasks/gxg-import/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data "{\"gender\": \"male\", \"gxg_kit_number\": \"string\"}"

Response:

{
  "id": "497f6eca-...-53cbbbba6f08",
  "gender": "male",
  "gxg_kit_number": "string",
  "status": "string"
}

Client can store Task ID (id) and use it to track status of the Task by executing:

curl --request GET
  --url "https://se1.lifenome.com/platform-api/api/samples-api/samples/${SAMPLE_ID}/genotype/tasks/gxg-import/${TASK_ID}/" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${ACCESS_TOKEN}'

If the Task state is success then genotype data have been successfuly transfered from GxG API to GenotypeStorage. After that processing of genotype data proceeds in the same way as processing of uploaded genotype file.

Providing file via Google Cloud storage URI

Currently not available.