ODM-12847: Differential expression for cell analysis (#492)

* ODM-12847: cell analysis: diff expression

Author: m-smazhevsky

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,60 @@ 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/integration/studies/{id}/tasks/publish-versions:
     post:
       description: This endpoint publishes information from staging and creates new
@@ -7372,6 +7426,10 @@ components:
       $ref: "./schemas/integration/FilterOption.yaml"
     AFile:
       $ref: "./schemas/afile/AFile.yaml"
+    DERequest:
+      $ref: "./schemas/cell/DERequest.yaml"
+    DEResponse:
+      $ref: "./schemas/cell/DEResponse.yaml"
   securitySchemes:
     Access-token:
       in: header

openapi/v1/integrationUser.yaml

@@ -5472,6 +5472,60 @@ 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/integration/link/files/by/study/{id}:
     get:
       operationId: getFilesByStudyAsUser
@@ -5591,6 +5645,10 @@ components:
       $ref: "./schemas/integration/FilterOption.yaml"
     AFile:
       $ref: "./schemas/afile/AFile.yaml"
+    DERequest:
+      $ref: "./schemas/cell/DERequest.yaml"
+    DEResponse:
+      $ref: "./schemas/cell/DEResponse.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

openapi/v1/schemas/cell/DEResponse.yaml

@@ -0,0 +1,91 @@
+type: object
+properties:
+  resultsPerGene:
+    type: array
+    items:
+      $ref: '#/components/schemas/GeneEntry'
+  pagination:
+    $ref: '#/components/schemas/Pagination'
+required:
+  - resultsPerGene
+  - pagination
+components:
+  schemas:
+    GeneEntry:
+      type: object
+      # The descriptions below are also duplicated in the endpoint description, make sure to keep them in sync.
+      properties:
+        geneId:
+          type: string
+          description: Gene identifier.
+          example: ENSG00000230368
+        caseCellCount:
+          type: integer
+          description: Number of cells expressing the gene in the case group.
+          example: 8450
+        controlCellCount:
+          type: integer
+          description: Number of cells expressing the gene in the control group.
+          example: 8123
+        caseAvgExpression:
+          type: number
+          format: double
+          description: Mean expression level across case cells.
+          example: 1.24
+        controlAvgExpression:
+          type: number
+          format: double
+          description: Mean expression level across control cells.
+          example: 0.62
+        expressionDifference:
+          type: number
+          format: double
+          description: Numerical difference between average expressions.
+          example: 0.62
+        foldChange:
+          type: number
+          format: double
+          description: Ratio of average expressions between case and control groups.
+          example: 2.0
+        mannWhitneyU:
+          type: number
+          format: double
+          description: Mann–Whitney U test statistic that measures the difference between Case and Control groups.
+          example: 1.5
+        pValue:
+          type: number
+          format: double
+          description: The probability of observing results as extreme as (or more extreme than) those obtained, assuming that the null hypothesis is true.
+          example: 0.95
+      required:
+        - geneId
+        - caseCellCount
+        - controlCellCount
+        - caseAvgExpression
+        - controlAvgExpression
+        - expressionDifference
+        - foldChange
+        - mannWhitneyU
+        - pValue
+    Pagination:
+        type: object
+        properties:
+          currentResultsCount:
+            type: integer
+            format: int32
+            description: Number of results returned in the current response.
+            example: 1
+          limit:
+            type: integer
+            format: int32
+            description: Results limit, used in the request.
+            example: 2000
+          offset:
+            type: integer
+            format: int32
+            description: Results offset, used in the request.
+            example: 0
+        required:
+          - currentResultsCount
+          - limit
+          - offset