Skip to content

Latest commit

 

History

History
1654 lines (1290 loc) · 62.9 KB

minutes.md

File metadata and controls

1654 lines (1290 loc) · 62.9 KB

Meeting Minutes for the AIRR Common Repository Working Group

This document contains notes and minutes from conference meetings of the AIRR Common Repository Working Group.

Agenda for 2020.01.30

Discusion Topics

  1. Bookkeeping
  2. US Government call for comments on repository requirements
  3. ADC API issues discussion
  4. AIRR Data Commons (ADC) API Paper
  5. On the horizon...

Agenda for 2020.01.16

Discusion Topics

  1. Bookkeeping
  2. ADC API issues discussion
  3. AIRR Data Commons (ADC) API Paper
  4. On the horizon...

Agenda for 2019.12.19

Discusion Topics

  1. Bookkeeping
  2. Gene naming and gene fields
  3. API discussion
  4. AIRR Data Commons (ADC) API Paper
  5. On the horizon...

Agenda for 2019.11.07

Discusion Topics

  1. Bookkeeping

  2. API discussion

  3. AIRR Data Commons (ADC) API Paper

  4. On the horizon...

Agenda for 2019.10.24

Discusion Topics

  1. Bookkeeping

  2. API discussion

  3. AIRR Data Commons (ADC) API Paper

    • Paper has been ratified by AIRR Community
    • Next steps?

  4. On the horizon...

Agenda for 2019.10.10

Discusion Topics

  1. Bookkeeping

  2. Meeting for AIRR Exec meeting

    • Presented status at Exec meeting

  3. API discussion

  4. AIRR Data Commons (ADC) API Paper

    • Paper has been ratified by AIRR Community
    • Next steps?

Agenda for 2019.08.15

Discussion Topics

  1. Bookkeeping

    • None

  2. API Discussion

  3. AIRR Data Commons (ADC) API Paper

    • Updates/Discussion

  4. Ongoing topics (not on the agenda for discussion):

Agenda for 2019.08.01

Discussion Topics

  1. Bookkeeping

    • None

  2. API Discussion

    • Updates

  3. AIRR Data Commons (ADC) API Paper

    • Authorship discussion
    • Take vote on approval of paper, record vote in minutes
    • Take vote on approval to send paper to AIRR Exec and then AIRR-C for endorsement, record vote in minutes
    • Discussion points
      • Publishing time line
        • Maturity of the implementation in the paper
      • Limited rearrangement query fields
        • See discussion around 2018.04 in this document
        • Consenus on approach
        • Do we have the right fields (Table in paper)

  4. Ongoing topics (not on the agenda for discussion):

Agenda for 2019.07.18

Discussion Topics

  1. Bookkeeping

    • None

  2. API discussion

  3. AIRR Data Commons (ADC) API Paper

    • Authorship discussion
    • Next steps for writing?

  4. Ongoing topics (not on the agenda for discussion):

Agenda for 2019.07.04

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Recommendations

    • Merge of revisions branch to master done, v0.6.0
    • Take this off of the agenda?

  3. API discussion

  4. AIRR Data Commons (ADC) API Paper

    • Authorship discussion
    • Writing approach
    • Should the paper take into account and discuss data privacy and data sharing (in particular GDPR related issues)

  5. AIRR Data Commons Registry

    • Discussion?
    • Issues

  6. Ongoing topics (not on the agenda for discussion):

Agenda for 2019.06.20

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Recommendations

    • Recommendataions were ratified
    • Need to merge in revisions on branch to master

  3. API discussion

  4. AIRR CRWG API Paper

  5. AIRR Data Commons Registry

  6. Ongoing topics (not on the agenda for discussion):

Agenda for 2019.06.06

Discussion Topics

  1. Book keeping

    • New member introductions

  2. AIRR Community Meeting

    • Meeting updates from attendees
    • Panel update from attendees

  3. AIRR Recommendations

  4. API discussion

  5. Metadata structure discussion

  6. New Working Group on meta-analysis

    • Report on discussions at AIRR Meeting Genoa.

  7. Ongoing topics (not on the agenda for discussion):

Agenda for 2019.04.11

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Plans for the Sunday panel
    • Plans for our working session Saturday morning
    • Plans for the presentation Sunday

  3. AIRR Recommendations

  4. API discussion

  5. Documentation

  6. Metadata structure discussion

    • Proposed that this JSON structure is what the API returns
      • See Scott's documentation above
    • Review and discuss
    • ramification of the "not 1-to-n" relation betwen sample and repertoire on MiAIRR and NCBI compatibility.
    • Link between an entity in the rearrangements API response (repertoire_id, rearrangement_set_id/software_processing_id) and the repertoire API reponse.

  7. New Working Group on meta-analysis

    • Proposal from MiniStd (see EMail)
    • Any other discussion?

  8. Ongoing topics (not on the agenda for discussion):

