EGA.analysis.json

{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "$id": "https://raw.githubusercontent.com/EbiEga/ega-metadata-schema/main/schemas/EGA.analysis.json",
    "type": "object",
    "title": "EGA analysis metadata schema",
    "meta:version": "0.0.0",
    "$async": true,
    "description": "Metadata schema used by the European Genome-phenome Archive (EGA) to validate its analysis metadata object. This object is intended to contain metadata about a detailed examination of data (mainly data processing protocols) in order to come to some conclusion. It can be of different types (e.g. sequence variation, sequence alignment, phenotype characterization, gene expression, etc.) that will mainly differ in the protocols used to achieve the processed data of the analysis. Further details can be found in the EGA-metadata-schema GitHub repository (https://github.com/EbiEga/ega-metadata-schema/tree/main/schemas) and EGA-archive website (https://ega-archive.org/)",
    "required": ["objectId", "analysisTypeSpecifications" ],
    "additionalProperties": false,
    "properties": {
      "objectId": {
        "type": "object",
        "title": "Object's IDs block",
        "description": "Node containing the main identifiers of the object (e.g. alias, centerName...), inherited from the common definitions.", 
        "allOf": [
          {
            "title": "Inherited objectCoreId object",
            "$ref": "./EGA.common-definitions.json#/$defs/objectCoreId"
          },
          {
            "title": "Check that analysis EGA ID (EGAZ) is correct",
            "properties": {
              "egaAccession": {
                "$ref": "./EGA.common-definitions.json#/$defs/EGAAnalysisIdPattern"
              }
            }
          }
        ]
      },

      "schemaDescriptor": {
        "title": "Schema descriptor node",
        "description": "Inherited schema descriptor node containing metadata about the schemas and standards used to create the JSON document itself.",
        "$ref": "./EGA.common-definitions.json#/$defs/schemaDescriptor"
      },

      "objectTitle": {
        "type": "string",
        "title": "Title of the analysis",
        "description": "An informative analysis title that should serve as an overview of the analysis, including: performed analysis, samples, purpose... (e.g. 'Variant calling analysis of tumor repressed cells'). This short text can be used to call out analyses records in searches or in displays.",
        "minLength": 1,
        "examples": [ "Variant calling analysis of tumor repressed cells" ]
      },

      "objectDescription": {
        "type": "string",
        "title": "Description of the analysis",
        "description": "An in-depth description of the biological relevance and intent of the analysis, including its workflow.",
        "minLength": 1,
        "examples": [ "The analysis was conducted with the objective of... ...and for that purpose we compared untreated controls against..." ]
      },

      "targetedLoci": {
        "type": "array",
        "title": "Loci of the targeted genomic feature",
        "description": "Array of items that unambiguously define the loci of targeted genomic features in the analysis. For example, if the aim of the analysis was to detect variants in the human gene TAF1 and TP53, their identifiers will be expected in two items of this array.",
        "minItems": 1,
        "uniqueItems": true,
        "additionalProperties": false,
        "items": {
          "$ref": "./EGA.common-definitions.json#/$defs/locusIdentifier" 
        }
      },

      "typesOfInputData": {
        "type": "array",
        "title": "Types of input data",
        "description": "Types of input data the analysis uses to obtain the processed files.",
        "additionalProperties": false,
        "uniqueItems": true,
        "minItems": 1,
        "items": {
          "$ref": "./EGA.common-definitions.json#/$defs/typeOfData"
        }
      },

      "typesOfOutputData": {
        "type": "array",
        "title": "Types of output data",
        "description": "Types of output data the analysis uses to obtain the processed files.",
        "additionalProperties": false,
        "uniqueItems": true,
        "minItems": 1,
        "items": {
          "$ref": "./EGA.common-definitions.json#/$defs/typeOfData"
        }
      },

      "analysisTypeSpecifications": {
        "type": "object",
        "title": "Analysis type specifications",
        "description": "Node containing different sets of fields that depend on the specific analysis type. Depending on the analysis types different metadata will be required.",
        "additionalProperties": false,
        "required": ["analysisTypes"],
        "properties": {
          "analysisTypes": {
            "type": "array",
            "title": "List of analysis types",
            "description": "Array of all analysis types applicable to this analysis. Details on how the analysis was performed (instruments, software, procedure...) shall be included in the 'analysis_protocols' field, not here. For example, if the analysis includes sequence variation files (e.g. VCF) that were obtained by a sequencing assay (i.e. from the sequenced reads), at least the analysis type 'sequence variation' would be expected. Furthermore, depending on the types of analysis, different details may be required (e.g. reference sequence details in a 'sequence alignment' type).",
            "additionalProperties": false,
            "uniqueItems": true,
            "minItems": 1,
            "items": {
              "type": "string",
              "title": "Type of analysis",
              "description": "Overall type of the analysis. Term chosen from a controlled vocabulary (CV) list. If you cannot find your term in the CV list, please create an issue at our [metadata GitHub repository](https://github.com/EbiEga/ega-metadata-schema/issues/new/choose) proposing its addition.",
              "enum": [ "sequence variation", "sequence alignment", "phenotype characterization", "sequence annotation", "sequence assembly", "gene expression" ],
              "meta:enum": {
                "sequence variation": "sequence variation__ERO:0100211: Analysis of variations at specific loci in the genomes of organisms (mutation and polymorphism) across or within a species, population, or individual (e.g healthy vs diseased tissue).",
                "sequence alignment": "sequence alignment__ERO:0100032: objective to display graphically how the sequences of two or more macromolecules align along a linear axis.",
                "phenotype characterization": "phenotype characterization__ERO:0000923: The result of an organismal assay that involves characterization of a phenotype; any observable characteristic or trait of an organism: such as its morphology, development, biochemical or physiological properties, behavior, and products of behavior (such as a bird's nest). Phenotypes result from the expression of an organism's genes as well as the influence of environmental factors and the interactions between the two.",
                "sequence annotation": "sequence annotation__operation:0361: Analysis where molecular sequence records are annotated with terms from a controlled vocabulary. For submitting sequence annotation files, which are usually 'tab' files. Examples include gene count and OTU tables from metagenomic studies.",
                "sequence assembly": "sequence assembly__topic:0196: The assembly of fragments of a DNA sequence to reconstruct the original sequence.",
                "gene expression": "gene expression__topic:0203: The analysis of levels and patterns of synthesis of gene products (proteins and functional RNA) including interpretation in functional terms of gene expression data." 
              }
            }
          },
          "referenceAlignmentDetails": {
            "title": "Reference assembly and sequence details",
            "description": "Node containing details of the reference sequence used in the alignment of raw sequences.",
            "$ref": "./EGA.common-definitions.json#/$defs/referenceAlignmentDetails"
          }
        }
      },

      "analysisFiles": {
        "type": "array",
        "title": "Files of the analysis",
        "description": "This property contains the files derived from performing any processing or analysis over raw data (e.g. VCF, aligned BAM...) and those that add context to it (e.g. CSV, TXT...).",
        "minItems": 1,
        "additionalProperties": false,
        "uniqueItems": true,
        "items": { 
              "$ref": "./EGA.common-definitions.json#/$defs/fileObject"
        }
      },

      "analysisRelationships": {
        "type": "array",
        "title": "Analysis relationships",
        "description": "Comprises metadata (e.g. Source or Target) of a directional association between two entities. This relationships node contains all the possible relationships between metadata objects, both outside of (e.g. an Array Design Format that was submitted to ArrayExpress being linked to their microarray data within EGA) and within (e.g. an analysis being linked to a Sample) the EGA.",
        "minItems": 1,
        "uniqueItems": true,
        "additionalProperties": false,
        "items": {
          "allOf": [
            {
              "title": "Inherited relationship node",
              "$ref": "./EGA.common-definitions.json#/$defs/relationshipObject"
            },
            {
              "title": "Relationship constraints for an analysis",
              "description": "Not all possible relationships between objects are allowed (e.g. an individual should not be linked to a policy). This node contains the restricted relationships that can be given for a analysis.",
              "anyOf": [
                {
                  "title": "Allowed relationships of type referencedBy (main ones)",
                  "allOf": [
                    {
                      "$ref": "./EGA.common-definitions.json#/$defs/rTypeReferencedBy"
                    },
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceStudy"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceSample"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceExperiment"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceAssay"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetDataset"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceSubmission"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceProtocol"
                        },
                        {
                          "title": "Optional one, added here to simplify",
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetAnalysis"
                        }
                      ]
                    }
                  ]                  
                },
                {
                  "title": "Allowed relationships of type groupedWith, isAfter, sameAs (optional ones)",
                  "allOf": [
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeGroupedWith"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeIsAfter"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeSameAs"
                        }
                      ]
                    },
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceAnalysis"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetAnalysis"
                        }
                      ]
                    }
                  ]
                },
                {
                  "title": "Relationships of external accessions and URLs (optional ones)",
                  "description": "Almost any relationship is imaginable with external accessions and URLs.",
                  "allOf": [
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeChildOf"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeFamilyRelationshipWith"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeGroupedWith"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeSameAs"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeReferencedBy"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeDevelopsFrom"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeMemberOf"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeIsAfter"
                        }
                      ]
                    },
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceExternalAccession"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceExternalURL"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetExternalAccession"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetExternalURL"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ] 
        },
        "contains": {
          "title": "Constraint to have at least one 'submission' relationship",
          "$ref": "./EGA.common-definitions.json#/$defs/rConstraintOneSourcedSubmission"
        }
      },

      "analysisAttributes": {
        "type": "array",
        "title": "Analysis custom attributes",
        "description": "Custom attributes of an analysis: reusable attributes to encode tag-value pairs (e.g. Tag being 'internal tag' and its Value 'this analysis is corresponds to internal tag XYZ') with optional units. Its properties are inherited from the common-definitions.json schema.",
        "additionalProperties": false,
        "uniqueItems": true,
        "minItems": 1,
        "items": {
          "$ref": "./EGA.common-definitions.json#/$defs/customAttribute" 
        }
      }
    }      
  }