ODM-12846: gene summary analytics

build.gradle.kts

@@ -60,7 +60,9 @@ tasks {
             // Workaround for https://github.com/OpenAPITools/openapi-generator/issues/21619
             // The second version asks for license, which we can't provide due to unavailability of
             // "licenseName" and "licenseUrl" fields in the specification for python generator.
-            "poetry1" to "true"
+            "poetry1" to "true",
+            // All float fields accept "NaN", "Infinity", "-Infinity" values
+            "mapNumberTo" to "float"
 //            "disallowAdditionalPropertiesIfNotPresent" to "true"
         )
     }

openapi/v1/integrationCurator.yaml

@@ -7021,6 +7021,112 @@ paths:
       summary: Stream data from a given VCF file
       tags:
         - Omics queries as Curator
+  /api/v1/as-curator/omics/cells/analytics/differential-expression:
+    post:
+      operationId: differentialExpressionAsCurator
+      summary: "[BETA] Perform differential gene expression analytics between case and control cell groups"
+      tags:
+        - "[BETA] Analytics omics queries as Curator"
+      # The descriptions below are also duplicated in the schema description, make sure to keep them in sync.
+      description: |+
+        This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data.
+
+        Consult `/omics` search endpoints to find description of parameters within the cell groups.
+        The response includes per-gene metrics that characterize expression differences between the two groups:
+        - `Gene name` - gene identifier.
+        - `Case cell count` - number of cells expressing the gene in the case group.
+        - `Control cell count` - number of cells expressing the gene in the control group.
+        - `Average expression (case)` - mean expression level across case cells.
+        - `Average expression (control)` - mean expression level across control cells.
+        - `Expression difference` - numerical difference between average expressions.
+        - `Fold change` - ratio of average expressions between case and control groups.
+        - `U statistic` - Mann–Whitney U test statistic that measures the difference between Case and Control groups.
+        - `p-value` - the probability of observing results as extreme as (or more extreme than) those obtained, assuming that the null hypothesis is true.
+        Results are sorted by absolute value of fold change in descending order, allowing easy identification of the most differentially expressed genes.
+
+        Request and response parameters are subject to change as this feature is in BETA.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DERequest"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DEResponse"
+          description: Differential expression result
+        "400":
+          content: { }
+          description: Entities cannot be retrieved.
+        "401":
+          content: { }
+          description: |-
+            User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token])
+             or  Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page).
+        "500":
+          content: { }
+          description: "An internal server error occurred. This indicates an unexpected\
+            \ failure in the Genestack system, please file a bug report to support@genestack.com,\
+            \ including the error details."
+      security:
+        - Access-token: [ ]
+        - Genestack-API-Token: [ ]
+  /api/v1/as-curator/omics/cells/analytics/gene-summary:
+    post:
+      operationId: geneSummaryAsCurator
+      summary: "[BETA] Compute and retrieve descriptive statistics and visual summaries for single-cell data."
+      tags:
+        - "[BETA] Analytics omics queries as Curator"
+      description: |+
+        This endpoint provides descriptive statistical metrics for gene expression across single-cell datasets.
+        It aggregates and summarizes expression data for each gene to help assess variability, distribution,
+        and intensity of expression within the population of cells.
+
+        The computed metrics include:
+          - `Gene name` - gene identifier.
+          - `Cell count` - number of cells with measurable expression for each gene.
+          - `Mean expression value`
+          - `Median expression value`
+          - `Quantiles` - configurable expression percentiles.
+          - `Histogram (density)` - binned distribution of expression levels for visualization.
+          - `Standard deviation` - dispersion of expression values.
+          - `Minimum and maximum values` - range of expression across cells.
+
+        Results are sorted by gene name.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GSRequest"
+      responses:
+        "200":
+          description: Gene summary result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GSResponse"
+        "400":
+          content: { }
+          description: Invalid data in the request. See the error message for details.
+        "401":
+          content: { }
+          description: |+
+            User is not authenticated. Please supply a valid Access Token in the `Authorization`
+            HTTP header (e.g. Authorization: bearer [token]) or  Genestack API token in the `Genestack-API-Token`
+            header (this token may be obtained from the Genestack UI _Profile_ page).
+        "500":
+          content: { }
+          description: |+
+            An internal server error occurred. This indicates an unexpected
+            failure in the Genestack system, please file a bug report to support@genestack.com,
+            including the error details."
+      security:
+        - Access-token: [ ]
+        - Genestack-API-Token: [ ]
   /api/v1/as-curator/integration/studies/{id}/tasks/publish-versions:
     post:
       description: This endpoint publishes information from staging and creates new
@@ -7372,6 +7478,14 @@ components:
       $ref: "./schemas/integration/FilterOption.yaml"
     AFile:
       $ref: "./schemas/afile/AFile.yaml"
+    DERequest:
+      $ref: "./schemas/cell/DERequest.yaml"
+    DEResponse:
+      $ref: "./schemas/cell/DEResponse.yaml"
+    GSRequest:
+      $ref: "./schemas/cell/GSRequest.yaml"
+    GSResponse:
+      $ref: "./schemas/cell/GSResponse.yaml"
   securitySchemes:
     Access-token:
       in: header

openapi/v1/integrationUser.yaml

@@ -5472,6 +5472,112 @@ paths:
       summary: Stream data from a given VCF file
       tags:
         - Omics queries as User