Agenda for 2019.03.28

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Plans for the Sunday panel
    • Plans for our working session Saturday morning
    • Plans for the presentation Sunday

  3. AIRR Recommendations

  4. Documentation

  5. Metadata structure discussion

    • Proposed that this JSON structure is what the API returns
      • See Scott's documentation above
    • Review and discuss
    • ramification of the "not 1-to-n" relation betwen sample and repertoire on MiAIRR and NCBI compatibility.
    • Link between an entity in the rearrangements API response (repertoire_id, rearrangement_set_id/software_processing_id) and the repertoire API reponse.

  6. New Working Group on meta-analysis

    • Proposal from MiniStd (see EMail)
    • Any other discussion?

  7. Ongoing topics (not on the agenda for discussion):

Agenda for 2019.03.14

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Panel invitations update
      • Four confirmed, but only one person has registered for the meeting
    • CRWG page on web site
      • Request to make change made...

  3. AIRR Recommendations

  4. Metadata structure discussion

    • Review and discuss
    • ramification of the "not 1-to-n" relation betwen sample and repertoire on MiAIRR and NCBI compatibility.
    • issue around not having 1-1 relationship between a rearrangement_set_id and a sample through the repertoire object.

  5. New Working Group on meta-analysis

    • Proposal from MiniStd (see EMail)

  6. Ongoing topics:

Agenda for 2019.02.28

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Panel invitations update
    • Comms committee has asked us to look at web site (in prep for May Meeting)
      • Our goals are listed for 2018 (as of the 2017 December meeting)
      • Should we simply change this to current goals?
      • Do we need any other changes?

  3. AIRR Recommendations

  4. Metadata structure discussion

  5. API discussion

  6. Data Provenence (Changelogs for repositories)

  7. Ongoing topics:

    • AIRR CRWG API Paper
    • AIRR Data Commons Registry
    • Ontologies

Agenda for 2019.02.14

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Panel invitations update
    • Comms committee has asked us to look at web site (in prep for May Meeting)
      • Our goals are listed for 2018 (as of the 2017 December meeting)
      • Should we simply change this to current goals?
      • Do we need any other changes?

  3. AIRR Recommendations

  4. API discussion

  5. Ontologies

  6. Data Provenence (Changelogs for repositories)

  7. AIRR Data Commons Registry

  8. AIRR CRWG API Paper

Agenda for 2019.01.31

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Panel invitations update
      • PIRD and OAS have accepted
      • Other candidates?
      • Organizing committee has asked us to nominate a chair for the panel discussion

  3. Ontologies

  4. API discussion

  5. Data Provenence (Changelogs for repositories)

  6. AIRR Data Commons Registry

  7. AIRR CRWG API Paper

  8. Priorities for next 4 months (May meeting)

    • AIRR API
    • AIRR Ontologies
    • Future of CRWG after May meeting
    • Article/paper submission

Agenda for 2019.01.03

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Panel invitations update
      • PIRD and OAS have accepted

  3. Ontologies

  4. API discussion

  5. Data Provenence (Changelogs for repositories)

  6. AIRR Data Commons Registry

Agenda for 2018.12.20

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Panel invitations update
      • PIRD and OAS have accepted

  3. Ontologies

    • Scott's comments (see email)
    • Issues
    • Discussion
      • Confirm a design for representing ontologies in the API
      • How and what do we tackle for a test implementation?

  4. API discussion

  5. Data Provenence (Changelogs for repositories)

  6. AIRR Data Commons Registry

Agenda for 2018.12.06

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Panel invitations update

  3. Ontologies

    • AIRR Vocabulary/Ontology sub-working group report
    • Scott's comments (see email)
    • Issues
    • Discussion

  4. API discussion

  5. Data Provenence (Changelogs for repositories)

  6. AIRR Data Commons Registry

Agenda for 2018.11.20

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Currently two reporting and panel sessions
    • Discussion - see notes
    • What do we want
      • Focus of the panel?
      • How many people?
      • Who?
    • Repository updates
      • OAS: may be attending, have asked if interested in panel
      • PIRD: Responded to Felix around visit, will be attending, probably willing to discuss on panel.

  3. Ontologies

    • AIRR Vocabulary/Ontology sub-working group
      • Meetings have occurred on a regular basis, progress being made
      • Will fall on us (and Data Rep) to implement

  4. API discussion

Agenda for 2018.10.25

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Currently two reporting and panel sessions
    • Repository updates
      • OAS: may be attending, have asked if interested in panel
      • PIRD: Responded to Felix around visit, will be attending, probably willing to discuss on panel.

  3. Ontologies

  4. API discussion

  5. CRWG publication planning

    • Where, when, what?

  6. Outstanding issues:

    • Repertoire and Rearrangement definitions
      • See: Github issue #17
      • Relate to Minimal Standards and Data Representation working group outcomes?
    • AIRR Repository registry
      • See: Github issue #18

  7. Repository lists

