NAV
Python bash

Quickstart

Intro and starting a study

import seeq

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

# Register if you don't have a Seeq 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 SEEQ_HOST=$(seeq host)

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

# Create study
$ seeq 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 Seeq Research!

Seeq 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 Seeq as a platform for your genomic studies by giving each user a special link. This link directs the user to the Seeq app, where we confirm that they are willing to link their Seeq account with your study and provide their genomic data. For individuals who are not already Seeq 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:

  1. Saliva collection kit
  2. Shipping to and from the user
  3. Sample processing
  4. Sequencing
  5. Ancestry and microbiome analysis for the user (returned to their phone)
  6. 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 Seeq (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 link
user_url = seeq.util.jwt_signed(
    study['id'], 
    'UniqueIdentifierForUser1', 
    study['api_key_production'], 
    subsidy_in_cents=5000)
# Create link
$ seeq 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 Seeq can be generated using these data with a simple helper function. This link will direct the user to the Seeq 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 seeq. 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:

  1. refresh_token, which is granted to the user upon successful authentication and used for accessing all REST API endpoints.
  2. 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 Seeq Research with code for an example study website.

Easy installation

pip install seeq
pip install seeq

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

Login

c = seeq.client.Client(None)

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

# Use object 'c' for interacting with Seeq backend...
# CLI tool will automatically look in $SEEQ_HOST 
# for host, to avoid setting --host every time
$ export SEEQ_HOST=$(seeq host)

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

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

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

Log in if you already have a Seeq account (no need to log in if you just registered).

Using multiple clients and tokens

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

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

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

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

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

# Use object 'c2' for interacting with Seeq backend...
# CLI tool will automatically look in $SEEQ_HOST 
# for host, to avoid setting --host every time
$ export SEEQ_HOST=$(seeq host)

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

$ export DEVICE_UUID="device2"
# Log into backend and perform actions
# from device2...
$ seeq 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 = seeq.client.Client(None)

c.set_refresh_token('<INSERT_YOUR_TOKEN_HERE>')

# Use object 'c' for interacting with Seeq backend...
# CLI tool will automatically look in $SEEQ_TOKEN 
# for token, to avoid setting --token every time
$ export SEEQ_TOKEN="<INSERT_YOUR_TOKEN_HERE>"

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

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

Logout

c.logout()
$ seeq 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
$ seeq study get_all

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

# Grab a specific field from the study
# e.g., study api key
$ export STUDY_KEY=$(seeq 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'])
seeq 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)
seeq study participant get_raw_data $STUDY_ID <participant-id-1> ...

Grab a list of metadata items describing each participant:

  1. study_id: study ID
  2. participant_id: seeq ID for participant
  3. external_id: external ID provided in unique link for each user
  4. url_s3: a presigned download link valid for 48h.

Change password

c.password_change()
$ seeq auth password_change

Easily change your password

Reset forgotten password

c.password_forgot_init("my@email.tld")
$ seeq 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
$ seeq --help
$ seeq auth --help
# ...
  1. Python API reference
  2. 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/seeqlabs/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

Support

Contact us at support@seeq.io