Getting started notebooks

[larrybabb]

I recommend we create a set of "getting started" notebooks that would allow a developer explore the main features of vrs-python. These are the first set that we can build on. I encourage other's to recommend changes and additional "quick" topics.

• Quick start
• Models
• References & Object Store
• Exploring the Allele Translator
• Exploring the CNV Translator

NOTE: We are thinking of creating an easy.py file to simplify the imports for the vrs-python package similar to how this was done in biocommons/hgvs (see here).

[larrybabb]

Notebook 1 : Quick start

What is the fastest way to have a working environment to play with VRS-Python tools

1. setup data proxy access

from ga4gh.vrs.dataproxy import SeqRepoRESTDataProxy

seqrepo_rest_service_url = "https://services.genomicmedlab.org/seqrepo"
dp = SeqRepoRESTDataProxy(base_url=seqrepo_rest_service_url)

(link to DataProxy.ipynb for further details, e.g. how to set up a local DataProxy (not REST))
To view in browser: https://services.genomicmedlab.org/seqrepo/1/ui/#

2. Setup allele translator

from ga4gh.vrs.extras.translator import AlleleTranslator
tlr = AlleleTranslator(data_proxy=dp, identify=True)

(talk about CnvTranslator in a separate notebook?)

3. Pass an HGVS/etc expression to the translator and get the result

[toneillbroad]

I've reviewed the notebooks and the installation docs in vrs-python/docs/setup-help and feel they are just too complicated for a getting started set of notebooks. I'd like to propose that we use the publicly available data sources for:

• seqrepo (SEQREPO_DATAPROXY_URL"https://services.genomicmedlab.org/seqrepo")

• uta (UTA_DB_URL="postgresql://anonymous:anonymous@uta.biocommons.org:5432/uta/uta_20210129b")

• Other than being a bit out of date, are there implications of using this combination that I am unaware of?

I very much like the idea of a separate DataProxy.ipynb that explores it's distinct functionality (see some examples in "Docs and Validation.ipynb" under "External Data"):

• get_sequence
• get_metadata
• translate_sequence_identifier
• others?

It may also be worthwhile including an example of VariationNormalizerRestDataProxy in here as well (perhaps borrowed in part from "HGVS Translation.ipynb" under VR -> HGVS section).

• Does this make it too complicated?

Otherwise I like keeping items 1 and 2 above with a simple AlleleTranslator example.

[korikuzma]

@toneillbroad We currently use the hosted seqrepo instance you provided in the notebooks. I would like to add a note that says something about please only using these instances for exploratory / introductory purposes to keep traffic low and costs down. But that is just my opinion

[larrybabb]

Notebook 2. A basic Models example

Goal: show how to create VRS objects using individual parameters, not a nomenclature string (HGVS/SPDI/Gnomad-VCF)

Demo the same Allele as the quick start notebook, but not using translator, going to Model classes directly, and calling normalize() and identify() on it.

1. setup access to the VRS models package

from ga4gh.vrs import models

2. build the Allele

SequenceReference
SequenceLocation
Allele

3. run normalization on it

from ga4gh.vrs import normalize
normalized_allele = normalize(allele)

4. compute the identifier

from ga4gh.core import ga4gh_identify
ga4gh_identify(allele)

[toneillbroad]

I agree with the above. Perhaps we use a single Allele example but run each of the following operations on it similar to "Operations.ipynb". The exception being no inter-dependency on the "Schema.ipynb" notebook:

• normalize
• ga4gh_identify
• ga4gh_serialize
• ga4gh_digest
• probably not sha512t24u?

[larrybabb]

Notebook 3: References & Object Store

1. Setting up a basic object store

2. Take the identified Allele from quickstart, run enref on it (recursively?) to collapse identifiable objects.

3. Store the identifiable objects in the object store

4. Round trip this by taking the collapsed object and dereferencing the referenced objects from the object store and giving back the original fully specified allele

[larrybabb]

Notebook 4: Exploring the Allele Translator

There are 4 translators available; SPDI, gnomAD/VCF, Beacon and HGVS. In this notebook we will perform a simple Allele translation with each of these
We will use each of the four nomenclatures for the same variant to demonstrate that the vrs output is consistent.

1. setup dataproxy and allele translator

2. pass in hgvs/gnomadvcf/beacon/spdi for the same quickstart Allele, get back VRS Allele.

[toneillbroad]

Updated AlleleTranslator examples in the vein of "Extras.ipynb":

• from/to SPDI
• from/to HGVS
• from gnomAD
• from Beacon

Simple examples. Advanced examples could be a linked notebook in the future.

[larrybabb]

Notebook 5: Exploring the CNV Translator

this is only for HGVS

[toneillbroad]

Simple examples of CopyNumberCount and CopyNumberChange.