Agenda for 2018.10.11

Discussion Topics

  1. Book keeping

    • None

  2. AIRR Community Meeting

    • Currently two reporting and panel sessions
    • CRWG, MiniStd, Biological Reagents scheduled together - report and panel
      • Should we suggest CRWG, MiniStd, DataRep together as more logically linked
      • Check with Encarnita and Uri/Scott if agreeable?
    • Repository updates
      • OAS: may be attending, have asked if interested in panel
      • PIRD: Responded to Felix around visit, will be attending, probably willing to discuss on panel.

  3. Ontologies

  4. Repository lists

  5. API discussion

  6. CRWG publication planning

    • Where, when, what?

  7. Outstanding issues:

    • Repertoire and Rearrangement definitions
      • See: Github issue #17
      • Relate to Minimal Standards and Data Representation working group outcomes?
    • AIRR Repository registry
      • See: Github issue #18

Agenda for 2018.09.26

Discussion Topics

  1. Book keeping

    • Change of Co-Chair

  2. Use of the term "AIRR Data Commons"

    • See: GitHub issue #19
    • Issue has been closed

  3. AIRR Community Meeting - Updates Corey?

    • Asked to prepare a panel for discussion around repositories and standards
    • Possible repositories:
      • AIRR internal: iReceptor, VDJServer, ImmuneDB, SciReptor, VDJdb, ...
      • AIRR external: OAS, PIRD, ...
    • Actions for interacting with external repositories
      • PIRD is using its own standards, how do we reach out to help them see the light 8-)
      • Need to coordinate contact with them (other WG have this on their agenda)

  4. Repository lists

  5. API demonstratoin/discussion

    • Scott to demonstrate his recent work on the API.

  6. Ontologies

    • See: Github issues:
    • General discussion
      • Update on API and MiAIRR Work
      • Brian meeting with Christian Friday to discuss
      • How to represent them in the API (see above issues)
        • In terms of API queries
        • In terms of API responses
    • More complex examples that are useful to help us with representation
      • Cell subset
      • Strain
      • Ethnicity
      • Tissue type
      • Disease state/donor status

  7. Outstanding issues:

    • Repertoire and Rearrangement definitions
      • See: Github issue #17
      • Relate to Minimal Standards and Data Representation working group outcomes?
    • AIRR Repository registry
      • See: Github issue #18

Agenda for 2018.09.13

Discussion Topics

  1. Chair person discussion

    • Corey stepping down
    • Brian has volunteered
    • Discussion

  2. Use of the term "AIRR Data Commons" - Brian

    • See: GitHub issue #19
    • Exec has been informed, no objections at this time
    • Expected to approve this and all other changes at next AIRR Meeting

Agenda for 2018.08.30

Discussion Topics

  1. Book keeping

    • Decisions document created

  2. Use of the term "AIRR Data Commons" - Brian

  3. AIRR Community Meeting

    • Asked to prepare a panel for discussion around repositories and standards
      • Volunteers to coordinate this?
    • Possible repositories:
      • AIRR internal: iReceptor, VDJServer, ImmuneDB, SciReptor, VDJdb, ...
      • AIRR external: OAS, PIRD, ...
    • Actions for interacting with external repositories
      • PIRD is using its own standards, how do we reach out to help them see the light 8-)
      • Need to coordinate contact with them (other WG have this on their agenda)

  4. Ontologies

    • See: Github issues:
    • General discussion
      • How to represent them in the API (see above issues)
        • In terms of API queries
        • In terms of API responses
    • Low hanging fruit
      • Species: further discussion?
    • More complex examples that are useful to help us with representation
      • Cell subset
      • Strain
      • Ethnicity
      • Tissue type
      • Disease state/donor status

  5. Outstanding issues:

    • Repertoire and Rearrangement definitions
      • See: Github issue #17
      • Relate to Minimal Standards and Data Representation working group outcomes?
    • Repository lists
      • See: Github issue #20
      • Create a list of repositories on TCR site
      • Eventually have a section for AIRR compliant repositories
    • AIRR Repository registry
      • See: Github issue #18

Agenda for 2018.08.16

