API reference¶

manwe¶

Manwë, a Python client library and command line interface to the Varda database for genomic variation frequencies.

class manwe.Session(api_root=None, token=None, config=None, log_level=20)[source]¶

Bases: manwe.session.AbstractSession

Session for interfacing the server API.

Example session:

>>> session = Session()
>>> sample = session.create_sample('Test')
>>> sample.uri
'/samples/1'
>>> sample.dirty
False
>>> sample.name = 'Test sample'
>>> sample.dirty
True
>>> sample.save()
>>> sample.dirty
False

annotation(uri)¶

Get a resource of type annotation.

Parameters:	uri (str) – URI for the annotation to retrieve.
Returns:	A resource of type annotation.
Return type:	`Annotation`

annotations(*args, **kwargs)¶

Query an annotation resource collection.

Returns:	An annotation resource collection.
Return type:	`AnnotationCollection`

coverage(uri)¶

Get a resource of type coverage.

Parameters:	uri (str) – URI for the coverage to retrieve.
Returns:	A resource of type coverage.
Return type:	`Coverage`

coverages(*args, **kwargs)¶

Query a coverage resource collection.

Parameters:	sample (`Sample`) – Filter collection by sample.
Returns:	A coverage resource collection.
Return type:	`CoverageCollection`

create_annotation(*args, **kwargs)¶

Create an annotation resource.

Parameters:	data_source (`DataSource`) – Data source to annotate. name (str) – Human readable annotation name. queries (dict(str, str)) – Sample queries to calculate variant frequencies over. Keys are query identifiers (alphanumeric) and values are query expressions.
Returns:	An annotation resource.
Return type:	`Annotation`

create_coverage(*args, **kwargs)¶

Create a coverage resource.

Parameters:	sample (`Sample`) – Sample the coverage resource is part of. data_source (`DataSource`) – Data source for the coverage resource.
Returns:	A coverage resource.
Return type:	`Coverage`

create_data_source(*args, **kwargs)¶

Create a data source resource.

Parameters:	name (str) – Human readable data source name. filetype (str) – Data filetype. Possible values are `bed`, `vcf`, and `csv`. gzipped (bool) – Whether or not the data is compressed using gzip. data (file-like object) – Data blob. local_file (str) – A filename on the server filesystem. This can be used instead of data.
Returns:	A data source resource.
Return type:	`DataSource`

create_group(*args, **kwargs)¶

Create a group resource.

Parameters:	name (str) – Human readable group name.
Returns:	A group resource.
Return type:	`Group`

create_sample(*args, **kwargs)¶

Create a sample resource.

Parameters:	name (str) – Human readable sample name. pool_size (int) – Number of individuals in the sample. coverage_profile (bool) – Whether or not the sample has a coverage profile. public (bool) – Whether or not this sample is public. notes (str) – Human readable notes in Markdown format. groups (iterable(`DataSource`)) – Groups this sample is part of.
Returns:	A sample resource.
Return type:	`Sample`

create_user(*args, **kwargs)¶

Create a user resource.

Parameters:	login (str) – Login name used for authentication. password (str) – Password used for authentication. name (str) – Human readable user name. email (str) – User e-mail address. roles (iterable(str)) – Roles for this user (values must be from `USER_ROLES`).
Returns:	A user resource.
Return type:	`User`

create_variant(*args, **kwargs)¶

Create a variant resource.

Parameters:	chromosome (str) – Chromosome name. position (int) – Position of variant on chromosome. reference (str) – Reference allele. observed (str) – Observed allele.
Returns:	A variant resource.
Return type:	`Variant`

create_variation(*args, **kwargs)¶

Create a variation resource.

Parameters:	sample (`Sample`) – Sample the variation resource is part of. data_source (`DataSource`) – Data source for the variation resource. skip_filtered (bool) – Discard entries in data_source marked as filtered. use_genotypes (bool) – Use per-sample genotype information from data_source. prefer_genotype_likelihoods (bool) – Prefer using genotype likelihoods from data_source instead of concrete genotypes.
Returns:	A variation resource.
Return type:	`Variation`

data_source(uri)¶

Get a resource of type data_source.

Parameters:	uri (str) – URI for the data_source to retrieve.
Returns:	A resource of type data_source.
Return type:	`DataSource`

