Where would one annotate metadata with an adjuvant

[bcorrie]

In the case of an immunization study, where would be the right place to make note of any adjuvants used in a study? A question from a user looking for such information in the AIRR Data Commons. The only place I could see that would make sense would be in the field immunogen with the adjuvant listed as part of describing the immunogen???

Their suggestion was that maybe we would want to have such a field to encourage its curation while describing a study?

[bussec]

Arrrg! :pirate_flag: I am just realizing that the parent object of this field -- like intervention -- is in only called Diagnosis, which doesn't make much sense...

Anyhow: immunogen should only describe the antigen that the immune system is expected to react against. If this is mixed with an adjuvant, the latter is described as part of the intervention, i.e. as free text.

Nevertheless, I agree that there is a use case in which a research wants to see all studies using a certain adjuvant. So having a separate field would make sense. And as this seems to be a quite central use case for AIRR-seq studies, maybe we could solve it for good with a separate Immunization Object (instead of a quick fix within Diagnosis):

Immunization:
    discriminator: AIRR
    type: object
    required:
        - schedule
        - schedule_unit
        - procedure
    properties:
        schedule:
            type: array
            description: Immunization schedule, starting at timepoint 0.
            items:
                type: float
            title: Immunization schedule
            example:
                - 0
                - 7
                - 21
            x-airr:
                miairr: important
                nullable: true
                adc-query-support: true
                set: 1
                subset: diagnosis and intervention
                name: Immunization schedule
        schedule_unit:
            $ref: '#/Ontology'
            description: Unit of immunization schedule
            title: Unit of immunization schedule
            example:
                id: UO:0000033
                label: day
            x-airr:
                miairr: important
                nullable: true
                adc-query-support: true
                set: 1
                subset: diagnosis and intervention
                name: Immunization schedule unit
                format: ontology
                ontology:
                    draft: false
                    top_node:
                        id: UO:0000003
                        label: time unit
        procedure:
            type: array
            description: Information for immunization procedure at each scheduled time point
            items:
                $ref: '#/Procedure'
            x-airr:
                nullable: false
                adc-query-support: true    

Procedure:
    discriminator: AIRR
    type: object
    required:
        - immunogen
        - immunogen_amount
        - immunogen_amount_unit
        - adjuvant
        - adjuvant_amount
        - adjuvant_amount_unit
        - application_route
        - application_site
    properties:
        immunogen:
            type: string
            description: Immunogen that is expected to by recognized by the host
        immunogen_amount:
            type: float
        immunogen_amount_unit:
            $ref: '#/Ontology'
            description: Unit of immunogen amount
        adjuvant:
            type: string
            description: Adjuvant used for immunization
        adjuvant_amount:
            type: float
        adjuvant_amount_unit:
            $ref: '#/Ontology'
            description: Unit of adjuvant amount
        application_route:
            type: string
            description: Route of immunogen application
            example: Intra-muscular injection
        application_site:
            $ref: '#/Ontology'
            description: Anatomical site of application
            example:
                id: UBERON:0001476
                label: deltoid
            x-airr:
                miairr: important
                nullable: true
                adc-query-support: true
                set: 1
                subset: diagnosis and intervention
                name: Anatomical site of immunization
                format: ontology
                ontology:
                    draft: false
                    top_node:
                        id: UBERON:0000061
                        label: anatomical structure

[schristley]

@bussec Looks good. How might this be attached to Repertoire ?

[bussec]

@schristley If this is part of the Subject object, wouldn't it be included via the $ref: '#/Subject' statement?

[schristley]

@schristley If this is part of the Subject object, wouldn't it be included via the $ref: '#/Subject' statement?

Yes it would, I wasn't sure how it would be included in Subject though. I guess as as a separate object. Now that I'm thinking about it a little more, it might be good to re-structure so that schedule and procedure arrays don't need to "manually matched". I'm thinking a bit how Diagnosis is an array of objects, would be nice if Intervention was like that. How about this as a suggestion? So the array is pushed up to Subject.

Subject:
    [snip]
    properties:
        diagnosis:
            type: array
            description: Diagnosis information for subject
            items:
                $ref: '#/Diagnosis'
            x-airr:
                nullable: false
                adc-query-support: true
        intervention:
            type: array
            description: Intervention information for subject, starting at timepoint 0.
            items:
                $ref: '#/Intervention'
            x-airr:
                nullable: false
                adc-query-support: true

Immunization:
    discriminator: AIRR
    type: object
    required:
        - schedule
        - schedule_unit
        - procedure
    properties:
        schedule:
            type: float
            description: Immunization schedule
            title: Immunization schedule
            example:
                - 0
                - 7
                - 21
            x-airr:
                miairr: important
                nullable: true
                adc-query-support: true
                set: 1
                subset: diagnosis and intervention
                name: Immunization schedule
        schedule_unit:
            $ref: '#/Ontology'
            description: Unit of immunization schedule
            title: Unit of immunization schedule
            example:
                id: UO:0000033
                label: day
            x-airr:
                miairr: important
                nullable: true
                adc-query-support: true
                set: 1
                subset: diagnosis and intervention
                name: Immunization schedule unit
                format: ontology
                ontology:
                    draft: false
                    top_node:
                        id: UO:0000003
                        label: time unit
        procedure:
                $ref: '#/Procedure'

Procedure:
    discriminator: AIRR
    type: object
    required:
        - immunogen
        - immunogen_amount
        - immunogen_amount_unit
        - adjuvant
        - adjuvant_amount
        - adjuvant_amount_unit
        - application_route
        - application_site
    properties:
        immunogen:
            type: string
            description: Immunogen that is expected to by recognized by the host
        immunogen_amount:
            type: float
        immunogen_amount_unit:
            $ref: '#/Ontology'
            description: Unit of immunogen amount
        adjuvant:
            type: string
            description: Adjuvant used for immunization
        adjuvant_amount:
            type: float
        adjuvant_amount_unit:
            $ref: '#/Ontology'
            description: Unit of adjuvant amount
        application_route:
            type: string
            description: Route of immunogen application
            example: Intra-muscular injection
        application_site:
            $ref: '#/Ontology'
            description: Anatomical site of application
            example:
                id: UBERON:0001476
                label: deltoid
            x-airr:
                miairr: important
                nullable: true
                adc-query-support: true
                set: 1
                subset: diagnosis and intervention
                name: Anatomical site of immunization
                format: ontology
                ontology:
                    draft: false
                    top_node:
                        id: UBERON:0000061
                        label: anatomical structure

Also, one might expect that repertoires are captured at the various timepoints in the schedule? How should we form that link? I guess we might add an identifer for the schedule timepoint then have a field in SampleProcessing that points to it?

[scharch]

Is this still something we want to add?

[bussec]

Given how common immunization schemes are, I still think that it would be worthwhile adding it. But if we restructure the Intervention, this would clearly be a v2.0 change. Also: @bcorrie would this actually solve your original use case (which reads like you suggest moving this to Study instead of Subject)?

[bcorrie]

Related to #749 I believe this is looking like it will end out of scope for v2.0