Discussion Topics

  1. Book keeping

    • Brian: Would like to move the decision part of minutes into a separate decision document. Any objections?
    • Minutes document is really and agenda document, should we rename?

  2. Use of the term "AIRR Data Commons" - Brian

  3. Ontologies - Lindsay

    • See: Github issue #21
    • Minimal standards update - Lindsay/Brian/Christian
    • Low hanging fruit
      • Species: further discussion?
    • More complex examples that are useful to help us with representation
      • Cell subset
      • Strain
    • General discussion
      • How to represent them in the API
        • In terms of API queries
        • In terms of API responses

  4. API Discussion - Brian/Scott

    • Repertoire and Rearrangement definitions
      • See: Github issue #17
      • Relate to Minimal Standards and Data Representation working group outcomes?
    • Repository lists
      • See: Github issue #20
      • Create a list of repositories on TCR site
      • Eventually have a section for AIRR compliant repositories
    • AIRR Repository registry
      • See: Github issue #18

Agenda for 2018.08.02

Discussion Topics

  1. Use of the term "AIRR Data Commons" - Brian

  2. API Discussion - Brian/Scott

    • Transition of iReceptor compliant repositories to AIRR compliant repositories
    • Repertoire and Rearrangement definitions
      • See: Github issue #17
      • Relate to Minimal Standards and Data Representation working group outcomes?
    • Repository lists
      • Create a list of repositories on TCR site (or on docs site)
        • Comprehensive list of AIRR related repositories
      • Eventually have a section for AIRR compliant repositories
    • Repository performance
      • Can we suggest performance levels?
        • Where performance is required to accomplish use cases
      • Can we report?
        • Should we add a performance metric (optional?) to the /info API entry point?
      • Or do we just let the repositories do what they do?

  3. Ontologies

    • How to define them?
    • How does the API use them?
      • Are ontology terms required for API requests?
      • Are ontology terms required for API responses?
      • Is an ontology term acceptable (e.g. Homo sapiens) or is a taxonomy ID required (e.g. 9606)

Agenda for 2018.07.19

Discussion Topics

  1. Use of the term "AIRR Data Commons" - Brian

    • See: GitHub issue #19
    • Definition discussion - critical points
      • AIRR Data Commons is a distributed data commons.

  2. API Discussion - Brian/Scott

    • Transition of iReceptor compliant repositories to AIRR compliant repositories
    • Repertoire and Rearrangement definitions
      • See: Github issue #17
      • Relate to Minimal Standards and Data Representation working group outcomes?
    • Asynchronous API
    • Registry

  3. Tool integration with AIRR Repostiroies

    • how to avoid the intermediate download step for large query results

  4. Ontologies

    • How do we want to tackle this?

Agenda for 2018.06.06

Discussion Topics

  1. 2019 AIRR Community Agenda

    • Discussed at length - feedback provided to AIRR Meeting organizing committee (see email to mailing list).

  2. Use of the term "AIRR Data Commons" See: GitHub issue #19

    • Discussed briefly, agreement in general that this was a good idea
    • Need to ensure that the term is well defined, in particular that the AIRR Data Commons is a distributed data commons.
    • Tabled for further discussion at the next meeting.

Agenda for 2018.05.10

In previous call, we discussed and agreed on the following:

  1. We discussed an asynchronous query mode interface. Whether it should be a single entrypoint that handles both synchronous and asynchronous queries, or separate entry points. The consensus was that separate entry points was a simpler design. We still need to work out details of the interface.

  2. We discussed the difference between query fields and returned fields. A discovery interface could inform the client what fields may be queried upon. We can define a core set of fields that all repositories must support query upon, but a specific repository might allow additional.

Discussion Topics

  1. Do we need to define a discovery interface? Does providing the OpenAPI spec have all the information that is needed?

  2. Asynchronous query mode interface. We need to hash out details of the interface.

Action Items

  1. Define DataMed submission standard. What will be the query to return the list of AIRR repositories?

  2. Continue developing API specification.

  • Define an asynchronous query mode interface.
  • Define a “discovery” interface
  • Continue work on ontology specifications.
  • Review existing work such as IEDB and NIAID GSCID/BRC metadata.
  • Based on review of the above, recommend ontologies for key elements listed above.
  • How will these ontologies be integrated in an implementation (client interface, web service API)?
  • Specify fields for alternative analytical pipeline data.
  • Specify fields for INSDC accession numbers.
  1. Integrate CRWG recommendations, CRWG design documentation, and API documentation into the airr-standards documentation structure, and thus make available on https://docs.airr-community.org

Agenda for 2018.04.26

In previous call, we discussed and agreed on the following:

  1. Should queries be digital objects stored by the repository and given their own identifiers? This might solve some issues and enable some functionality.
  • We will not require that repositories store the query and give it a unique identifier.
  • However, we do see the desire for some repositories to support an asychronous query operation versus sychronous. We agreed that defining an asynchronous query mode would be useful but it places a larger burden (computational and infrastructure overhead) on the repository over a simple synchronous query mode. Therefore, we will not require repositories to support it.

