Quickstart

Intro and starting a study

import gencove

# Use default API URL: https://rest.gencove.com
c = gencove.client.Client(None)

# Register if you don't have a Gencove account
# After registration, you will receive an email to 
# confirm your email address
c.register('My Name', 'my@email.tld', 'my_password')

# Create study
study = c.study_create(
    'Study Name', 
    'https://study.link.tld', 
    'Description of study')

# Use the default host
$ export GENCOVE_HOST=$(gencove host)

# Register if you don't have a Gencove account
# After registration, you will receive an email to
# confirm your email address
$ export GENCOVE_TOKEN=$(gencove auth register\
    "My Name"\
    "my@email.tld"\
    --password "my_password")

# Create study
$ gencove study create\
    "Study Name"\
    https://study.link.tld\
    "Description of study"

Omitting the password parameter will result in prompting the user for a password

Welcome to Gencove Research!

Gencove aims to give users easy access to their genome. They can download the app, order our inexpensive saliva kit, and drop it off in any USPS mailbox - that’s all it takes. Users get ancestry and microbiome information delivered to their smartphone, ready to share with friends and family.

As a researcher, you can use Gencove as a platform for your genomic studies by giving each user a special link. This link directs the user to the Gencove app, where we confirm that they are willing to link their Gencove account with your study and provide their genomic data. For individuals who are not already Gencove users, you can also optionally choose to fully or partially subsidize their sequencing.

Once the user provides their sample and we process it, you will have access to the user’s low coverage sequencing .bam file. At scale, this data is much more powerful than SNP genotyping arrays for assaying common variation and additionally provides insight into rare variants (check out Pasanuic et. al. and Nicod et. al.).

Compared to microarrays, it’s also a fraction of the cost: we currently charge $50 per user, which includes:

Saliva collection kit
Shipping to and from the user
Sample processing
Sequencing
Ancestry and microbiome analysis for the user (returned to their phone)
Raw data delivery in .bam format.

This means you can start a large-scale genomic study without the hassle of sample collection, processing, and operating a wet lab. All you need to do is sign up as a researcher with Gencove (depending on your institutional requirements and your plans, you may also need IRB approval for your study).

Try out the examples on the side and read on to see how you can use our API to set up a research project and start recruiting users to your genomic studies in no time.

Create unique links for users

# Create link
user_url = gencove.util.jwt_signed(
    study['id'], 
    'UniqueIdentifierForUser1', 
    study['api_key_production'], 
    subsidy_in_cents=5000)

# Create link
$ gencove jwt\
    <study-id>\
    UniqueIdentifierForUser1\
    <study-api-key>\
    --subsidy-in-cents 5000

Creating a study generates a study id and study api key. Unique links for sending users to Gencove can be generated using these data with a simple helper function. This link will direct the user to the Gencove app, display basic study information, and prompt for their approval. Once approved, you will have access to their raw data.

In case they don’t have the app installed, users will be taken to a responsive web page to join the study.

You must attribute a unique identifier for each user in order to be able to dereference the raw data once it is available.

You may also provide a discount for kits to users (i.e., “subsidize a kit”) in case they have not already provided a saliva sample through Gencove. The code examples define a kit subsidy of $50, i.e., provide a free kit to users in the USA.

Check below for more details on getting information about existing studies.

Keys and tokens

This API has 2 main keys/tokens:

refresh_token, which is granted to the user upon successful authentication and used for accessing all REST API endpoints.
api_key_production, which is associated with a particular research study and used to generate unique links for granting users access to that study. It is also unfortunately named.

An example study

Have a look at our blog post for an introduction to Gencove Research with code for an example study website.

Easy installation

pip install gencove

pip install gencove

All you need is Python 2.7+ or Python 3.3+, with pip installed.

Python (and pip) installation instructions.

We also highly recommend using virtualenv for Python.

More API operations

c = gencove.client.Client(None)

c.login('my@email.tld', 'my_password')

# Use object 'c' for interacting with Gencove backend...

# CLI tool will automatically look in $GENCOVE_HOST 
# for host, to avoid setting --host every time
$ export GENCOVE_HOST=$(gencove host)