data_sources(*args, **kwargs)¶

Query a data source resource collection.

Parameters:	user (`User`) – Filter collection by user.
Returns:	A data source resource collection.
Return type:	`DataSourceCollection`

group(uri)¶

Get a resource of type group.

Parameters:	uri (str) – URI for the group to retrieve.
Returns:	A resource of type group.
Return type:	`Group`

groups(*args, **kwargs)¶

Query a group resource collection.

Returns:	A group resource collection.
Return type:	`GroupCollection`

sample(uri)¶

Get a resource of type sample.

Parameters:	uri (str) – URI for the sample to retrieve.
Returns:	A resource of type sample.
Return type:	`Sample`

samples(*args, **kwargs)¶

Query a sample resource collection.

Parameters:	groups (iterable(`DataSource`)) – Filter collection by groups. public (bool) – Filter collection by public/non-public. user (`User`) – Filter collection by user.
Returns:	A sample resource collection.
Return type:	`SampleCollection`

user(uri)¶

Get a resource of type user.

Parameters:	uri (str) – URI for the user to retrieve.
Returns:	A resource of type user.
Return type:	`User`

users(*args, **kwargs)¶

Query a user resource collection.

Returns:	A user resource collection.
Return type:	`UserCollection`

variant(uri)¶

Get a resource of type variant.

Parameters:	uri (str) – URI for the variant to retrieve.
Returns:	A resource of type variant.
Return type:	`Variant`

variants(*args, **kwargs)¶

Query a variant resource collection.

Returns:	A variant resource collection.
Return type:	`VariantCollection`

variation(uri)¶

Get a resource of type variation.

Parameters:	uri (str) – URI for the variation to retrieve.
Returns:	A resource of type variation.
Return type:	`Variation`

variations(*args, **kwargs)¶

Query a variation resource collection.

Parameters:	sample (`Sample`) – Filter collection by sample.
Returns:	A variation resource collection.
Return type:	`VariationCollection`

manwe.config¶

Manwë configuration object.

class manwe.config.AttributeDictMixin[source]¶

Bases: object

Augment classes with a Mapping interface by adding attribute access.

Taken from Celery (celery.datastructures.AttributeDictMixin).

class manwe.config.Config[source]¶

Bases: flask.config.Config, manwe.config.AttributeDictMixin

Dictionary with some extra ways to fill it from files or special dictionaries (see flask.config.Config) and attribute access.

Initialized with manwe.default_config.

manwe.default_config¶

Manwë default configuration settings.

manwe.default_config.API_ROOT = 'http://127.0.0.1:5000'¶: Varda API root endpoint.

manwe.default_config.COLLECTION_CACHE_SIZE = 20¶: Number of resources to query per collection request.

manwe.default_config.DATA_BUFFER_SIZE = 1048576¶: Size of chunks to yield from data iterator in bytes.

manwe.default_config.TASK_POLL_WAIT = 2¶: Time to wait between polling task state (in seconds).

manwe.default_config.TOKEN = None¶: Varda API authentication token.

manwe.default_config.VERIFY_CERTIFICATE = True¶: Whether or not to verify the API SSL certificate, or a path to a CA_BUNDLE file with certificates of trusted CAs.

manwe.errors¶

API custom exceptions.

exception manwe.errors.ApiError(code, message)[source]¶: Bases: exceptions.Exception

exception manwe.errors.BadRequestError(code, message)[source]¶: Bases: manwe.errors.ApiError

exception manwe.errors.ForbiddenError(code, message)[source]¶: Bases: manwe.errors.ApiError

exception manwe.errors.NotAcceptableError(code, message)[source]¶: Bases: manwe.errors.ApiError

exception manwe.errors.NotFoundError(code, message)[source]¶: Bases: manwe.errors.ApiError

exception manwe.errors.TaskError(code, message)[source]¶: Bases: manwe.errors.ApiError

exception manwe.errors.UnauthorizedError(code, message)[source]¶: Bases: manwe.errors.ApiError

exception manwe.errors.UnsatisfiableRangeError(code, message)[source]¶: Bases: manwe.errors.ApiError

manwe.fields¶

Manwë resource fields.

class manwe.fields.Custom(from_api, to_api, **kwargs)[source]¶