Discussion Topics

  1. There is a difference between query fields and fields that are returned from a query. CWRG can define two sets, a large set of fields for return and a smaller set of fields for query. Repositories may support additional fields.
  • We need to define a “discovery” interface for retrieving the set of fields that can be queried upon.
  1. Asynchronous query mode interface. Should it be a separate entrypoint(s) or a parameter to the same entrypoint? I think the interaction flow between client/server is different enough between synchronous and asynchronous that it’s better to have separate entrypoint(s).

Action Items

  1. Define DataMed submission standard. What will be the query to return the list of AIRR repositories?

  2. Continue developing API specification.

  • Define an asynchronous query mode interface.
  • Define a “discovery” interface
  • Continue work on ontology specifications.
  • Review existing work such as IEDB and NIAID GSCID/BRC metadata.
  • Based on review of the above, recommend ontologies for key elements listed above.
  • How will these ontologies be integrated in an implementation (client interface, web service API)?
  • Specify fields for alternative analytical pipeline data.
  • Specify fields for INSDC accession numbers.
  1. Integrate CRWG recommendations, CRWG design documentation, and API documentation into the airr-standards documentation structure, and thus make available on https://docs.airr-community.org

Agenda for 2018.04.12

In previous call, we discussed and agreed on the following:

  1. Discussion about repertoire_id versus rearrangement_set_id. We agreed that we need the capabilities of 1) how the study design defines the repertoire and 2) allow user queries to define those repertoires differently (e.g. CD4 subset). The actual technical solution is still being considered.

  2. In a related issue, should queries be digital objects stored by the repository and given their own identifiers? This might solve some issues and enable some functionality:

  • By “storing query”, we mean storing the parameters and their values that make up the query request, not the resultant data returned from the query.
  • Expensive queries can be run asynchronously. Doing a query returns a query_id instead of the actual query results, and the user polls the service with the query_id to see when the data is available.
  • Queries with DOIs would allow those queries to be referenced in journal publications.
  • A challenge with query DOIs is whether it should always return the same data, or all data including new data that’s been added to the repository. Returning the same data implies some level of versioning on the data so that new data can be excluded.
  • We decided that requiring a query to return the same data was too heavy of a requirement on the repository.

Discussion Topics

  1. Show initial prototype of API
  • The service is up and running but doesn’t return data.

  1. There is a difference between query fields and fields that are returned from a query. CWRG can define two sets, a large set of fields for return and a smaller set of fields for query. Repositories may support additional fields.

  2. An initial set of query fields for /repertoire entrypoint. We should walk through MiAIRR fields to see if we want to add any more.

  • repertoire_id - as defined by study designer
  • rearrangement_set_id - to allow users to query for subsets of the repertoire; should this persist?
  • study.title
  • study.insdc_id
  • study.pub_ids
  • subject.organism
  • subject.sex
  • subject.age
  • subject.race
  • subject.strain
  • subject.study_group_description
  • subject.disease_diagnosis
  • subject.disease_stage
  • subject.immunogen
  • sample.insdc_id
  • sample.tissue
  • sample.anatomic_site
  • sample.disease_state_sample
  • sample.cell_subset
  • sample.cell_phenotype
  • sample.template_class
  • software.software_version
  • software.alternative_analysis
  • software.germline_database
  1. An initial set of query fields for /rearrangement entrypoint.
  • rearrangement_id
  • rearrangement_set_id
  • productive
  • locus
  • v_call
  • d_call
  • j_call
  • c_call
  • junction
  • junction_aa
  • duplicate_count
  • consensus_count
  1. Defining a larger set of fields for return but which cannot be queried might be useful for rearrangements.
  • Sequence
  • Alignment information
  • Region coordinates

Action Items

  1. Define DataMed submission standard. What will be the query to return the list of AIRR repositories?

  2. Continue developing API specification.

  • Continue work on ontology specifications.
  • Review existing work such as IEDB and NIAID GSCID/BRC metadata.
  • Based on review of the above, recommend ontologies for key elements listed above.
  • How will these ontologies be integrated in an implementation (client interface, web service API)?
  • Specify fields for alternative analytical pipeline data.
  • Specify fields for INSDC accession numbers.
  1. Integrate CRWG recommendations, CRWG design documentation, and API documentation into the airr-standards documentation structure, and thus make available on https://docs.airr-community.org

Agenda for 2018.03.15

In previous call, we discussed and agreed on the following:

  1. Should RDF be a return format?
  • RDF very expressive
  • Let each repo decide, and if one implements it and it proves to be useful, then we can move it into the standard

  1. An initial set of query fields for /repertoire and /rearrangement entrypoints.

  2. Discussion about repertoire_id versus rearrangement_set_id. We want to provide both capabilities of 1) how the study design defines the repertoire and 2) allow user queries to define those repertoires differently (e.g. CD4 subset), and at the same time avoid confusion about whether a specific data set is the whole repertoire or just a subset.

  • Say a user queries two subsets, productive and unproductive, from the same repertoire. If only have repertoire_id (which is identical for the two subsets), there is no identifier that keeps the two subsets “separate”. With rearrangement_set_id, each subset would get a different rearrangement_set_id and thus can be distinguished from each other.