$ export GENCOVE_TOKEN=$(gencove auth login\
    "my@email.tld"\
    --password "my_password")

# Run more commands for interacting with Gencove backend...

Omitting the password parameter will result in prompting the user for a password

Using multiple clients and tokens

c1 = gencove.client.Client(None, device_uuid='device1')

c1.login('my@email.tld', 'my_password')

# Use object 'c1' for interacting with Gencove backend...

c2 = gencove.client.Client(None, device_uuid='device2')

c2.login('my@email.tld', 'my_password')

# Use object 'c2' for interacting with Gencove backend...

# CLI tool will automatically look in $GENCOVE_HOST 
# for host, to avoid setting --host every time
$ export GENCOVE_HOST=$(gencove host)

$ export DEVICE_UUID="device1"
# Log into backend and perform actions
# from device1...
$ gencove auth login\
    "my@email.tld"\
    --password "my_password"\

$ export DEVICE_UUID="device2"
# Log into backend and perform actions
# from device2...
$ gencove auth login\
    "my@email.tld"\
    --password "my_password"\

Omitting the password parameter will result in prompting the user for a password

It is easy to create multiple tokens for using several clients. For example, one client may be used by an administrative user, while another may be used by automated scripts.

Use existing token for authentication

c = gencove.client.Client(None)

c.set_refresh_token('<INSERT_YOUR_TOKEN_HERE>')

# Use object 'c' for interacting with Gencove backend...

# CLI tool will automatically look in $GENCOVE_TOKEN 
# for token, to avoid setting --token every time
$ export GENCOVE_TOKEN="<INSERT_YOUR_TOKEN_HERE>"

# Run more commands for interacting with Gencove backend...

If you have already logged in or registered, you may use that same token for authentication purposes

Logout

c.logout()

$ gencove auth logout

You can easily logout and invalidate the current token.

Get study information

# Get all my studies
studies = c.studies_get()

# Get a specific study
study = c.study_get(my_study_id)

# Get all studies
$ gencove study get_all

# Get a specific study
$ export STUDY_ID=<my-study-id>
$ gencove study get $STUDY_ID

# Grab a specific field from the study
# e.g., study api key
$ export STUDY_KEY=$(gencove study get\
    $STUDY_ID\
    --key api_key_production)

You can grab information about all your studies or one specific study

Get study participants

participants = c.study_participants_get(study['id'])

gencove study participant get_all $STUDY_ID

Grab a list of all participant ID’s taking part in your study

Get raw data

raw_data = c.study_raw_data_get(
    study['id'], list_of_participant_ids)

gencove study participant get_raw_data $STUDY_ID <participant-id-1> ...

Grab a list of metadata items describing each participant:

study_id: study ID
participant_id: gencove ID for participant
external_id: external ID provided in unique link for each user
url_s3: a presigned download link valid for 48h.

Change password

c.password_change()

$ gencove auth password_change

Easily change your password

Reset forgotten password

c.password_forgot_init("my@email.tld")

$ gencove auth password_forgot_init my@email.tld

Easily reset a forgotten password by sending an emaill to the address associated with the account

API Reference

We currently provide a Python API and a command line tool.

# check out link to the Python API reference in the text

$ gencove --help
$ gencove auth --help
# ...

Python API reference
The command-line tool has nicely formatted help pages

Source code

The git repository for the Python API and CLI can be found here:

https://gitlab.com/gencove/api-python

Terms

We reserve the right to remove your access to our API for any reason at our sole discretion. We will provide a more detailed description of our expectations in due course. However, overall we expect that 1) you will not mislead users into disclosing their data under false pretenses and 2) you will have a clear policy on how users can opt out of your use of their data should they change their minds about sharing it with you.

FAQ

User FAQ

Quickstart

Intro and starting a study

Create unique links for users

Keys and tokens

An example study

Easy installation

More API operations

Login

Using multiple clients and tokens

Use existing token for authentication

Logout

Get study information

Get study participants

Get raw data

Change password

Reset forgotten password

API Reference

Source code

Terms

FAQ

Support