iReceptor Documentation

Description

iReceptor is a distributed data management system and scientific gateway for mining “Next Generation” sequence data from immune responses. iReceptor provides a technology platform that lowers the barrier to immune genetics researchers who need to federate large, distributed, immune genetics databases in order to answer complex questions about the immune response.

For more informaton about the iReceptor architecture, please refer to the Architecture Page.

Using the iReceptor Gateway

Researchers can use the iReceptor Scientific Gateway by applying for an account and logging in to the web interface at gateway.ireceptor.org. To apply for an account, please send an email to support@ireceptor.org. Documentation on how to use the iReceptor Scientific Gateway is available through the documentation pages on the right hand menu or at the main user documentation page.

Using the iReceptor Repository Service API

Repository Service API

The iReceptor Repository Service implements the AIRR Community's MiAIRR data sharing recommendations, using a REST API to perform queries against a AIRR repository and responding to that query with a well defined JSON response. The defintion of the iReceptor API is available at the iReceptor API GitHub Repository. The API has two main entry points, one for metadata at the study/subject/sample level and one for the annotated sequence level of AIRR-seq data. These API entry points are:

  • samples - https://client_name:client_sharedsecret@dbservice.host.org/baseurl/samples?username=username
  • sequences - https://client_name:client_sharedsecret@dbservice.host.org/baseurl/sequences?username=username

For those repositories that support the iReceptor security layer, the following information is required to connect to an iReceptor Repository Service:

  • client_name: the username that creates the trust relationship between the iReceptor Gateway and the Repository Service. This prevents untrusted servers from connencting to the repository. This username/secret pair would typically be provided to the client by the repository data steward. For a repository to be used by the iReceptor Gateway a repository must provide this information to the iReceptor Gateway when the repository is registered with iReceptor.
  • client_sharedsecret: the shared secret or "password" required to connect to the repository service as a trusted consumer of data.
  • dbservice.host.org: the hostname and base URL for the entry point for repository connections. The base URL allows multiple versions of the API to be supported on the same server.
  • dbusername: the username for accessing the data repository itself. This allows the repository to provide a second layer of user level authorization to the repository.

For example, if a client_name:client_sharedsecret is provided to an application such as iReceptor (e.g. ireceptor:ireceptorsecret), then iReceptor would send that information to the repository service as above. The service can then confirm that the client is how they say they are. In addition, the iReceptor Gateway would send the user identity of the individual on the gateway making the request to the repository service. This allows a data steward to control access at the user level as well as the client level. Note at this time no user level authentication is performed, so user level access is based on a trust relationship between the client (using the client_name and sharesecret) and the repository. That is, in the example above, the repository and the gateway share a mapping of the username and the repository trusts that the client is managing access to user's.

For those repositories that implement the above security protocol, Nit is not possible to access an iReceptor Repository Service unless the consumer of the service is provided with a valid client_username and client_sharedsecret. Thus when using URLs of the form above, access will be denied unless the correct authentication mechanisms are used.

It is not necessary for all repositories to implement the iReceptor security protocol. In this instance, the repository is providing public, open data to the iReceptor Data Commons. In these instances, simple URLs such as:

  • samples - https://dbservice.host.org/baseurl/samples
  • sequences - https://dbservice.host.org/baseurl/sequences

iReceptor manages the iReceptor Public Archive (IPA), using Compute Canada resources, using the URL htps://ipa.ireceptor.org. This repository is running the iReceptor v2.0 version of the iReceptor IPA. As such, it is possible to retrieve data using the following URLs:

  • samples - https://ipa.ireceptororg/v2/samples
  • sequences - https://ipa.ireceptor.org/v2/sequences

 

Policies

The iReceptor Scientific Gateway is hosted, operated, and maintained by the IRMACS Centre at Simon Fraser University. Interested researchers can apply for iReceptor accounts by visiting the iReceptor Gateway login page. No data (except for temporary staged data) is maintained on the iReceptor Gateway machine. If researchers require access to an iReceptor Repository, they should contact the iReceptor Repository data steward for that site. If researchers want to run their own iReceptor repository as part of the iReceptor Data Commons, they should contact the iReceptor team at support@ireceptor.org.

Licensing

The iReceptor Gateway platform is operated by the IRMACS Centre at Simon Fraser Unversity. The iReceptor software is available for download at the iReceptor GitHub Repository. Research groups that would like to download the software should contact support@ireceptor.org.

iReceptor makes extensive use of the AGAVE APIs. In particular the Authentication and Computation services utilize AGAVE services. AGAVE's licensing and terms of service are described on the AGAVE Licensing and AGAVE terms of service page.

iReceptor makes use of Compute Canada resources. Any use of Compute Canada resources are done under their Terms of Service and Acceptable Use Policy.

Provenance

The iReceptor Gateway and its component parts were released into beta-production on June 30, 2015. The software and operations of related sites are managed by the IRMACS Centre. This software is available for use by researchers in the community, but it is beta software.  The software is provided AS-IS, as described in the "3 Claues BSD" license. Software release will be carried out as follows:

  • Software will be released by the iReceptor team at the IRMACS Centre.
  • A specific software release will ensure that the iReceptor Gateway works with the coresponding Repository Service APIs of that release. Although backwards compatibility with past Repository APIs will be a priority, this can not be guaranteed.
  • Compatibility with third party packages such as AGAVE and integration with Compute Canda will be maintained where possible, but can not be guaranteed.