Discussion Topics

  1. repertoire_id versus rearrangement_set_id
  • After some more thought, the key point is to have an identifier that distinguishes between different queried subsets of a repertoire. Maybe rearrangement_set_id is the wrong name, and query_id is better? Query_id indicates that a set of data are all part of the same query.
  • Should we require repositories to store their queries? Should they have DOIs?
  • There is precedent for this for provenance/reproducibility. Should we require an exact query to be retrieved given its DOI?
  • How to handle a query spanning the /repertoire and /rearrangement entrypoints. Should the same query_id be used? Do you pass the query_id returned by /repertoire into /rearrangement? They are fundamentally different queries though so one query_id represents two queries which is confusing.

  1. There is a difference between query fields and fields that are returned from a query. CWRG can define two sets, a large set of fields for return and a smaller set of fields for query. Repositories may support additional fields.

  2. An initial set of query fields for /repertoire entrypoint. We should walk through MiAIRR fields to see if we want to add any more.

  • repertoire_id - as defined by study designer
  • rearrangement_set_id - to allow users to query for subsets of the repertoire; should this persist?
  • study.title
  • study.insdc_id
  • study.pub_ids
  • subject.organism
  • subject.sex
  • subject.age
  • subject.race
  • subject.strain
  • subject.study_group_description
  • subject.disease_diagnosis
  • subject.disease_stage
  • subject.immunogen
  • sample.insdc_id
  • sample.tissue
  • sample.anatomic_site
  • sample.disease_state_sample
  • sample.cell_subset
  • sample.cell_phenotype
  • sample.template_class
  • software.software_version
  • software.alternative_analysis
  • software.germline_database
  1. An initial set of query fields for /rearrangement entrypoint.
  • rearrangement_id
  • rearrangement_set_id
  • productive
  • locus
  • v_call
  • d_call
  • j_call
  • c_call
  • junction
  • junction_aa
  • duplicate_count
  • consensus_count
  1. Defining a larger set of fields for return but which cannot be queried might be useful for rearrangements.
  • Sequence
  • Alignment information
  • Region coordinates

Action Items

  1. Define DataMed submission standard. What will be the query to return the list of AIRR repositories?

  2. Continue developing API specification.

  • Continue work on ontology specifications.
  • Review existing work such as IEDB and NIAID GSCID/BRC metadata.
  • Based on review of the above, recommend ontologies for key elements listed above.
  • How will these ontologies be integrated in an implementation (client interface, web service API)?
  • Specify fields for alternative analytical pipeline data.
  • Specify fields for INSDC accession numbers.
  1. Integrate CRWG recommendations, CRWG design documentation, and API documentation into the airr-standards documentation structure, and thus make available on https://docs.airr-community.org

Agenda for 2018.03.01

In previous call, we discussed and agreed on the following:

  1. We will not define a Registry API. Instead, we will utilize the DataMed (BioCaddie) discovery index. However, CRWG will define a submission standard for DataMed so that AIRR repositories can be easily retrieved.
https://datamed.org/index.php
  1. The same raw data may be processed through multiple analytical pipelines, (e.g., for comparative purposes) with results from all pipelines in the repository. How do we indicate this and coordinate what gets returned?
  • Conclusion: each repository will return only one as the default, but each repository will determine its own default. CRWG API will specify the fields that get returned to alert the user that there are alternatives.
  1. Will we coordinate repertoire and rearrangement IDs across repositories? If yes, how?
  • Conclusion: it’s challenging to enforce a globally unique ID, so CRWG API will require that INSDC accession numbers (e.g., Bioproject, Biosample, SRA) are provided so users can check for duplicates. If those accession numbers aren’t available for a specific study, the user will have to rely upon manually reviewing titles, publications, abstract, etc.

