iReceptor Documentation

Description

iReceptor is a distributed data management system and scientific gateway for mining “Next Generation” sequence data from immune responses. 

iReceptor will provide a technology platform that will lower 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. The focus of the iReceptor project is to leverage existing capabilities and technologies to build a new scientific platform for the immune genetics research community. In order to provide such a system, the iReceptor project will develop the following components:

  • An iReceptor immune genetics data model and database design that enhances existing genomics data models,
  • A set of data adaptor/import/conversion services for transforming immune genetics data sets into the iReceptor data model,
  • An iReceptor data service that will expose access to a set of distributed immune genetics databases,
  • A set of iReceptor computational services that provide researchers access to advanced computational resources for the analysis of immune genetics data,
  • A scientific gateway web platform that ties these components together to enable a new type of immune genetics research.

Using the iReceptor Gateway

Researchers can use the iReceptor Scientific Gateway by applying for an account and logging in to the web interface at ireceptorgw.irmacs.sfu.ca. To apply for an account, please send an email to ireceptor-help@sfu.ca.

Using the iReceptor Service APIs

DB Service API

The iReceptor DB Service has three API entry points, one for meta-data, one for biological samples, and one for sequence data. These API entry points are:

  • meta-data - https://portal_username:portal_sharedsecret@dbservice.host.org/baseurl/metadata?username=dbusername
  • biological samples - https://portal_username:portal_sharedsecret@dbservice.host.org/baseurl/samples?username=dbusername
  • sequence data - https://portal_username:portal_sharedsecret@dbservice.host.org/baseurl/sequences?username=dbusername

The following information is required to connect to an iReceptor DB Service:

  • portal_username: the username that creates the trust relationship between the iReceptor Gateway and the DBService. This prevents untrusted servers from connencting to the DBService. Provided by the DBService to the iReceptor Gateway when a DBService is registered with iReceptor.
  • portal_sharedsecret: the shared secret or "password" required to connect to the DBService as a trusted consumer of data.
  • dbservice.host.org: the hostname and base URL for the entry point for iReceptor DBService connections.
  • dbusername: the username for accessing the data repository itself. This allows the DBService to provide user level authroization to specific data in the data repository.

Note that because of the data security requirements for iReceptor and its DBService, it is not possible to access any DBService unless the consumer of the service is provided with the portal_username and portal_sharedsecret. Thus when using URLs of the form above, access will be denied unless the correct authentication and authorization are permitted by the DBService.

The base URL for the iReceptor Compute Canada database is: https://joffre.westgrid.ca/iReceptor

Data Migration API

The iReceptor Data Migration service has three entry points. One will provide sample metada, and connect the sample to a particular project in the database, one loads results of sequencing a specific sample (a FASTA formatted file), and one uploads the results of annotation process performed on a FASTA file. The entry points are:

  • sample metadata: https://node_username:node_password@dbservice.nodehost.org/baseurl/backend/parsemetadata
    • parameters are passed in the POST request, as follows:
      • internal iReceptor username of the person uploading the sample metadata
      • tab-delimited text file containing the sample metadata
  • sequencing result: https://node_username:node_password@dbservice.nodehost.org/baseurl/backend/parsefasta
    • parameters are passed in the POST request, as follows:
      • internal iReceptor username of the person uploading the sample metadata
      • name of the project for which sequencing was performed
      • label of the sample used for the sequencing
      • sequencing results file in FASTA format, uncompressed
  • annotation result: https://node_username:node_password@dbservice.nodehost.org/baseurl/backend/parsevquest
    • parameters are passed in the POST request, as follows:
      • internal iReceptor username of the person uploading the sample metadata
      • name of the project for which sequencing was performed
      • label of the sample used for the sequencing
      • output file from the V-Quest program. File contains a zipped folder, containing 11 tab-delimited files.

The following information is required to connect to an iReceptor Data Migration Service:

  • node_username: the username that creates the trust relationship between the iReceptor Gateway and the Data Migration Service. This prevents untrusted servers from connencting to the service. Provided by the Data Migration Service to users that are authorized to upload data to an iReceptor database.
  • node_sharedsecret: the shared secret or "password" required to connect to the Data Migration Service.
  • dbservice.nodehost.org: the hostname and base URL for the entry point for iReceptor Data Migration Service connections.

Authentication API

iReceptor uses the AGAVE authentication API through an iReceptor tenant operated at the Texas Advanced Computation Centre. AGAVE uses OAuth2 to autehticate users. It is possible to get an authentication token using the AGAVE API running on the iReceptor tenant with this URL:

https://irec.agave.tacc.utexas.edu/token

iReceptor uses OAuth2, through the AGAVE API to authenticate users on the Gateway. This AGAVE Authentication API is documented in detail at the AGAVE authentication web site. Note it is possible to use the wide range of APIs available from AGAVE, including the command line API, to access and control AGAVE authentication. As with the DBService APIs, authentication credentials from the iReceptor AGAVE tenant are required to access these APIs.

Computation API

iReceptor uses the AGAVE systems, apps, and jobs APIs through an iReceptor tenant operated at the Texas Advanced Computation Centre. Computational systems are created on behalf of users on the Compute Canada bugaboo machine. Note it is necessary to have a Compute Canada account on that Compute Canada machine. Apps are created to provide a wrapper around computational analysis tools. Jobs are instances of Apps that run on specific systems. Jobs are managed on behalf of users when data is federated and staged for analysis with a specific App.

  • https://irec.agave.tacc.utexas.edu/systems/v2/
  • https://irec.agave.tacc.utexas.edu/apps/v2/
  • https://irec.agave.tacc.utexas.edu/jobs/v2/

iReceptor uses OAuth2, through the AGAVE API to authenticate users on the Gateway. This AGAVE Authentication API is documented in detail at the AGAVE systems tutorial and AGAVE jobs tutorial web site. Note it is possible to use the wide range of APIs available from AGAVE<, including the command line API, to access and monitor iReceptor data, systems, apps, and jobs. As with the DBService APIs, authentication credentials from the iReceptor AGAVE tenant are required to access these APIs.

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 Database, they should contact the iReceptor DB administrator for that site. If researchers want to run their own iReceptor DB and DBService, they should contact the iRecptor team at ireceptor-help@sfu.ca.

Licensing

The iReceptor Gateway platform is operated by the IRMACS Centre at Simon Fraser Unversity. It is available for use but is not available for download. The iReceptor DB Service is available for download under the "3 Clause BSD" license. Research groups that would like to download the software should contact ireceptor-help@sfu.ca.

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 DB Service APIs of that release. Although backwards compatibility with past DBService 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.