Bases: manwe.fields.Field

Custom field definitions are parameterized with conversion functions.

class manwe.fields.Field(key=None, mutable=False, hidden=False, default=None, doc=None)[source]¶

Bases: object

Base class for resource field definitions.

A field definition can convert field values from their API representation to their Python representation, and vice versa.

__init__(key=None, mutable=False, hidden=False, default=None, doc=None)[source]¶

Create a field instance.

Parameters:	key (str) – Key by which this field is stored in the API. mutable (bool) – If True, field values can be modified. hidden (bool) – If True, field should not be shown. default – Default field value (as a Python value). doc (str) – Documentation string

default = None¶: Default field value (as an API value).

doc = None¶: Documentation string.

from_python(value)[source]¶: Convert Python value to API value.

hidden = None¶: If True, field should not be shown.

key = None¶: Key by which this field is stored in the API. By default inherited from name.

mutable = None¶: If True, field values can be modified.

name¶: Name by which this field is available on the resource class.

to_python(value, resource)[source]¶

Convert API value to Python value.

This gets called from field getters, so the user gets a nice Python value when accessing the field.

Subclasses for structured data (such as lists and dicts) should be careful to not return mutable structures here, since that would allow to bypass the field setter. For example, calling field.append(v) will not add field to the set of dirty fields and will not go through from_python(). Actually, it might not even modify the API value on the resource, because to_python() probably created a copy.

One solution for this, as implemented on Set, is to return an immutable field value (a frozenset in this case) and thereby force modifications through the field setter.

Another approach would be something similar to the MutableDict type in SQLAlchemy (see Mutation Tracking).

This does not apply to Link fields, where the value is itself a resource which should be modified using its own resources.Resource.save() method.

class manwe.fields.Link(resource_key, **kwargs)[source]¶

Bases: manwe.fields.Field

Definition for a resource link.

__init__(resource_key, **kwargs)[source]¶

Parameters:	resource_key (str) – Key for the linked resource.

from_python(value)[source]¶: In request data, a resource link is represented by its URI (a string).

to_python(value, resource)[source]¶

Create a resources.Resource instance from the resource URI.

Modifications of the returned resource should be saved by calling resources.Resource.save() on that resource.

class manwe.fields.Queries(key=None, mutable=False, hidden=False, default=None, doc=None)[source]¶

Bases: manwe.fields.Field

Definition for a field containing annotation queries.

In the API, annotation queries are lists of dictionaries with name and expression items.

As a Python value, we represent this as a dictionary with keys the query names and values the query expressions.

manwe.resources¶

Manwë resources.

class manwe.resources.Annotation(session, values)[source]¶

Bases: manwe.resources.TaskedResource

Class for representing an annotation resource.

annotated_data_source¶: Annotated data source (DataSource instance).

classmethod create(session, data_source, name=None, queries=None)[source]¶

Create an annotation resource.

Parameters:	data_source (`DataSource`) – Data source to annotate. name (str) – Human readable annotation name. queries (dict(str, str)) – Sample queries to calculate variant frequencies over. Keys are query identifiers (alphanumeric) and values are query expressions.
Returns:	An annotation resource.
Return type:	`Annotation`

original_data_source¶: Original data source (DataSource instance).

class manwe.resources.AnnotationCollection(session)[source]¶

Bases: manwe.resources.ResourceCollection

Class for representing an annotation resource collection as an iterator returning Annotation instances.

__init__(session)[source]¶

Query an annotation resource collection.

Returns:	An annotation resource collection.
Return type:	`AnnotationCollection`

resource_class¶: alias of Annotation

class manwe.resources.Coverage(session, values)[source]¶

Bases: manwe.resources.TaskedResource

Class for representing a coverage resource.

classmethod create(session, sample, data_source)[source]¶

Create a coverage resource.

Parameters:	sample (`Sample`) – Sample the coverage resource is part of. data_source (`DataSource`) – Data source for the coverage resource.
Returns:	A coverage resource.
Return type:	`Coverage`

data_source¶: Coverage data (DataSource instance).

sample¶: Coverage is part of this Sample.

class manwe.resources.CoverageCollection(session, sample=None)[source]¶

Bases: manwe.resources.ResourceCollection

