ODM-12846: gene summary analytics

openapi/v1/integrationCurator.yaml

@@ -7075,6 +7075,59 @@ paths:
       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
@@ -7430,6 +7483,10 @@ components:
       $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

@@ -5526,6 +5526,59 @@ paths:
       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
@@ -5649,6 +5702,10 @@ components:
       $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/GSRequest.yaml

@@ -0,0 +1,52 @@
+type: object
+properties:
+  cellGroup:
+    $ref: '#/components/schemas/CellGroupRequest'
+  geneNames:
+    type: array
+    items:
+      type: string
+    example:
+      - "ENSG00000230368"
+      - "ENSG00000188976"
+      - "ENSG00000188982"
+  exQuery:
+    type: string
+    example: '-3 < value < 3'
+required:
+  - geneNames
+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

openapi/v1/schemas/cell/GSResponse.yaml

@@ -0,0 +1,68 @@
+type: object
+properties:
+  resultsPerGene:
+    type: array
+    items:
+      $ref: '#/components/schemas/GeneSummaryEntry'
+components:
+  schemas:
+    GeneSummaryEntry:
+      type: object
+      description: Per-gene summary statistics.
+      properties:
+        geneId:
+          type: string
+          description: Gene identifier.
+          example: "ENSG00000111640"
+        cellCount:
+          type: integer
+          format: int32
+          description: Number of cells expressing the gene.
+          example: 8968167
+        mean:
+          type: number
+          format: double
+          description: Mean expression
+          example: 7.747614311820911
+        median:
+          type: number
+          format: double
+          description: Median expression
+          example: 7
+        stdDev:
+          type: number
+          format: double
+          description: Standard deviation
+          example: 6.499314669429827
+        min:
+          type: number
+          format: double
+          description: Minimum value
+          example: 1
+        max:
+          type: number
+          format: double
+          description: Maximum value
+          example: 496
+        quantiles:
+          type: array
+          description: |
+            List of quantile values from 0 to 1 (inclusive), with step 0.1
+          example: |
+            [1, 1, 2, 3, 5, 7, 10, 12, 15, 27, 192]
+          items:
+            type: number
+            format: double
+        histogram:
+          type: array
+          description: |
+            Histogram as a list of [binStart, binEnd, count] triples.
+            Length depends of the selected sample size, maximum is 20.
+          example: |
+            [(1, 15.50289002318, 7686678.375), (15.50289002318, 35.49570418233824, 1229164),
+            (35.49570418233824, 56.93121325335453, 36531.25), (56.93121325335453, 77.21467372919479, 6910.625)]
+          items:
+            type: array
+            items:
+              type: number
+              format: double