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, object_type):
 221         return self.prepare_url(ENCODED_SCHEMA_ROOT + object_type + '.json') + '#'
 222
 223     def _is_encoded_object(self, obj):
 224         '''Test to see if an object is a JSON-LD object
 225
 226         Some of the nested dictionaries lack the @id or @type
 227         information necessary to convert them.
 228         '''
 229         if not isinstance(obj, collections.Iterable):
 230             return False
 231
 232         if '@id' in obj and '@type' in obj:
 233             return True
 234         return False
 235
 236     def patch_json(self, obj_id, changes):
 237         """Given a dictionary of changes push them as a HTTP patch request
 238         """
 239         url = self.prepare_url(obj_id)
 240         payload = json.dumps(changes)
 241         response = requests.patch(url, auth=self.auth, headers=self.json_headers, data=payload)
 242         if response.status_code != requests.codes.ok:
 243             LOGGER.error("Error http status: {}".format(response.status_code))
 244             LOGGER.error("Response: %s", response.text)
 245             response.raise_for_status()
 246         return response.json()
 247
 248     def put_json(self, obj_id, new_object):
 249         url = self.prepare_url(obj_id)
 250         payload = json.dumps(new_object)
 251         response = requests.put(url, auth=self.auth, headers=self.json_headers, data=payload)
 252         if response.status_code != requests.codes.created:
 253             LOGGER.error("Error http status: {}".format(response.status_code))
 254             response.raise_for_status()
 255         return response.json()
 256
 257     def post_json(self, collection_id, new_object):
 258         url = self.prepare_url(collection_id)
 259         payload = json.dumps(new_object)
 260
 261         response = requests.post(url, auth=self.auth, headers=self.json_headers, data=payload)
 262         if response.status_code != requests.codes.created:
 263             LOGGER.error("Error http status: {}".format(response.status_code))
 264             response.raise_for_status()
 265         return response.json()
 266
 267     def prepare_url(self, request_url):
 268         '''This attempts to provide some convienence for accessing a URL
 269
 270         Given a url fragment it will default to :
 271         * requests over http
 272         * requests to self.server
 273
 274         This allows fairly flexible urls. e.g.
 275
 276         prepare_url('/experiments/ENCSR000AEG')
 277         prepare_url('submit.encodedcc.org/experiments/ENCSR000AEG')
 278         prepare_url('http://submit.encodedcc.org/experiments/ENCSR000AEG?limit=all')
 279
 280         should all return the same url
 281         '''
 282         # clean up potentially messy urls
 283         url = urlparse(request_url)._asdict()
 284         if not url['scheme']:
 285             url['scheme'] = self.scheme
 286         if not url['netloc']:
 287             url['netloc'] = self.server
 288         url = urlunparse(url.values())
 289         return url
 290
 291     def search_jsonld(self, term, **kwargs):
 292         '''Send search request to ENCODED
 293         '''
 294         url = self.prepare_url('/search/')
 295         result = self.get_json(url, searchTerm=term, **kwargs)
 296         self.convert_search_to_jsonld(result)
 297         return result
 298
 299     def convert_search_to_jsonld(self, result):
 300         '''Add the context to search result
 301
 302         Also remove hard to handle nested attributes
 303           e.g. remove object.term when we have no id
 304         '''
 305         graph = result['@graph']
 306         for i, obj in enumerate(graph):
 307             # suppress nested attributes
 308             graph[i] = {k: v for k, v in obj.items() if '.' not in k}
 309
 310         self.add_jsonld_context(result, self.prepare_url(result['@id']))
 311         return result
 312
 313     def validate(self, obj, object_type=None):
 314         object_type = object_type if object_type else self.get_object_type(obj)
 315         schema_url = self.get_schema_url(object_type)
 316         if not schema_url:
 317             raise ValueError("Unable to construct schema url")
 318
 319         schema = self.schemas.setdefault(object_type, self.get_json(schema_url))
 320         hidden = obj.copy()
 321         if '@id' in hidden:
 322             del hidden['@id']
 323         if '@type' in hidden:
 324             del hidden['@type']
 325         jsonschema.validate(hidden, schema)
 326
 327 class TypedColumnParser(object):
 328     @staticmethod
 329     def parse_sheet_array_type(value):
 330         """Helper function to parse :array columns in sheet
 331         """
 332         return value.split(', ')
 333
 334     @staticmethod
 335     def parse_sheet_integer_type(value):
 336         """Helper function to parse :integer columns in sheet
 337         """
 338         return int(value)
 339
 340     @staticmethod
 341     def parse_sheet_boolean_type(value):
 342         """Helper function to parse :boolean columns in sheet
 343         """
 344         return bool(value)
 345
 346     @staticmethod
 347     def parse_sheet_timestamp_type(value):
 348         """Helper function to parse :date columns in sheet
 349         """
 350         return value.strftime('%Y-%m-%d')
 351
 352     @staticmethod
 353     def parse_sheet_string_type(value):
 354         """Helper function to parse :string columns in sheet (the default)
 355         """
 356         return unicode(value)
 357
 358     def __getitem__(self, name):
 359         parser = {
 360             'array': self.parse_sheet_array_type,
 361             'boolean': self.parse_sheet_boolean_type,
 362             'integer': self.parse_sheet_integer_type,
 363             'date': self.parse_sheet_timestamp_type,
 364             'string': self.parse_sheet_string_type
 365         }.get(name)
 366         if parser:
 367             return parser
 368         else:
 369             raise RuntimeError("unrecognized column type")
 370
 371     def __call__(self, header, value):
 372         header = header.split(':')
 373         column_type = 'string'
 374         if len(header) > 1:
 375             if header[1] == 'skip':
 376                 return None, None
 377             else:
 378                 column_type = header[1]
 379         return header[0], self[column_type](value)
 380
 381 typed_column_parser = TypedColumnParser()
 382
 383 if __name__ == '__main__':
 384     # try it
 385     from htsworkflow.util.rdfhelp import get_model, dump_model
 386     from htsworkflow.util.rdfjsonld import load_into_model
 387     from pprint import pprint
 388     model = get_model()
 389     logging.basicConfig(level=logging.DEBUG)
 390     encoded = ENCODED('test.encodedcc.org')
 391     encoded.load_netrc()
 392     body = encoded.get_jsonld('/experiments/ENCSR000AEC/')
 393     pprint(body)
 394     load_into_model(model, body)
 395     #dump_model(model)