Class for representing a coverage resource collection as an iterator returning Coverage instances.

__init__(session, sample=None)[source]¶

Query a coverage resource collection.

Parameters:	sample (`Sample`) – Filter collection by sample.
Returns:	A coverage resource collection.
Return type:	`CoverageCollection`

resource_class¶: alias of Coverage

sample¶: Collection is filtered by this Sample.

class manwe.resources.DataSource(session, values)[source]¶

Bases: manwe.resources.Resource

Class for representing a data source resource.

added¶: Date and time this data source was added.

classmethod create(session, name, filetype, gzipped=False, data=None, local_file=None)[source]¶

Create a data source resource.

Parameters:	name (str) – Human readable data source name. filetype (str) – Data filetype. Possible values are `bed`, `vcf`, and `csv`. gzipped (bool) – Whether or not the data is compressed using gzip. data (file-like object) – Data blob. local_file (str) – A filename on the server filesystem. This can be used instead of data.
Returns:	A data source resource.
Return type:	`DataSource`

data¶: Iterator yielding data as chunks.

filetype¶: Data filetype.

gzipped¶: If True, data is compressed using gzip.

name¶: Human readable data source name.

user¶: Data source is owned by this User.

class manwe.resources.DataSourceCollection(session, user=None)[source]¶

Bases: manwe.resources.ResourceCollection

Class for representing a data source resource collection as an iterator returning DataSource instances.

__init__(session, user=None)[source]¶

Query a data source resource collection.

Parameters:	user (`User`) – Filter collection by user.
Returns:	A data source resource collection.
Return type:	`DataSourceCollection`

resource_class¶: alias of DataSource

user¶: Collection is filtered by this User.

class manwe.resources.Group(session, values)[source]¶

Bases: manwe.resources.Resource

Class for representing a group resource.

classmethod create(session, name)[source]¶

Create a group resource.

Parameters:	name (str) – Human readable group name.
Returns:	A group resource.
Return type:	`Group`

name¶: Human readable group name.

class manwe.resources.GroupCollection(session)[source]¶

Bases: manwe.resources.ResourceCollection

Class for representing a group resource collection as an iterator returning Group instances.

__init__(session)[source]¶

Query a group resource collection.

Returns:	A group resource collection.
Return type:	`GroupCollection`

resource_class¶: alias of Group

class manwe.resources.Resource(session, values)[source]¶

Bases: object

Base class for representing server resources.

Resource fields are defined as class attributes by Field instances.

__init__(session, values)[source]¶

Create a representation for a server resource from a dictionary.

Parameters:	session (`Session`) – Manwë session. values (dict) – Dictionary with field values (using API keys and values).

classmethod create(session, values=None, files=None)[source]¶

Create a new resource on the server and return a representation for it.

Parameters:	session (`Session`) – Manwë session. values (dict) – Dictionary with field values (using Python names and values). files (dict(str, file-like object)) – Open file objects.

Every subclass should override this with an informative docstring.

dirty¶: True if there are any unsaved changes on this resource, False otherwise.

key = None¶: Key for this resource type.

refresh(skip_dirty=False)[source]¶

Refresh resource with data from the server.

Parameters:	skip_dirty (bool) – If True, don’t refresh field values with unsaved changes.

save()[source]¶: Send any unsaved changes on this resource to the server and refresh with data from the server.

save_fields(**values)[source]¶

Send field values specified by keyword arguments to the server and refresh with data from the server (skipping dirty field values).

Keyword arguments use Python names and values.

session = None¶: The session this resource is attached to as .Session.

uri¶: Resource URI.

class manwe.resources.ResourceCollection(session, values=None)[source]¶

Bases: object

Base class for representing server resource collections, iterators returning Resource instances.

Collection filters are defined as class attributes by Field instances (and must not be mutable).

__init__(session, values=None)[source]¶

Create a representation for a server resource collection.

Parameters:	session (`Session`) – Manwë session. values (dict) – Dictionary with field values (using Python names and values).

Every subclass should override this with an informative docstring.

cache_size¶: Number of resources to query per collection request.

next()[source]¶: Return the next resource in the collection.

reset()[source]¶: Reset resource collection iterator.

resource_class = None¶: Resource class to use for instantiating resources in this collection.