+  /api/v1/as-user/omics/cells/analytics/differential-expression:
+    post:
+      operationId: differentialExpressionAsUser
+      summary: "[BETA] Perform differential gene expression analytics between case and control cell groups"
+      tags:
+        - "[BETA] Analytics omics queries as User"
+      # The descriptions below are also duplicated in the schema description, make sure to keep them in sync.
+      description: |+
+        This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data.
+
+        Consult `/omics` search endpoints to find description of parameters within the cell groups.
+        The response includes per-gene metrics that characterize expression differences between the two groups:
+        - `Gene name` - gene identifier.
+        - `Case cell count` - number of cells expressing the gene in the case group.
+        - `Control cell count` - number of cells expressing the gene in the control group.
+        - `Average expression (case)` - mean expression level across case cells.
+        - `Average expression (control)` - mean expression level across control cells.
+        - `Expression difference` - numerical difference between average expressions.
+        - `Fold change` - ratio of average expressions between case and control groups.
+        - `U statistic` - Mann–Whitney U test statistic that measures the difference between Case and Control groups.
+        - `p-value` - the probability of observing results as extreme as (or more extreme than) those obtained, assuming that the null hypothesis is true.
+        Results are sorted by absolute value of fold change in descending order, allowing easy identification of the most differentially expressed genes.
+
+        Request and response parameters are subject to change as this feature is in BETA.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DERequest"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DEResponse"
+          description: Differential expression result
+        "400":
+          content: { }
+          description: Entities cannot be retrieved.
+        "401":
+          content: { }
+          description: |-
+            User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token])
+             or  Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page).
+        "500":
+          content: { }
+          description: "An internal server error occurred. This indicates an unexpected\
+            \ failure in the Genestack system, please file a bug report to support@genestack.com,\
+            \ including the error details."
+      security:
+        - Access-token: [ ]
+        - Genestack-API-Token: [ ]
+  /api/v1/as-user/omics/cells/analytics/gene-summary:
+    post:
+      operationId: geneSummaryAsUser
+      summary: "[BETA] Compute and retrieve descriptive statistics and visual summaries for single-cell data."
+      tags:
+        - "[BETA] Analytics omics queries as User"
+      description: |+
+        This endpoint provides descriptive statistical metrics for gene expression across single-cell datasets.
+        It aggregates and summarizes expression data for each gene to help assess variability, distribution,
+        and intensity of expression within the population of cells.
+
+        The computed metrics include:
+          - `Gene name` - gene identifier.
+          - `Cell count` - number of cells with measurable expression for each gene.
+          - `Mean expression value`
+          - `Median expression value`
+          - `Quantiles` - configurable expression percentiles.
+          - `Histogram (density)` - binned distribution of expression levels for visualization.
+          - `Standard deviation` - dispersion of expression values.
+          - `Minimum and maximum values` - range of expression across cells.
+
+        Results are sorted by gene name.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GSRequest"
+      responses:
+        "200":
+          description: Gene summary result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GSResponse"
+        "400":
+          content: { }
+          description: Invalid data in the request. See the error message for details.
+        "401":
+          content: { }
+          description: |+
+            User is not authenticated. Please supply a valid Access Token in the `Authorization`
+            HTTP header (e.g. Authorization: bearer [token]) or  Genestack API token in the `Genestack-API-Token`
+            header (this token may be obtained from the Genestack UI _Profile_ page).
+        "500":
+          content: { }
+          description: |+
+            An internal server error occurred. This indicates an unexpected
+            failure in the Genestack system, please file a bug report to support@genestack.com,
+            including the error details."
+      security:
+        - Access-token: [ ]
+        - Genestack-API-Token: [ ]
   /api/v1/as-user/integration/link/files/by/study/{id}:
     get:
       operationId: getFilesByStudyAsUser
@@ -5591,6 +5697,14 @@ components:
       $ref: "./schemas/integration/FilterOption.yaml"
     AFile:
       $ref: "./schemas/afile/AFile.yaml"
+    DERequest:
+      $ref: "./schemas/cell/DERequest.yaml"
+    DEResponse:
+      $ref: "./schemas/cell/DEResponse.yaml"
+    GSRequest:
+      $ref: "./schemas/cell/GSRequest.yaml"
+    GSResponse:
+      $ref: "./schemas/cell/GSResponse.yaml"
   securitySchemes:
     Access-token:
       in: header

openapi/v1/schemas/cell/DERequest.yaml

@@ -0,0 +1,57 @@
+type: object
+properties:
+  caseGroup:
+    $ref: '#/components/schemas/CellGroupRequest'
+  controlGroup:
+    $ref: '#/components/schemas/CellGroupRequest'
+  exQuery:
+    type: string
+    example: 'feature=ENSG00000230368,ENSG00000188976'
+  limit:
+    type: integer
+    format: int32
+    description: This parameter determines the number of results to retrieve per page, with the default set at 2000.
+    example: 2000
+  offset:
+    type: integer
+    format: int32
+    description: This parameter allows skipping a specified number of results, with the default set at 0.
+    example: 0
+required:
+  - caseGroup
+  - controlGroup
+components:
+  schemas:
+    CellGroupRequest:
+      type: object
+      properties:
+        studyFilter:
+          type: string
+          example: '"Study Source"=ArrayExpress'
+        studyQuery:
+          type: string
+          example: 'RNA-Seq of human dendritic cells'
+        sampleFilter:
+          type: string
+          example: '"Species or strain"="Homo sapiens"'
+        sampleQuery:
+          type: string
+          example: 'Clozapine'
+        libraryFilter:
+          type: string
+          example: '"Library Type"=RNA-Seq-1'
+        libraryQuery:
+          type: string
+          example: 'illumina HiSeq500'
+        preparationFilter:
+          type: string
+          example: 'Digestion=Trypsin'
+        preparationQuery:
+          type: string
+          example: 'reversed-phase liquid chromatography'
+        cellQuery:
+          type: string
+          example: 'cellType=Macrophage,Monocyte'
+        searchSpecificTerms:
+          type: boolean
+          example: false