ODM-12845 Add cell ratio docs

openapi/v1/integrationCurator.yaml

@@ -7021,6 +7021,53 @@ paths:
       summary: Stream data from a given VCF file
       tags:
         - Omics queries as Curator
+  /api/v1/as-curator/omics/cells/analytics/cell-ratio:
+    post:
+      operationId: cellRatioAsCurator
+      summary: "[BETA] Compute cell ratio statistics across groups or metadata attributes in single-cell data."
+      tags:
+        - "[BETA] Analytics omics queries as Curator"
+      description: |+
+        This endpoint calculates cell ratio statistics based on single-cell metadata.
+
+        It allows quantifying the proportion of cells that meet specific criteria (`countSelected`, e.g. expression threshold, cell type, or cluster)
+        relative to a defined reference group or the total cell population (`countAvailable`) defined by study, samples, library, or preparation metadata.
+
+        `countAvailable` parameter returns all cells specified in study, sample, library, or preparation queries and filters.
+        In case `exQuery` is selected, only cells linked to cell expression will be counted in `countSelected` parameter.
+
+        The endpoint supports filtering by study, sample, library, or preparation metadata and filtering by cell expression or cell metadata fields.
+
+        Request and response parameters are subject to change as this feature is in BETA.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CRRequest"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CRResponse"
+          description: Cell ratio 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/differential-expression:
     post:
       operationId: differentialExpressionAsCurator
@@ -7097,6 +7144,8 @@ paths:
           - `Minimum and maximum values` - range of expression across cells.
 
         Results are sorted by gene name.
+
+        Request and response parameters are subject to change as this feature is in BETA.
       requestBody:
         required: true
         content:
@@ -7487,6 +7536,10 @@ components:
       $ref: "./schemas/cell/GSRequest.yaml"
     GSResponse:
       $ref: "./schemas/cell/GSResponse.yaml"
+    CRRequest:
+      $ref: "./schemas/cell/CRRequest.yaml"
+    CRResponse:
+      $ref: "./schemas/cell/CRResponse.yaml"
   securitySchemes:
     Access-token:
       in: header

openapi/v1/integrationUser.yaml

@@ -5472,6 +5472,53 @@ paths:
       summary: Stream data from a given VCF file
       tags:
         - Omics queries as User
+  /api/v1/as-user/omics/cells/analytics/cell-ratio:
+    post:
+      operationId: cellRatioAsUser
+      summary: "[BETA] Compute cell ratio statistics across groups or metadata attributes in single-cell data."
+      tags:
+        - "[BETA] Analytics omics queries as User"
+      description: |+
+        This endpoint calculates cell ratio statistics based on single-cell metadata.
+
+        It allows quantifying the proportion of cells that meet specific criteria (`countSelected`, e.g. expression threshold, cell type, or cluster)
+        relative to a defined reference group or the total cell population (`countAvailable`) defined by study, samples, library, or preparation metadata.
+
+        `countAvailable` parameter returns all cells specified in study, sample, library, or preparation queries and filters.
+        In case `exQuery` is selected, only cells linked to cell expression will be counted in `countSelected` parameter.
+
+        The endpoint supports filtering by study, sample, library, or preparation metadata and filtering by cell expression or cell metadata fields.
+
+        Request and response parameters are subject to change as this feature is in BETA.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CRRequest"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CRResponse"
+          description: Cell ratio 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/differential-expression:
     post:
       operationId: differentialExpressionAsUser
@@ -5548,6 +5595,8 @@ paths:
           - `Minimum and maximum values` - range of expression across cells.
 
         Results are sorted by gene name.
+
+        Request and response parameters are subject to change as this feature is in BETA.
       requestBody:
         required: true
         content:
@@ -5706,6 +5755,10 @@ components:
       $ref: "./schemas/cell/GSRequest.yaml"
     GSResponse:
       $ref: "./schemas/cell/GSResponse.yaml"
+    CRRequest:
+      $ref: "./schemas/cell/CRRequest.yaml"
+    CRResponse:
+      $ref: "./schemas/cell/CRResponse.yaml"
   securitySchemes:
     Access-token:
       in: header

openapi/v1/schemas/cell/CRRequest.yaml

@@ -0,0 +1,7 @@
+type: object
+properties:
+  cellGroup:
+    $ref: 'CellGroupRequest.yaml'
+  exQuery:
+    type: string
+    example: '-3 < value < 3'

openapi/v1/schemas/cell/CRResponse.yaml

@@ -0,0 +1,21 @@
+type: object
+required:
+  - countSelected
+  - countAvailable
+  - ratio
+properties:
+  countSelected:
+    type: integer
+    format: int32
+    description: Count of Cells selected with all queries and filters.
+    example: 1243393
+  countAvailable:
+    type: integer
+    format: int32
+    description: Count of all available Cells limited by Study and SLP queries and filters.
+    example: 9234945
+  ratio:
+    type: number
+    format: double
+    description: Ratio value
+    example: 0.13465

openapi/v1/schemas/cell/CellGroupRequest.yaml

@@ -0,0 +1,32 @@
+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/DERequest.yaml

@@ -1,9 +1,9 @@
 type: object
 properties:
   caseGroup:
-    $ref: '#/components/schemas/CellGroupRequest'
+    $ref: 'CellGroupRequest.yaml'
   controlGroup:
-    $ref: '#/components/schemas/CellGroupRequest'
+    $ref: 'CellGroupRequest.yaml'
   exQuery:
     type: string
     example: 'feature=ENSG00000230368,ENSG00000188976'
@@ -20,38 +20,3 @@ properties:
 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/GSRequest.yaml

@@ -1,7 +1,7 @@
 type: object
 properties:
   cellGroup:
-    $ref: '#/components/schemas/CellGroupRequest'
+    $ref: 'CellGroupRequest.yaml'
   geneNames:
     type: array
     items:
@@ -15,38 +15,3 @@ properties:
     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