session = None¶: The session this resource collection is attached to as .Session.

size = None¶: The total number of resources in this collection as last reported by the server. Note that the actual number of resources produced by the collection iterator might deviate from this number, and this is why there is not __len__ property defined.

class manwe.resources.Sample(session, values)[source]¶

Bases: manwe.resources.Resource

Class for representing a sample resource.

active¶: If True, the sample is active.

added¶: Date and time this sample was added.

coverage_profile¶: If True, the sample has a coverage profile.

classmethod create(session, name, pool_size=1, coverage_profile=True, public=False, notes=None, groups=None)[source]¶

Create a sample resource.

Parameters:	name (str) – Human readable sample name. pool_size (int) – Number of individuals in the sample. coverage_profile (bool) – Whether or not the sample has a coverage profile. public (bool) – Whether or not this sample is public. notes (str) – Human readable notes in Markdown format. groups (iterable(`DataSource`)) – Groups this sample is part of.
Returns:	A sample resource.
Return type:	`Sample`

groups¶: Sample is part of these groups (Group instances).

name¶: Human readable sample name.

notes¶: Human readable notes in Markdown format.

pool_size¶: Number of individuals.

public¶: If True, the sample is public.

user¶: Sample is owned by this User.

class manwe.resources.SampleCollection(session, groups=None, public=None, user=None)[source]¶

Bases: manwe.resources.ResourceCollection

Class for representing a sample resource collection as an iterator returning Sample instances.

__init__(session, groups=None, public=None, user=None)[source]¶

Query a sample resource collection.

Parameters:	groups (iterable(`DataSource`)) – Filter collection by groups. public (bool) – Filter collection by public/non-public. user (`User`) – Filter collection by user.
Returns:	A sample resource collection.
Return type:	`SampleCollection`

groups¶: Collection is filtered by these groups (Group instances).

public¶: Collection is filtered by this public state.

resource_class¶: alias of Sample

user¶: Collection is filtered by this User.

class manwe.resources.Task(resource)[source]¶

Bases: object

Represents a server task.

Instances are equiped with the parent resource which they use to query task state. This means refreshing the parent resource is directly visible on the task.

error¶: The error object as a TaskError if state is failure, None otherwise.

failure¶

Whether or not task is in failure state.

If True, error is set.

progress¶: Task progress in the range 0 to 100 if state is running, None otherwise.

resubmit()[source]¶: Resubmit task.

running¶

Whether or not task is in running state.

If True, progress is set.

state¶: Task state. Possible values are waiting, running, succes, and failure.

success¶: Whether or not task is in success state.

wait()[source]¶: Block while state is waiting or running, polling the server every TASK_POLL_WAIT seconds.

wait_and_monitor()[source]¶

Iterator, yielding progress while state is waiting or running, polling the server every TASK_POLL_WAIT seconds.

After that, yield 100, or raise error if state is failure.

waiting¶: Whether or not task is in waiting state.

class manwe.resources.TaskedResource(session, values)[source]¶

Bases: manwe.resources.Resource

Base class for representing server resources with tasks.

task¶: Server task (Task instance).

class manwe.resources.User(session, values)[source]¶

Bases: manwe.resources.Resource

Class for representing a user resource.

added¶: Date and time this user was added.

classmethod create(session, login, password, name=None, email=None, roles=None)[source]¶

Create a user resource.

Parameters:	login (str) – Login name used for authentication. password (str) – Password used for authentication. name (str) – Human readable user name. email (str) – User e-mail address. roles (iterable(str)) – Roles for this user (values must be from `USER_ROLES`).
Returns:	A user resource.
Return type:	`User`

email¶: Email address.

login¶: Login name.

name¶: Human readable user name.

password¶: Password used for authentication.

roles¶: Roles for this user.

class manwe.resources.UserCollection(session)[source]¶

Bases: manwe.resources.ResourceCollection

Class for representing a user resource collection as an iterator returning User instances.

__init__(session)[source]¶

Query a user resource collection.

Returns:	A user resource collection.
Return type:	`UserCollection`

resource_class¶: alias of User

class manwe.resources.Variant(session, values)[source]¶

Bases: manwe.resources.Resource

Class for representing a variant resource.

annotate(queries=None)[source]¶

