htsworkflow/submission/encoded.py

   1 """Interface with encoded software for ENCODE3 data submission & warehouse
   2
   3 This allows retrieving blocks
   4 """
   5
   6
   7 from __future__ import print_function
   8 import collections
   9 import logging
  10 import json
  11 import jsonschema
  12 import requests
  13 import types
  14 from urlparse import urljoin, urlparse, urlunparse
  15
  16 LOGGER = logging.getLogger(__name__)
  17
  18 ENCODED_CONTEXT = {
  19     # The None context will get added to the root of the tree and will
  20     # provide common defaults.
  21     None: {
  22         # terms in multiple encoded objects
  23         'award': {'@type': '@id'},
  24         'dataset': {'@type': '@id'},
  25         'description': 'rdf:description',
  26         'documents': {'@type': '@id'},
  27         'experiment': {'@type': '@id'},
  28         'href': {'@type': '@id'},
  29         'lab': {'@type': '@id'},
  30         'library': {'@type': '@id'},
  31         'pi': {'@type': '@id'},
  32         'platform': {'@type': '@id'},
  33         'replicates': {'@type': '@id'},
  34         'submitted_by': {'@type': '@id'},
  35         'url': {'@type': '@id'},
  36     },
  37     # Identify and markup contained classes.
  38     # e.g. in the tree there was a sub-dictionary named 'biosample'
  39     # That dictionary had a term 'biosample_term_id, which is the
  40     # term that should be used as the @id.
  41     'biosample': {
  42         'biosample_term_id': {'@type': '@id'},
  43     },
  44     'experiment': {
  45         "assay_term_id": {"@type": "@id"},
  46         "files": {"@type": "@id"},
  47         "original_files": {"@type": "@id"},
  48     },
  49     # I tried to use the JSON-LD mapping capabilities to convert the lab
  50     # contact information into a vcard record, but the encoded model
  51     # didn't lend itself well to the vcard schema
  52     #'lab': {
  53     #    "address1": "vcard:street-address",
  54     #    "address2": "vcard:street-address",
  55     #    "city": "vcard:locality",
  56     #    "state": "vcard:region",
  57     #    "country": "vcard:country"
  58     #},
  59     'library': {
  60         'nucleic_acid_term_id': {'@type': '@id'}
  61     }
  62 }
  63
  64 #FIXME: this needs to be initialized from rdfns
  65 ENCODED_NAMESPACES = {
  66     # JSON-LD lets you define namespaces so you can used the shorted url syntax.
  67     # (instead of http://www.w3.org/2000/01/rdf-schema#label you can do
  68     # rdfs:label)
  69     "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
  70     "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
  71     "owl": "http://www.w3.org/2002/07/owl#",
  72     "dc": "htp://purl.org/dc/elements/1.1/",
  73     "xsd": "http://www.w3.org/2001/XMLSchema#",
  74     "vcard": "http://www.w3.org/2006/vcard/ns#",
  75
  76     # for some namespaces I made a best guess for the ontology root.
  77     "EFO": "http://www.ebi.ac.uk/efo/",  # EFO ontology
  78     "OBO": "http://purl.obolibrary.org/obo/",  # OBO ontology
  79     "OBI": "http://purl.obolibrary.org/obo/OBI_",  # Ontology for Biomedical Investigations
  80     # OBI: available from http://svn.code.sf.net/p/obi/code/releases/2012-07-01/merged/merged-obi-comments.owl
  81     "SO": "http://purl.obolibrary.org/obo/SO_",  # Sequence ontology
  82     # SO: available from http://www.berkeleybop.org/ontologies/so.owl
  83     # NTR: New Term Request space for DCC to implement new ontology terms
  84
  85 }
  86
  87 ENCODED_SCHEMA_ROOT = '/profiles/'
  88
  89
  90 class ENCODED:
  91     '''Programatic access encoded, the software powering ENCODE3's submit site.
  92     '''
  93     def __init__(self, server, contexts=None, namespaces=None):
  94         self.server = server
  95         self.scheme = 'https'
  96         self.username = None
  97         self.password = None
  98         self.contexts = contexts if contexts else ENCODED_CONTEXT
  99         self.namespaces = namespaces if namespaces else ENCODED_NAMESPACES
 100         self.json_headers = {'content-type': 'application/json', 'accept': 'application/json'}
 101         self.schemas = {}
 102
 103     def get_auth(self):
 104         return (self.username, self.password)
 105     auth = property(get_auth)
 106
 107     def load_netrc(self):
 108         import netrc
 109         session = netrc.netrc()
 110         authenticators = session.authenticators(self.server)
 111         if authenticators:
 112             self.username = authenticators[0]
 113             self.password = authenticators[2]
 114
 115     def add_jsonld_context(self, tree, default_base):
 116         """Add contexts to various objects in the tree.
 117
 118         tree is a json tree returned from the DCC's encoded database.
 119         contexts is a dictionary of dictionaries containing contexts
 120                 for the various  possible encoded classes.
 121         base, if supplied allows setting the base url that relative
 122             urls will be resolved against.
 123         """
 124         self.add_jsonld_child_context(tree, default_base)
 125         self.add_jsonld_namespaces(tree['@context'])
 126
 127     def add_jsonld_child_context(self, obj, default_base):
 128         '''Add JSON-LD context to the encoded JSON.
 129
 130         This is recursive because some of the IDs were relative URLs
 131         and I needed a way to properly compute a the correct base URL.
 132         '''
 133         # pretend strings aren't iterable
 134         if type(obj) in types.StringTypes:
 135             return
 136
 137         # recurse on container types
 138         if isinstance(obj, collections.Sequence):
 139             # how should I update lists?
 140             for v in obj:
 141                 self.add_jsonld_child_context(v, default_base)
 142             return
 143
 144         if isinstance(obj, collections.Mapping):
 145             for v in obj.values():
 146                 self.add_jsonld_child_context(v, default_base)
 147
 148         # we have an object. attach a context to it.
 149         if self._is_encoded_object(obj):
 150             context = self.create_jsonld_context(obj, default_base)
 151             if len(context) > 0:
 152                 obj.setdefault('@context', {}).update(context)
 153
 154     def add_jsonld_namespaces(self, context):
 155         '''Add shortcut namespaces to a context
 156
 157         Only needs to be run on the top-most context
 158         '''
 159         context.update(self.namespaces)
 160
 161     def create_jsonld_context(self, obj, default_base):
 162         '''Synthesize the context for a encoded type
 163
 164         self.contexts[None] = default context attributes added to any type
 165         self.contexts[type] = context attributes for this type.
 166         '''
 167         context = {'@base': urljoin(default_base, obj['@id']),
 168                    '@vocab': self.get_schema_url(obj)}
 169         # add in defaults
 170         context.update(self.contexts[None])
 171         for t in obj['@type']:
 172             if t in self.contexts:
 173                 context.update(self.contexts[t])
 174         return context
 175
 176     def get_json(self, obj_id, **kwargs):
 177         '''GET an ENCODE object as JSON and return as dict
 178
 179         Uses prepare_url to allow url short-cuts
 180         if no keyword arguments are specified it will default to adding limit=all
 181         Alternative keyword arguments can be passed in and will be sent to the host.
 182
 183         Known keywords are:
 184           limit - (integer or 'all') how many records to return, all for all of them
 185           embed - (bool) if true expands linking ids into their associated object.
 186           format - text/html or application/json
 187         '''
 188         if len(kwargs) == 0:
 189             kwargs['limit'] = 'all'
 190
 191         url = self.prepare_url(obj_id)
 192         LOGGER.info('requesting url: {}'.format(url))
 193
 194         # do the request
 195
 196         LOGGER.debug('username: %s, password: %s', self.username, self.password)
 197         response = requests.get(url, auth=self.auth, headers=self.json_headers, params=kwargs)
 198         if not response.status_code == requests.codes.ok:
 199             LOGGER.error("Error http status: {}".format(response.status_code))
 200             response.raise_for_status()
 201         return response.json()
 202
 203     def get_jsonld(self, obj_id, **kwargs):
 204         '''Get ENCODE object as JSONLD annotated with classses contexts
 205
 206         see get_json for documentation about what keywords can be passed.
 207         '''
 208         url = self.prepare_url(obj_id)
 209         json = self.get_json(obj_id, **kwargs)
 210         self.add_jsonld_context(json, url)
 211         return json
 212
 213     def get_object_type(self, obj):
 214         """Return type for a encoded object
 215         """
 216         obj_type = obj.get('@type')
 217         if obj_type and isinstance(obj_type, collections.Sequence):
 218             return obj_type[0]
 219
 220     def get_schema_url(self, obj):
 221         obj_type = self.get_object_type(obj)
 222         if obj_type:
 223             return self.prepare_url(ENCODED_SCHEMA_ROOT + obj_type + '.json') + '#'
 224
 225     def _is_encoded_object(self, obj):
 226         '''Test to see if an object is a JSON-LD object
 227
 228         Some of the nested dictionaries lack the @id or @type
 229         information necessary to convert them.
 230         '''
 231         if not isinstance(obj, collections.Iterable):
 232             return False
 233
 234         if '@id' in obj and '@type' in obj:
 235             return True
 236         return False
 237
 238     def patch_json(self, obj_id, changes):
 239         """Given a dictionary of changes push them as a HTTP patch request
 240         """
 241         url = self.prepare_url(obj_id)
 242         payload = json.dumps(changes)
 243         response = requests.patch(url, auth=self.auth, headers=self.json_headers, data=payload)
 244         if response.status_code != requests.codes.ok:
 245             LOGGER.error("Error http status: {}".format(response.status_code))
 246             LOGGER.error("Response: %s", response.text)
 247             response.raise_for_status()
 248         return response.json()
 249
 250     def put_json(self, obj_id, new_object):
 251         url = self.prepare_url(obj_id)
 252         payload = json.dumps(new_object)
 253         response = requests.put(url, auth=self.auth, headers=self.json_headers, data=payload)
 254         if response.status_code != requests.codes.created:
 255             LOGGER.error("Error http status: {}".format(response.status_code))
 256             response.raise_for_status()
 257         return response.json()
 258
 259     def post_json(self, collection_id, new_object):
 260         url = self.prepare_url(collection_id)
 261         payload = json.dumps(new_object)
 262
 263         response = requests.post(url, auth=self.auth, headers=self.json_headers, data=payload)
 264         if response.status_code != requests.codes.created:
 265             LOGGER.error("Error http status: {}".format(response.status_code))
 266             response.raise_for_status()
 267         return response.json()
 268
 269     def prepare_url(self, request_url):
 270         '''This attempts to provide some convienence for accessing a URL
 271
 272         Given a url fragment it will default to :
 273         * requests over http
 274         * requests to self.server
 275
 276         This allows fairly flexible urls. e.g.
 277
 278         prepare_url('/experiments/ENCSR000AEG')
 279         prepare_url('submit.encodedcc.org/experiments/ENCSR000AEG')
 280         prepare_url('http://submit.encodedcc.org/experiments/ENCSR000AEG?limit=all')
 281
 282         should all return the same url
 283         '''
 284         # clean up potentially messy urls
 285         url = urlparse(request_url)._asdict()
 286         if not url['scheme']:
 287             url['scheme'] = self.scheme
 288         if not url['netloc']:
 289             url['netloc'] = self.server
 290         url = urlunparse(url.values())
 291         return url
 292
 293     def search_jsonld(self, term, **kwargs):
 294         '''Send search request to ENCODED
 295         '''
 296         url = self.prepare_url('/search/')
 297         result = self.get_json(url, searchTerm=term, **kwargs)
 298         self.convert_search_to_jsonld(result)
 299         return result
 300
 301     def convert_search_to_jsonld(self, result):
 302         '''Add the context to search result
 303
 304         Also remove hard to handle nested attributes
 305           e.g. remove object.term when we have no id
 306         '''
 307         graph = result['@graph']
 308         for i, obj in enumerate(graph):
 309             # suppress nested attributes
 310             graph[i] = {k: v for k, v in obj.items() if '.' not in k}
 311
 312         self.add_jsonld_context(result, self.prepare_url(result['@id']))
 313         return result
 314
 315     def validate(self, obj):
 316         obj_type = self.get_object_type(obj)
 317         schema_url = self.get_schema_url(obj)
 318         if not schema_url:
 319             raise ValueError("Unable to construct schema url")
 320
 321         schema = self.schemas.setdefault(obj_type, self.get_json(schema_url))
 322         hidden = obj.copy()
 323         del hidden['@id']
 324         del hidden['@type']
 325         jsonschema.validate(hidden, schema)
 326
 327
 328 if __name__ == '__main__':
 329     # try it
 330     from htsworkflow.util.rdfhelp import get_model, dump_model
 331     from htsworkflow.util.rdfjsonld import load_into_model
 332     from pprint import pprint
 333     model = get_model()
 334     logging.basicConfig(level=logging.DEBUG)
 335     encoded = ENCODED('test.encodedcc.org')
 336     encoded.load_netrc()
 337     body = encoded.get_jsonld('/experiments/ENCSR000AEC/')
 338     pprint(body)
 339     load_into_model(model, body)
 340     #dump_model(model)