Discussion Topics

  1. Should RDF be a return format?
  • RDF very expressive
  • Perhaps we let each repo decide, and if one implements it and it proves to be useful, then we can move it into the standard
  1. An initial set of fields for /repertoire entrypoint. CWRG will define a minimal set that all repositories must support for query/return. Alternatively, CWRG can define two sets, a large set of fields for return and a smaller set of fields for query. Repositories may support additional fields. We should walk through MiAIRR fields to see if we want to add any more.
  • repertoire_id - as defined by study designer
  • rearrangement_set_id - to allow users to query for subsets of the repertoire; should this persist?
  • study.title
  • study.insdc_id
  • study.pub_ids
  • subject.organism
  • subject.sex
  • subject.age
  • subject.race
  • subject.strain
  • subject.study_group_description
  • subject.disease_diagnosis
  • subject.disease_stage
  • subject.immunogen
  • sample.insdc_id
  • sample.tissue
  • sample.anatomic_site
  • sample.disease_state_sample
  • sample.cell_subset
  • sample.cell_phenotype
  • sample.template_class
  • software.software_version
  • software.alternative_analysis
  • software.germline_database
  1. An initial set of fields for /rearrangement entrypoint. CWRG will define a minimal set that all repositories must support for query/return. Alternatively, CWRG can define two sets, a large set of fields for return and a smaller set of fields for query. Repositories may support additional fields.
  • rearrangement_id
  • rearrangement_set_id
  • productive
  • locus
  • v_call
  • d_call
  • j_call
  • c_call
  • junction
  • junction_aa
  • duplicate_count
  • consensus_count
  1. Defining a larger set of fields for return but which cannot be queried might be useful for rearrangements.
  • Sequence
  • Alignment information
  • Region coordinates

Action Items

  1. Define DataMed submission standard. What will be the query to return the list of AIRR repositories?

  2. Continue developing API specification.

  • Decide what “entities” we have, and which ones are “linked” through each endpoint?
  • Continue work on ontology specifications.
  • Review existing work such as IEDB and NIAID GSCID/BRC metadata.
  • Based on review of the above, recommend ontologies for key elements listed above.
  • How will these ontologies be integrated in an implementation (client interface, web service API)?
  • Specify fields for alternative analytical pipeline data.
  • Specify fields for INSDC accession numbers.
  1. Integrate CRWG recommendations, CRWG design documentation, and API documentation into the airr-standards documentation structure, and thus make available on https://docs.airr-community.org

Agenda for 2018.02.15

In previous calls, we agreed on the following:

  1. RESTful API, JSON, using the OpenAPI specification. Initial implementation in Github
https://github.com/airr-community/airr-standards/blob/CRWG-API/specs/common_repository_api.yaml
  1. Two primary endpoints (“gettable” objects with unique ids)
/repertoire

A “sample repertoire” with associated study metadata.

/rearrangement

A “rearrangement object” with associated annotations. A rearrangement object is associated with a sample repertoire by the repertoire’s unique id.

  1. We will build on the GDC API
https://docs.gdc.cancer.gov/API/Users_Guide/Search_and_Retrieval/

  • It has a well-defined and expressive query language

  • Clients can limit/request what data fields to be returned (versus all data being returned)

  • It has a “loose” data model, which just indicates which entities are “linked” through an endpoint and can thus be queried upon, without specifying how that link is implemented. For example, the “case” endpoint is linked to the “diagnosis” entity, so a query can be performed on diagnosis data by having “diagnosis.” as a prefix to the field name, such as “diagnosis.state”.

  • It has a “facets” parameter which requests a limited form of aggregation capability, specifically for driving summary graphics (pie charts, bar plots, etc.) on a web interface.

  • JSON and TSV formats for return data.

  • It has a “_mapping” endpoint which is a discovery mechanism which provides metadata about the API itself. We probably need to expand upon it.

  • We will specify relationships between entities in the API data model, but each repository can have a different backend data model, which they will need to map to the API data model.

  1. Key repeating elements to prioritize for computationally precise standardization
  • Donor species (e.g., homo sapiens) (subject)
  • Donor health status (e.g., diabetes) (subject, primary sample)
  • Tissue type (e.g. PBMC) (primary sample)
  • Cell subset (e.g. T-cell)
  • Sequence type (e.g., TRB) (also from primer selection - experimental protocol)
  • Gene usage (e.g., IGHV1-69)
  • CDR3 sequence ( e.g., “CASSYIKLN”)
  • Receptor specificity (e.g., HIV virus)

Open Questions

  1. The same raw data may be processed through multiple analytical pipelines, (e.g., for comparative purposes) with results from all pipelines in the repository. How do we indicate this and coordinate what gets returned?
  • Ignore this and return everything as if independent? No
  • Return only a single one, and indicate alternatives are available? If return only one, which one? Most recent, “official” repo one?
  • Give the user the choice up front to query all output or only a single output for each data set.
  • Conclusion: each repository will return only one as the default, but each repository will determine its own default. CRWG API will specify the fields that get returned to alert the user that there are alternatives.
  1. Will we coordinate repertoire and rearrangement IDs across repositories? If yes, how?
  • Won’t force repositories to interact to know about duplicates ahead of time, but will regard that relevant fields are well-defined and populated.
  • cBioPortal has a mechanism for doing this that may be worth investigating.
  • Use INSDC accession numbers (e.g., Bioproject, Biosample, SRA)
  • What about when don’t have those?
  • PubMed identifier
  • After that probably have to manually review titles, abstracts, etc