Annotate this variant with the observed frequencies over sets of samples

Parameters:	queries (dict(str, str)) – Sample queries to calculate variant frequencies over. Keys are query identifiers (alphanumeric) and values are query expressions.
Returns:	Variant observation frequencies. Keys are query identifiers and values are dictionaries with coverage, frequency, frequency_het, and frequency_hom.
Return type:	dict(str, dict)

chromosome¶: Chromosome name.

classmethod create(session, chromosome, position, reference='', observed='')[source]¶

Create a variant resource.

Parameters:	chromosome (str) – Chromosome name. position (int) – Position of variant on chromosome. reference (str) – Reference allele. observed (str) – Observed allele.
Returns:	A variant resource.
Return type:	`Variant`

observed¶: Observed allele.

position¶: Position of variant on chromosome.

reference¶: Reference allele.

class manwe.resources.VariantCollection(session)[source]¶

Bases: manwe.resources.ResourceCollection

Class for representing a variant resource collection as an iterator returning Variant instances.

__init__(session)[source]¶

Query a variant resource collection.

Returns:	A variant resource collection.
Return type:	`VariantCollection`

resource_class¶: alias of Variant

class manwe.resources.Variation(session, values)[source]¶

Bases: manwe.resources.TaskedResource

Class for representing a variation resource.

classmethod create(session, sample, data_source, skip_filtered=True, use_genotypes=True, prefer_genotype_likelihoods=False)[source]¶

Create a variation resource.

Parameters:	sample (`Sample`) – Sample the variation resource is part of. data_source (`DataSource`) – Data source for the variation resource. skip_filtered (bool) – Discard entries in data_source marked as filtered. use_genotypes (bool) – Use per-sample genotype information from data_source. prefer_genotype_likelihoods (bool) – Prefer using genotype likelihoods from data_source instead of concrete genotypes.
Returns:	A variation resource.
Return type:	`Variation`

data_source¶: Variation data (DataSource instance).

sample¶: Variation is part of this Sample.

class manwe.resources.VariationCollection(session, sample=None)[source]¶

Bases: manwe.resources.ResourceCollection

Class for representing a variation resource collection as an iterator returning Variation instances.

__init__(session, sample=None)[source]¶

Query a variation resource collection.

Parameters:	sample (`Sample`) – Filter collection by sample.
Returns:	A variation resource collection.
Return type:	`VariationCollection`

resource_class¶: alias of Variation

sample¶: Collection is filtered by this Sample.

class manwe.resources.classproperty(getter)[source]¶

Bases: object

Decorator for defining computed class attributes, dual to the property built-in complementary to the classmethod built-in.

Example usage:

>>> class Foo(object):
...     x= 4
...     @classproperty
...     def number(cls):
...         return cls.x
...
>>> Foo().number
4
>>> Foo.number
4

Copied from bobince.

manwe.session¶

Manwë sessions.

class manwe.session.AbstractSession(api_root=None, token=None, config=None, log_level=20)[source]¶

Bases: object

Abstract session for interfacing the server API.

Subclasses should have a dictionary of resources in their _collections attribute.

__init__(api_root=None, token=None, config=None, log_level=20)[source]¶

Create a session.

Parameters:	api_root (str) – Varda API root endpoint. token (str) – Varda API authentication token. config (config.Config) – Manwë configuration object (api_root and token take precedence). log_level (logging.LOG_LEVEL) – Control the level of log messages you will see. Use log_level=logging.DEBUG to troubleshoot.

get(*args, **kwargs)[source]¶: Short for request() where method is GET.

patch(*args, **kwargs)[source]¶: Short for request() where method is PATCH.

post(*args, **kwargs)[source]¶: Short for request() where method is POST.

request(method, uri, **kwargs)[source]¶

Send HTTP request to server.

Raises requests.RequestException:
	Exception occurred while handling an API request.

set_log_level(log_level)[source]¶: Control the level of log messages you will see.

manwe.session.stringify(value)[source]¶

Serialize value to a str parsable by Varda.

Only works one level deep, so no nesting of structured data.

>>> stringify(34)
'34'
>>> stringify(False)
'false'
>>> stringify([4,2,6])
'4,2,6'
>>> stringify({'a': False, 'b': True})
'a:false,b:true'