https://datamed.org/search.php?query=b+cell&searchtype=data
  1. Should the registry be part of the repository API, or a separate API?
  • Same: simpler case, a repository can easily have a default, return itself as a registry and return itself as a repository.
  • Separate: requires a separate web service to handle the registry API, which may be overkill for the simple functionality
  • Use DataMed (BioCaddie) to register
  • DATS for tagging
  1. Should RDF be a return format?

Next Steps

  1. Continue developing API specification.
  • Decide what “entities” we have, and which ones are “linked” through each endpoint?
  • Continue work on ontology specifications.
  • Review existing work such as IEDB and NIAID GSCID/BRC metadata.
  • Based on review of the above, recommend ontologies for key elements listed above.
  • How will these ontologies be integrated in an implementation (client interface, web service API)?
  1. Integrate CRWG recommendations, CRWG design documentation, and API documentation into the airr-standards documentation structure, and thus make available on https://docs.airr-community.org

Agenda for 2018.02.01

We condensed all of the discussions and comments from the brainstorming document.

Current Status

  1. RESTful API, JSON, using the OpenAPI specification. Initial implementation in Github
https://github.com/airr-community/airr-standards/blob/CRWG-API/specs/common_repository_api.yaml
  1. Two primary endpoints (“gettable” objects with unique ids)
/repertoire

A “sample repertoire” with associated study metadata.

/rearrangement

A “rearrangement object” with associated annotations. A rearrangement object is associated with a sample repertoire by the repertoire’s unique id.

  1. The GDC API looks to be a good specification to build upon
https://docs.gdc.cancer.gov/API/Users_Guide/Search_and_Retrieval/

  • It has a well-defined and expressive query language

  • Clients can limit/request what data fields to be returned (versus all data being returned)

  • It has a “loose” data model, which just indicates which entities are “linked” through an endpoint and can thus be queried upon, without specifying how that link is implemented. For example, the “case” endpoint is linked to the “diagnosis” entity, so a query can be performed on diagnosis data by having “diagnosis.” as a prefix to the field name, such as “diagnosis.state”.

  • It has a “facets” parameter which requests a limited form of aggregation capability, specifically for driving summary graphics (pie charts, bar plots, etc.) on a web interface.

  • JSON and TSV formats for return data.

  • It has a “_mapping” endpoint which is a discovery mechanism which provides metadata about the API itself. We probably need to expand upon it.

  1. Key repeating elements to prioritize for computationally precise standardization
  • Donor species (e.g., homo sapiens) (subject) ontology: NCBI taxonomy
  • Donor health status (e.g., diabetes) (subject, primary sample) ontology: Disease Ontology, others?
  • Tissue type (e.g. PBMC) (primary sample) ontology: Uberon, others?
  • Cell subset (e.g. T-cell) ontology: Cell Ontology, others?
  • Sequence type (e.g., TRB) (also from primer selection - experimental protocol) ontology: IMGT, OBI
  • Gene usage (e.g., IGHV1-69) ontology: IMGT, Sequence Ontology
  • CDR3 sequence ( e.g., “CASSYIKLN”) ontology: IMGT
  • Receptor specificity (e.g., HIV virus) ontology: IEDB

Open Questions

The API cannot be completely data model agnostic, but we don’t want to force a specific data model on the repository. The GDC API has a specification for how to do that. We still need to decide what “entities” we have, and which ones are “linked” through each endpoint? We also want to allow repositories to provide their own specialized entities. The discovery mechanism should provide the ability for the client to learn about them. Do we need to place any requirements on this?

  • Analysis output (clones, lineage trees)
  • Raw data/sequences
  • Computation/Analysis workflow

The same raw data may be processed through multiple analytical pipelines, (e.g., for comparative purposes) with results from all pipelines in the repository, do we need to do anything special to indicate this situation?

GDC allows for simple wildcard (*) but do we want the more expressive regular expressions for CDR3 searches? Should that capability be mandatory or optional? Regular expression capability on other fields, like free text fields, as mandatory/optional?

Registry implementation. Should each repository be a registry as well? Should we define a separate API for a registry?

Action Items

  1. Continue developing API specification.

  2. Integrate CRWG recommendations, CRWG design documentation, and API documentation into the airr-standards documentation structure, and thus made available on https://docs.airr-community.org

  3. Continue work on ontology specifications.

  • Review existing work such as NIAID GSCID/BRC metadata.
  • Review what IEDB is using.
  • Based on review of the above, recommend ontologies for key elements listed above.
  • How will these ontologies be integrated in an implementation (client interface, web service API)?
  1. Who is going to implement the initial API spec and provide feedback to CRWG? How much of a “turnkey” system do/can we provide?