From 90eed36878b6ae47632f28a17b3d078b00928eea Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Fri, 24 Oct 2025 15:12:13 +0200 Subject: [PATCH 01/31] ODM-12847: cell analysis: diff expression --- openapi/v1/integrationCurator.yaml | 46 ++++++++++++++++++ openapi/v1/integrationUser.yaml | 46 ++++++++++++++++++ .../cell/DifferentialExpressionRequest.yaml | 36 ++++++++++++++ .../cell/DifferentialExpressionResult.yaml | 47 +++++++++++++++++++ 4 files changed, 175 insertions(+) create mode 100644 openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml create mode 100644 openapi/v1/schemas/cell/DifferentialExpressionResult.yaml diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index c072f3ff..8813818c 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6761,6 +6761,48 @@ paths: summary: Stream data from a given VCF file tags: - Omics queries as Curator + /api/v1/as-user/omics/cells/analytics/differential-expression: + post: + operationId: differentialExpressionAsUser + summary: "[BETA] Perform differential gene expression analysis between case and control cell groups" + tags: + - "[BETA] Analysis omics queries as User" + description: |+ + This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. + + The response includes per-gene metrics that characterize expression differences between the two groups. + Results are sorted by 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/DifferentialExpressionRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DifferentialExpressionResult" + 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 @@ -7112,6 +7154,10 @@ components: $ref: "./schemas/integration/FilterOption.yaml" AFile: $ref: "./schemas/afile/AFile.yaml" + DifferentialExpressionRequest: + $ref: "./schemas/cell/DifferentialExpressionRequest.yaml" + DifferentialExpressionResult: + $ref: "./schemas/cell/DifferentialExpressionResult.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 033ae61f..3d9bbd92 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5212,6 +5212,48 @@ 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 analysis between case and control cell groups" + tags: + - "[BETA] Analysis omics queries as User" + description: |+ + This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. + + The response includes per-gene metrics that characterize expression differences between the two groups. + Results are sorted by 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/DifferentialExpressionRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DifferentialExpressionResult" + 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 @@ -5331,6 +5373,10 @@ components: $ref: "./schemas/integration/FilterOption.yaml" AFile: $ref: "./schemas/afile/AFile.yaml" + DifferentialExpressionRequest: + $ref: "./schemas/cell/DifferentialExpressionRequest.yaml" + DifferentialExpressionResult: + $ref: "./schemas/cell/DifferentialExpressionResult.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml b/openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml new file mode 100644 index 00000000..aedd6549 --- /dev/null +++ b/openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml @@ -0,0 +1,36 @@ +type: object +properties: + caseGroup: + $ref: '#/components/schemas/CellGroupRequest' + controlGroup: + $ref: '#/components/schemas/CellGroupRequest' + exQuery: + type: string +required: + - caseGroup + - controlGroup +components: + schemas: + CellGroupRequest: + type: object + properties: + studyFilter: + type: string + studyQuery: + type: string + sampleFilter: + type: string + sampleQuery: + type: string + libraryFilter: + type: string + libraryQuery: + type: string + preparationFilter: + type: string + preparationQuery: + type: string + cellQuery: + type: string + searchSpecificTerms: + type: boolean diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml new file mode 100644 index 00000000..112f3551 --- /dev/null +++ b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml @@ -0,0 +1,47 @@ +DifferentialExpressionResult: + type: object + properties: + resultsPerGene: + type: array + items: + $ref: '#/components/schemas/GeneEntry' + required: + - resultsPerGene +components: + schemas: + GeneEntry: + type: object + properties: + geneId: + type: string + description: Gene identifier + caseCellCount: + type: integer + description: Number of cells expressing the gene in the case group + controlCellCount: + type: integer + description: Number of cells expressing the gene in the control group + caseAvgExpression: + type: number + format: double + description: Average expression level across case cells + controlAvgExpression: + type: number + format: double + description: Average expression level across control cells + expressionDifference: + type: number + format: double + description: Numerical difference between average expressions + foldChange: + type: number + format: double + description: Ratio of average expressions between case and control groups + required: + - geneId + - caseCellCount + - controlCellCount + - caseAvgExpression + - controlAvgExpression + - expressionDifference + - foldChange From ab524ef6cf668051cf6f3e43a0b3259422191ce3 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Fri, 24 Oct 2025 16:08:39 +0200 Subject: [PATCH 02/31] ODM-12847: response model fix --- .../cell/DifferentialExpressionResult.yaml | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml index 112f3551..2de8a807 100644 --- a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml +++ b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml @@ -1,12 +1,11 @@ -DifferentialExpressionResult: - type: object - properties: - resultsPerGene: - type: array - items: - $ref: '#/components/schemas/GeneEntry' - required: - - resultsPerGene +type: object +properties: + resultsPerGene: + type: array + items: + $ref: '#/components/schemas/GeneEntry' +required: + - resultsPerGene components: schemas: GeneEntry: From 658d76a442e46354382e405baa8a58333109be1d Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Mon, 3 Nov 2025 20:16:32 +0100 Subject: [PATCH 03/31] ODM-12847: diff expression * pagination * examples * description improved --- openapi/v1/integrationCurator.yaml | 3 +- openapi/v1/integrationUser.yaml | 3 +- .../cell/DifferentialExpressionRequest.yaml | 21 +++++++++ .../cell/DifferentialExpressionResult.yaml | 46 ++++++++++++++++--- 4 files changed, 64 insertions(+), 9 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 1b276601..d329325d 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6983,8 +6983,9 @@ paths: 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. - Results are sorted by fold change in descending order, allowing easy identification of the most differentially expressed genes. + 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: diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 0eba521a..902e26e0 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5434,8 +5434,9 @@ paths: 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. - Results are sorted by fold change in descending order, allowing easy identification of the most differentially expressed genes. + 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: diff --git a/openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml b/openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml index aedd6549..52005e11 100644 --- a/openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml +++ b/openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml @@ -6,6 +6,17 @@ properties: $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 @@ -16,21 +27,31 @@ components: 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 diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml index 2de8a807..5049717e 100644 --- a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml +++ b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml @@ -4,8 +4,11 @@ properties: type: array items: $ref: '#/components/schemas/GeneEntry' + pagination: + $ref: '#/components/schemas/Pagination' required: - resultsPerGene + - pagination components: schemas: GeneEntry: @@ -13,29 +16,36 @@ components: properties: geneId: type: string - description: Gene identifier + description: Gene identifier. + example: ENSG00000230368 caseCellCount: type: integer - description: Number of cells expressing the gene in the case group + 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 + description: Number of cells expressing the gene in the control group. + example: 8123 caseAvgExpression: type: number format: double - description: Average expression level across case cells + description: Average expression level across case cells. + example: 1.24 controlAvgExpression: type: number format: double - description: Average expression level across control cells + description: Average expression level across control cells. + example: 0.62 expressionDifference: type: number format: double - description: Numerical difference between average expressions + description: Numerical difference between average expressions. + example: 0.62 foldChange: type: number format: double - description: Ratio of average expressions between case and control groups + description: Ratio of average expressions between case and control groups. + example: 2.0 required: - geneId - caseCellCount @@ -44,3 +54,25 @@ components: - controlAvgExpression - expressionDifference - foldChange + Pagination: + type: object + properties: + currentResultsCount: + type: integer + format: int32 + description: Number of results returned in the current response. + example: 2000 + 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 From 2284fddfb9eb2c4ca9656139e4b8a6ed734fc4c4 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Tue, 4 Nov 2025 15:47:15 +0100 Subject: [PATCH 04/31] ODM-12847: bugfix --- openapi/v1/integrationCurator.yaml | 4 ++-- openapi/v1/schemas/cell/DifferentialExpressionResult.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index d329325d..5d34c20f 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6974,9 +6974,9 @@ paths: summary: Stream data from a given VCF file tags: - Omics queries as Curator - /api/v1/as-user/omics/cells/analytics/differential-expression: + /api/v1/as-curator/omics/cells/analytics/differential-expression: post: - operationId: differentialExpressionAsUser + operationId: differentialExpressionAsCurator summary: "[BETA] Perform differential gene expression analysis between case and control cell groups" tags: - "[BETA] Analysis omics queries as User" diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml index 5049717e..5c0c87e7 100644 --- a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml +++ b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml @@ -61,7 +61,7 @@ components: type: integer format: int32 description: Number of results returned in the current response. - example: 2000 + example: 1 limit: type: integer format: int32 From 1267fd4829b4476b45c6311ad69e1eafcec10251 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Tue, 4 Nov 2025 17:45:44 +0100 Subject: [PATCH 05/31] ODM-12847: bugfix --- openapi/v1/integrationCurator.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 5d34c20f..31492fba 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6979,7 +6979,7 @@ paths: operationId: differentialExpressionAsCurator summary: "[BETA] Perform differential gene expression analysis between case and control cell groups" tags: - - "[BETA] Analysis omics queries as User" + - "[BETA] Analysis omics queries as Curator" description: |+ This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. From 10e0d779eff7efb71a2fa84e0f3f9f7dabd5f79f Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Tue, 4 Nov 2025 18:24:09 +0100 Subject: [PATCH 06/31] ODM-12847: allowing NaN and Infs in sdk? --- .../cell/DifferentialExpressionResult.yaml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml index 5c0c87e7..5bf06b86 100644 --- a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml +++ b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml @@ -27,22 +27,30 @@ components: description: Number of cells expressing the gene in the control group. example: 8123 caseAvgExpression: - type: number + oneOf: + - type: number + - type: string # Nan format: double description: Average expression level across case cells. example: 1.24 controlAvgExpression: - type: number + oneOf: + - type: number + - type: string # Nan format: double description: Average expression level across control cells. example: 0.62 expressionDifference: - type: number + oneOf: + - type: number + - type: string # Nan format: double description: Numerical difference between average expressions. example: 0.62 foldChange: - type: number + oneOf: + - type: number + - type: string # Nan, Inf and -Inf format: double description: Ratio of average expressions between case and control groups. example: 2.0 From e7eaf5ec0a3cd0d1e36f73536b3963c72a1036e7 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 5 Nov 2025 12:27:41 +0100 Subject: [PATCH 07/31] ODM-12847: test python gen --- build.gradle.kts | 3 ++- .../schemas/cell/DifferentialExpressionResult.yaml | 13 +++---------- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index d5a33760..47c09691 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -60,7 +60,8 @@ 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", + "mapNumberTo" to "StrictStr" // "disallowAdditionalPropertiesIfNotPresent" to "true" ) } diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml index 5bf06b86..67d628fd 100644 --- a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml +++ b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml @@ -27,9 +27,7 @@ components: description: Number of cells expressing the gene in the control group. example: 8123 caseAvgExpression: - oneOf: - - type: number - - type: string # Nan + type: string format: double description: Average expression level across case cells. example: 1.24 @@ -41,16 +39,11 @@ components: description: Average expression level across control cells. example: 0.62 expressionDifference: - oneOf: - - type: number - - type: string # Nan - format: double + type: string description: Numerical difference between average expressions. example: 0.62 foldChange: - oneOf: - - type: number - - type: string # Nan, Inf and -Inf + type: number format: double description: Ratio of average expressions between case and control groups. example: 2.0 From 7233d7e634d2809ce0b437d8f6ebed92eb20c31c Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 5 Nov 2025 12:48:44 +0100 Subject: [PATCH 08/31] ODM-12847: test python gen2 --- build.gradle.kts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.gradle.kts b/build.gradle.kts index 47c09691..b9a32bc8 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -61,7 +61,7 @@ tasks { // 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", - "mapNumberTo" to "StrictStr" + "mapNumberTo" to "float" // "disallowAdditionalPropertiesIfNotPresent" to "true" ) } From bae14d057ce78a2c1a71f9d8c597b533d735df1d Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 5 Nov 2025 14:21:51 +0100 Subject: [PATCH 09/31] ODM-12847: one more version... --- openapi/v1/schemas/cell/DifferentialExpressionResult.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml index 67d628fd..7a312f37 100644 --- a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml +++ b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml @@ -27,8 +27,7 @@ components: description: Number of cells expressing the gene in the control group. example: 8123 caseAvgExpression: - type: string - format: double + type: number description: Average expression level across case cells. example: 1.24 controlAvgExpression: @@ -39,7 +38,9 @@ components: description: Average expression level across control cells. example: 0.62 expressionDifference: - type: string + oneOf: + - type: number + - type: string # Nan description: Numerical difference between average expressions. example: 0.62 foldChange: From 28aba9a9d2f83b4599da61bf5e3283777625f4df Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 5 Nov 2025 15:15:32 +0100 Subject: [PATCH 10/31] ODM-12847: switching back to number --- .../v1/schemas/cell/DifferentialExpressionResult.yaml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml index 7a312f37..5c0c87e7 100644 --- a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml +++ b/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml @@ -28,19 +28,17 @@ components: example: 8123 caseAvgExpression: type: number + format: double description: Average expression level across case cells. example: 1.24 controlAvgExpression: - oneOf: - - type: number - - type: string # Nan + type: number format: double description: Average expression level across control cells. example: 0.62 expressionDifference: - oneOf: - - type: number - - type: string # Nan + type: number + format: double description: Numerical difference between average expressions. example: 0.62 foldChange: From 85168b68c2030cab9a8cf71b44698bd3c1b3b1d2 Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 5 Nov 2025 16:41:18 +0100 Subject: [PATCH 11/31] ODM-12846: Cell analytics - Gene Summary - added endpoint skeleton for integrationCurator --- openapi/v1/integrationCurator.yaml | 44 ++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index c60480e8..615153d6 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6974,6 +6974,50 @@ paths: summary: Stream data from a given VCF file tags: - Omics queries as Curator + /api/v1/as-curator/omics/cells/analytics/gene-summary: + post: + operationId: geneSummaryAsCurator + tags: + - "[BETA] Analysis omics queries as Curator" + description: |+ + This endpoint provides gene summary statistical metrics for gene expression across single-cell datasets. + It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. + + Consult `/omics` search endpoints to find description of parameters within the cell groups. + The response includes per-gene statistics. + + Request and response parameters are subject to change as this feature is in BETA. + requestBody: + required: true + content: + text/plain: + schema: + type: string + responses: + "200": + content: + text/plain: + schema: + type: string + description: Gene summary result + "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 From a720ee0538e6a4983e2aa9d863236d2ea4df32b4 Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 5 Nov 2025 17:06:33 +0100 Subject: [PATCH 12/31] ODM-12846: Cell analytics - Gene Summary - added endpoint skeleton for integrationUser --- openapi/v1/integrationUser.yaml | 44 +++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 077a5a05..0ef8263f 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5425,6 +5425,50 @@ paths: summary: Stream data from a given VCF file tags: - Omics queries as User + /api/v1/as-curator/omics/cells/analytics/gene-summary: + post: + operationId: geneSummaryAsCurator + tags: + - "[BETA] Analysis omics queries as Curator" + description: |+ + This endpoint provides gene summary statistical metrics for gene expression across single-cell datasets. + It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. + + Consult `/omics` search endpoints to find description of parameters within the cell groups. + The response includes per-gene statistics. + + Request and response parameters are subject to change as this feature is in BETA. + requestBody: + required: true + content: + text/plain: + schema: + type: string + responses: + "200": + content: + text/plain: + schema: + type: string + description: Gene summary result + "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 From 76adcb2eba30e4f1662e2b9b7e5a024c3eb443e7 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 5 Nov 2025 18:27:39 +0100 Subject: [PATCH 13/31] ODM-12847: shorten names (to shorten "DifferentialExpressionResultResultsPerGeneInner" inside python sdk) --- openapi/v1/integrationCurator.yaml | 12 ++++++------ openapi/v1/integrationUser.yaml | 12 ++++++------ ...erentialExpressionRequest.yaml => DERequest.yaml} | 0 ...erentialExpressionResult.yaml => DEResponse.yaml} | 0 4 files changed, 12 insertions(+), 12 deletions(-) rename openapi/v1/schemas/cell/{DifferentialExpressionRequest.yaml => DERequest.yaml} (100%) rename openapi/v1/schemas/cell/{DifferentialExpressionResult.yaml => DEResponse.yaml} (100%) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 31492fba..ce45e45a 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6992,14 +6992,14 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/DifferentialExpressionRequest" + $ref: "#/components/schemas/DERequest" required: true responses: "200": content: application/json: schema: - $ref: "#/components/schemas/DifferentialExpressionResult" + $ref: "#/components/schemas/DEResponse" description: Differential expression result "400": content: { } @@ -7368,10 +7368,10 @@ components: $ref: "./schemas/integration/FilterOption.yaml" AFile: $ref: "./schemas/afile/AFile.yaml" - DifferentialExpressionRequest: - $ref: "./schemas/cell/DifferentialExpressionRequest.yaml" - DifferentialExpressionResult: - $ref: "./schemas/cell/DifferentialExpressionResult.yaml" + DERequest: + $ref: "./schemas/cell/DERequest.yaml" + DEResponse: + $ref: "./schemas/cell/DEResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 902e26e0..561063f8 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5443,14 +5443,14 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/DifferentialExpressionRequest" + $ref: "#/components/schemas/DERequest" required: true responses: "200": content: application/json: schema: - $ref: "#/components/schemas/DifferentialExpressionResult" + $ref: "#/components/schemas/DEResponse" description: Differential expression result "400": content: { } @@ -5587,10 +5587,10 @@ components: $ref: "./schemas/integration/FilterOption.yaml" AFile: $ref: "./schemas/afile/AFile.yaml" - DifferentialExpressionRequest: - $ref: "./schemas/cell/DifferentialExpressionRequest.yaml" - DifferentialExpressionResult: - $ref: "./schemas/cell/DifferentialExpressionResult.yaml" + DERequest: + $ref: "./schemas/cell/DERequest.yaml" + DEResponse: + $ref: "./schemas/cell/DEResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml b/openapi/v1/schemas/cell/DERequest.yaml similarity index 100% rename from openapi/v1/schemas/cell/DifferentialExpressionRequest.yaml rename to openapi/v1/schemas/cell/DERequest.yaml diff --git a/openapi/v1/schemas/cell/DifferentialExpressionResult.yaml b/openapi/v1/schemas/cell/DEResponse.yaml similarity index 100% rename from openapi/v1/schemas/cell/DifferentialExpressionResult.yaml rename to openapi/v1/schemas/cell/DEResponse.yaml From 0ec015daebad026d6154fbfd123131ec003e1828 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 5 Nov 2025 18:33:19 +0100 Subject: [PATCH 14/31] =?UTF-8?q?ODM-12847:=20Mann=E2=80=93Whitney=20U=20t?= =?UTF-8?q?est?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- openapi/v1/schemas/cell/DEResponse.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/openapi/v1/schemas/cell/DEResponse.yaml b/openapi/v1/schemas/cell/DEResponse.yaml index 5c0c87e7..dc76cb11 100644 --- a/openapi/v1/schemas/cell/DEResponse.yaml +++ b/openapi/v1/schemas/cell/DEResponse.yaml @@ -46,6 +46,16 @@ components: 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 @@ -54,6 +64,8 @@ components: - controlAvgExpression - expressionDifference - foldChange + - mannWhitneyU + - pValue Pagination: type: object properties: From 32ecefe61180605fc20bddd0bdd3748874c74926 Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 5 Nov 2025 18:40:21 +0100 Subject: [PATCH 15/31] ODM-12846: Cell analytics - Gene Summary - added GeneSummaryRequest for integrationCurator --- openapi/v1/integrationCurator.yaml | 6 ++- .../v1/schemas/cell/GeneSummaryRequest.yaml | 51 +++++++++++++++++++ 2 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 openapi/v1/schemas/cell/GeneSummaryRequest.yaml diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 615153d6..3bf69957 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6990,9 +6990,9 @@ paths: requestBody: required: true content: - text/plain: + application/json: schema: - type: string + $ref: "#/components/schemas/GeneSummaryRequest" responses: "200": content: @@ -7369,6 +7369,8 @@ components: $ref: "./schemas/integration/FilterOption.yaml" AFile: $ref: "./schemas/afile/AFile.yaml" + GeneSummaryRequest: + $ref: "./schemas/cell/GeneSummaryRequest.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/schemas/cell/GeneSummaryRequest.yaml b/openapi/v1/schemas/cell/GeneSummaryRequest.yaml new file mode 100644 index 00000000..7fa82dfb --- /dev/null +++ b/openapi/v1/schemas/cell/GeneSummaryRequest.yaml @@ -0,0 +1,51 @@ +type: object +properties: + cellGroup: + $ref: '#/components/schemas/CellGroupRequest' + geneIds: + type: array + items: + type: string + example: + - "ENSG00000230368" + - "ENSG00000188976" + exQuery: + type: string + example: '-3 < value < 3' +required: + - geneIds +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 From 3d25f6daf1af2a0b7a5dfc87a1b0a5a1b377d8da Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 5 Nov 2025 23:27:30 +0100 Subject: [PATCH 16/31] ODM-12846: Cell analytics - Gene Summary - added GeneSummaryResponse for integrationCurator --- openapi/v1/integrationCurator.yaml | 8 ++- .../v1/schemas/cell/GeneSummaryResponse.yaml | 68 +++++++++++++++++++ 2 files changed, 73 insertions(+), 3 deletions(-) create mode 100644 openapi/v1/schemas/cell/GeneSummaryResponse.yaml diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 3bf69957..e373f5c0 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6995,11 +6995,11 @@ paths: $ref: "#/components/schemas/GeneSummaryRequest" responses: "200": + description: Gene summary result content: - text/plain: + application/json: schema: - type: string - description: Gene summary result + $ref: "#/components/schemas/GeneSummaryResponse" "400": content: { } description: Invalid data in the request. See the error message for details. @@ -7371,6 +7371,8 @@ components: $ref: "./schemas/afile/AFile.yaml" GeneSummaryRequest: $ref: "./schemas/cell/GeneSummaryRequest.yaml" + GeneSummaryResponse: + $ref: "./schemas/cell/GeneSummaryResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/schemas/cell/GeneSummaryResponse.yaml b/openapi/v1/schemas/cell/GeneSummaryResponse.yaml new file mode 100644 index 00000000..618c39b6 --- /dev/null +++ b/openapi/v1/schemas/cell/GeneSummaryResponse.yaml @@ -0,0 +1,68 @@ +type: object +properties: + resultsPerGene: + type: array + items: + $ref: '#/components/schemas/GeneEntry' +components: + schemas: + GeneEntry: + 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 From ace5a54a8deb08ce34b0135b5a1c6c357008b3da Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Thu, 6 Nov 2025 00:00:01 +0100 Subject: [PATCH 17/31] ODM-12846: Cell analytics - Gene Summary - added GeneSummaryRequest amd GeneSummaryResponse for integrationUser --- openapi/v1/integrationUser.yaml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 0ef8263f..8cef3de0 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5441,16 +5441,16 @@ paths: requestBody: required: true content: - text/plain: + application/json: schema: - type: string + $ref: "#/components/schemas/GeneSummaryRequest" responses: "200": + description: Gene summary result content: - text/plain: + application/json: schema: - type: string - description: Gene summary result + $ref: "#/components/schemas/GeneSummaryResponse" "400": content: { } description: Invalid data in the request. See the error message for details. @@ -5588,6 +5588,10 @@ components: $ref: "./schemas/integration/FilterOption.yaml" AFile: $ref: "./schemas/afile/AFile.yaml" + GeneSummaryRequest: + $ref: "./schemas/cell/GeneSummaryRequest.yaml" + GeneSummaryResponse: + $ref: "./schemas/cell/GeneSummaryResponse.yaml" securitySchemes: Access-token: in: header From 9cbacf4b67e55731a0d76b41c3a38353adf440ee Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Thu, 6 Nov 2025 07:45:30 +0100 Subject: [PATCH 18/31] ODM-12846: Cell analytics - Gene Summary - added GeneSummaryRequest amd GeneSummaryResponse for integrationUser --- openapi/v1/schemas/cell/GeneSummaryRequest.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi/v1/schemas/cell/GeneSummaryRequest.yaml b/openapi/v1/schemas/cell/GeneSummaryRequest.yaml index 7fa82dfb..b2ac5704 100644 --- a/openapi/v1/schemas/cell/GeneSummaryRequest.yaml +++ b/openapi/v1/schemas/cell/GeneSummaryRequest.yaml @@ -9,6 +9,7 @@ properties: example: - "ENSG00000230368" - "ENSG00000188976" + - "ENSG00000188982" exQuery: type: string example: '-3 < value < 3' From 1b204a10cee2f9cc48600644db3618ab06c134de Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Thu, 6 Nov 2025 08:01:50 +0100 Subject: [PATCH 19/31] ODM-12846: Cell analytics - Gene Summary - removed trailing whitespace --- openapi/v1/integrationCurator.yaml | 6 +++--- openapi/v1/integrationUser.yaml | 6 +++--- openapi/v1/schemas/cell/GeneSummaryResponse.yaml | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index e373f5c0..9da2d9f3 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6981,7 +6981,7 @@ paths: - "[BETA] Analysis omics queries as Curator" description: |+ This endpoint provides gene summary statistical metrics for gene expression across single-cell datasets. - It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. + It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. Consult `/omics` search endpoints to find description of parameters within the cell groups. The response includes per-gene statistics. @@ -7006,8 +7006,8 @@ paths: "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` + 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: { } diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 8cef3de0..68819f16 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5432,7 +5432,7 @@ paths: - "[BETA] Analysis omics queries as Curator" description: |+ This endpoint provides gene summary statistical metrics for gene expression across single-cell datasets. - It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. + It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. Consult `/omics` search endpoints to find description of parameters within the cell groups. The response includes per-gene statistics. @@ -5457,8 +5457,8 @@ paths: "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` + 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: { } diff --git a/openapi/v1/schemas/cell/GeneSummaryResponse.yaml b/openapi/v1/schemas/cell/GeneSummaryResponse.yaml index 618c39b6..8a9827c5 100644 --- a/openapi/v1/schemas/cell/GeneSummaryResponse.yaml +++ b/openapi/v1/schemas/cell/GeneSummaryResponse.yaml @@ -56,10 +56,10 @@ components: histogram: type: array description: | - Histogram as a list of [binStart, binEnd, count] triples. + 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), + [(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 From 9cbca740b018891160696268258841f09339f25a Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Thu, 6 Nov 2025 10:02:01 +0100 Subject: [PATCH 20/31] ODM-12846: Cell analytics - Gene Summary - renamed request property --- openapi/v1/schemas/cell/GeneSummaryRequest.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi/v1/schemas/cell/GeneSummaryRequest.yaml b/openapi/v1/schemas/cell/GeneSummaryRequest.yaml index b2ac5704..86b90d2e 100644 --- a/openapi/v1/schemas/cell/GeneSummaryRequest.yaml +++ b/openapi/v1/schemas/cell/GeneSummaryRequest.yaml @@ -2,7 +2,7 @@ type: object properties: cellGroup: $ref: '#/components/schemas/CellGroupRequest' - geneIds: + geneNames: type: array items: type: string @@ -14,7 +14,7 @@ properties: type: string example: '-3 < value < 3' required: - - geneIds + - geneNames components: schemas: CellGroupRequest: From 9654deeaeebf28f01c2cd2d4331183a683763b76 Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Thu, 6 Nov 2025 10:33:00 +0100 Subject: [PATCH 21/31] ODM-12846: Cell analytics - Gene Summary - added summary for Curator and User endpoint and replaced Curator with User in integrationUser --- openapi/v1/integrationCurator.yaml | 1 + openapi/v1/integrationUser.yaml | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 9da2d9f3..0ba5b7e5 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6977,6 +6977,7 @@ paths: /api/v1/as-curator/omics/cells/analytics/gene-summary: post: operationId: geneSummaryAsCurator + summary: "[BETA] Perform gene summary analysis" tags: - "[BETA] Analysis omics queries as Curator" description: |+ diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 68819f16..57b4151f 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5427,9 +5427,10 @@ paths: - Omics queries as User /api/v1/as-curator/omics/cells/analytics/gene-summary: post: - operationId: geneSummaryAsCurator + operationId: geneSummaryAsUser + summary: "[BETA] Perform gene summary analysis" tags: - - "[BETA] Analysis omics queries as Curator" + - "[BETA] Analysis omics queries as User" description: |+ This endpoint provides gene summary statistical metrics for gene expression across single-cell datasets. It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. From 84f2551e2880eeae5e2a3c6e2d38a241ca3c9786 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Thu, 6 Nov 2025 18:12:28 +0100 Subject: [PATCH 22/31] ODM-12847: code review comment --- build.gradle.kts | 1 + 1 file changed, 1 insertion(+) diff --git a/build.gradle.kts b/build.gradle.kts index b9a32bc8..89132c03 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -61,6 +61,7 @@ tasks { // 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", + // All float fields accept "NaN", "Infinity", "-Infinity" values "mapNumberTo" to "float" // "disallowAdditionalPropertiesIfNotPresent" to "true" ) From fe37afd5a1b1885adaf0be7f7b6d9cd92b8ba32c Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Fri, 7 Nov 2025 12:07:34 +0100 Subject: [PATCH 23/31] ODM-12846: Cell analytics - Gene Summary - fixed user's endpoint --- openapi/v1/integrationUser.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index b09c8079..710d3881 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5468,7 +5468,7 @@ paths: security: - Access-token: [ ] - Genestack-API-Token: [ ] - /api/v1/as-curator/omics/cells/analytics/gene-summary: + /api/v1/as-user/omics/cells/analytics/gene-summary: post: operationId: geneSummaryAsUser summary: "[BETA] Perform gene summary analysis" From 431bf0aff81836eb9781d397a16f91d1c90c7a0e Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Fri, 7 Nov 2025 14:58:24 +0100 Subject: [PATCH 24/31] ODM-12846: Cell analytics - Gene Summary - fixed user's endpoint --- openapi/v1/schemas/cell/GeneSummaryResponse.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi/v1/schemas/cell/GeneSummaryResponse.yaml b/openapi/v1/schemas/cell/GeneSummaryResponse.yaml index 8a9827c5..6c91f9e0 100644 --- a/openapi/v1/schemas/cell/GeneSummaryResponse.yaml +++ b/openapi/v1/schemas/cell/GeneSummaryResponse.yaml @@ -3,10 +3,10 @@ properties: resultsPerGene: type: array items: - $ref: '#/components/schemas/GeneEntry' + $ref: '#/components/schemas/GeneSummaryEntry' components: schemas: - GeneEntry: + GeneSummaryEntry: type: object description: Per-gene summary statistics. properties: From 54bf9e08653803b27ac042867b93fdfa6e83a466 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Mon, 10 Nov 2025 15:36:37 +0100 Subject: [PATCH 25/31] ODM-12847: minor --- openapi/v1/integrationCurator.yaml | 4 ++-- openapi/v1/integrationUser.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index ce45e45a..92136cce 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -6977,9 +6977,9 @@ paths: /api/v1/as-curator/omics/cells/analytics/differential-expression: post: operationId: differentialExpressionAsCurator - summary: "[BETA] Perform differential gene expression analysis between case and control cell groups" + summary: "[BETA] Perform differential gene expression analytics between case and control cell groups" tags: - - "[BETA] Analysis omics queries as Curator" + - "[BETA] Analytics omics queries as Curator" description: |+ This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 561063f8..420c1a20 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5428,9 +5428,9 @@ paths: /api/v1/as-user/omics/cells/analytics/differential-expression: post: operationId: differentialExpressionAsUser - summary: "[BETA] Perform differential gene expression analysis between case and control cell groups" + summary: "[BETA] Perform differential gene expression analytics between case and control cell groups" tags: - - "[BETA] Analysis omics queries as User" + - "[BETA] Analytics omics queries as User" description: |+ This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. From 3d79e7bb1d0769ea338a0b04b6e43ce2929b7591 Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 12 Nov 2025 11:45:39 +0100 Subject: [PATCH 26/31] ODM-12846: Cell analytics - Gene Summary - changed analysis to analytics --- openapi/v1/integrationCurator.yaml | 4 ++-- openapi/v1/integrationUser.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 3384d98f..37d21963 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7067,9 +7067,9 @@ paths: /api/v1/as-curator/omics/cells/analytics/gene-summary: post: operationId: geneSummaryAsCurator - summary: "[BETA] Perform gene summary analysis" + summary: "[BETA] Perform gene summary analytics" tags: - - "[BETA] Analysis omics queries as Curator" + - "[BETA] Analytics omics queries as Curator" description: |+ This endpoint provides gene summary statistical metrics for gene expression across single-cell datasets. It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index dc1d5445..4b82934a 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5518,9 +5518,9 @@ paths: /api/v1/as-user/omics/cells/analytics/gene-summary: post: operationId: geneSummaryAsUser - summary: "[BETA] Perform gene summary analysis" + summary: "[BETA] Perform gene summary analytics" tags: - - "[BETA] Analysis omics queries as User" + - "[BETA] Analytics omics queries as User" description: |+ This endpoint provides gene summary statistical metrics for gene expression across single-cell datasets. It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. From be1f0cc2097fe5fdda861602066bc5ff22743081 Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 12 Nov 2025 13:49:26 +0100 Subject: [PATCH 27/31] ODM-12846: Cell analytics - Gene Summary - renamed gene summary response and request --- openapi/v1/integrationCurator.yaml | 4 ++-- openapi/v1/integrationUser.yaml | 4 ++-- .../schemas/cell/{GeneSummaryRequest.yaml => GSRequest.yaml} | 0 .../cell/{GeneSummaryResponse.yaml => GSResponse.yaml} | 0 4 files changed, 4 insertions(+), 4 deletions(-) rename openapi/v1/schemas/cell/{GeneSummaryRequest.yaml => GSRequest.yaml} (100%) rename openapi/v1/schemas/cell/{GeneSummaryResponse.yaml => GSResponse.yaml} (100%) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 37d21963..241bd19e 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7465,9 +7465,9 @@ components: DEResponse: $ref: "./schemas/cell/DEResponse.yaml" GeneSummaryRequest: - $ref: "./schemas/cell/GeneSummaryRequest.yaml" + $ref: "./schemas/cell/GSRequest.yaml" GeneSummaryResponse: - $ref: "./schemas/cell/GeneSummaryResponse.yaml" + $ref: "./schemas/cell/GSResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 4b82934a..9ba64dee 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5684,9 +5684,9 @@ components: DEResponse: $ref: "./schemas/cell/DEResponse.yaml" GeneSummaryRequest: - $ref: "./schemas/cell/GeneSummaryRequest.yaml" + $ref: "./schemas/cell/GSRequest.yaml" GeneSummaryResponse: - $ref: "./schemas/cell/GeneSummaryResponse.yaml" + $ref: "./schemas/cell/GSResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/schemas/cell/GeneSummaryRequest.yaml b/openapi/v1/schemas/cell/GSRequest.yaml similarity index 100% rename from openapi/v1/schemas/cell/GeneSummaryRequest.yaml rename to openapi/v1/schemas/cell/GSRequest.yaml diff --git a/openapi/v1/schemas/cell/GeneSummaryResponse.yaml b/openapi/v1/schemas/cell/GSResponse.yaml similarity index 100% rename from openapi/v1/schemas/cell/GeneSummaryResponse.yaml rename to openapi/v1/schemas/cell/GSResponse.yaml From 012efda84b009d2b5b8162cbda4ce790f0d8fe84 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 12 Nov 2025 14:52:42 +0100 Subject: [PATCH 28/31] !!ODM-12847: duplicating params description --- openapi/v1/integrationCurator.yaml | 12 +++++++++++- openapi/v1/integrationUser.yaml | 12 +++++++++++- openapi/v1/schemas/cell/DEResponse.yaml | 5 +++-- 3 files changed, 25 insertions(+), 4 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index b5c78d3a..8443ff5f 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7027,11 +7027,21 @@ paths: 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. + 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. diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 506a0eec..0d388a98 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5478,11 +5478,21 @@ paths: 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. + 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. diff --git a/openapi/v1/schemas/cell/DEResponse.yaml b/openapi/v1/schemas/cell/DEResponse.yaml index dc76cb11..3f283aea 100644 --- a/openapi/v1/schemas/cell/DEResponse.yaml +++ b/openapi/v1/schemas/cell/DEResponse.yaml @@ -13,6 +13,7 @@ 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 @@ -29,12 +30,12 @@ components: caseAvgExpression: type: number format: double - description: Average expression level across case cells. + description: Mean expression level across case cells. example: 1.24 controlAvgExpression: type: number format: double - description: Average expression level across control cells. + description: Mean expression level across control cells. example: 0.62 expressionDifference: type: number From 7ebcc7f5f53b482ea7f67d7bd53ff095d80005a5 Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 12 Nov 2025 14:55:37 +0100 Subject: [PATCH 29/31] ODM-12846: Cell analytics - Gene Summary - renamed gene summary response and request reference --- openapi/v1/integrationCurator.yaml | 8 ++++---- openapi/v1/integrationUser.yaml | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 241bd19e..c6925b90 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7083,14 +7083,14 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/GeneSummaryRequest" + $ref: "#/components/schemas/GSRequest" responses: "200": description: Gene summary result content: application/json: schema: - $ref: "#/components/schemas/GeneSummaryResponse" + $ref: "#/components/schemas/GSResponse" "400": content: { } description: Invalid data in the request. See the error message for details. @@ -7464,9 +7464,9 @@ components: $ref: "./schemas/cell/DERequest.yaml" DEResponse: $ref: "./schemas/cell/DEResponse.yaml" - GeneSummaryRequest: + GSRequest: $ref: "./schemas/cell/GSRequest.yaml" - GeneSummaryResponse: + GSResponse: $ref: "./schemas/cell/GSResponse.yaml" securitySchemes: Access-token: diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 9ba64dee..d139aa6c 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5534,14 +5534,14 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/GeneSummaryRequest" + $ref: "#/components/schemas/GSRequest" responses: "200": description: Gene summary result content: application/json: schema: - $ref: "#/components/schemas/GeneSummaryResponse" + $ref: "#/components/schemas/GSResponse" "400": content: { } description: Invalid data in the request. See the error message for details. @@ -5683,9 +5683,9 @@ components: $ref: "./schemas/cell/DERequest.yaml" DEResponse: $ref: "./schemas/cell/DEResponse.yaml" - GeneSummaryRequest: + GSRequest: $ref: "./schemas/cell/GSRequest.yaml" - GeneSummaryResponse: + GSResponse: $ref: "./schemas/cell/GSResponse.yaml" securitySchemes: Access-token: From 5787d703c20e1fe098f53ac58e3374e8511da6b8 Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 12 Nov 2025 15:20:15 +0100 Subject: [PATCH 30/31] ODM-12846: Cell analytics - Gene Summary - update summary and description --- openapi/v1/integrationCurator.yaml | 24 ++++++++++++++++-------- openapi/v1/integrationUser.yaml | 24 ++++++++++++++++-------- 2 files changed, 32 insertions(+), 16 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 8562b335..2f256ae3 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7077,17 +7077,25 @@ paths: /api/v1/as-curator/omics/cells/analytics/gene-summary: post: operationId: geneSummaryAsCurator - summary: "[BETA] Perform gene summary analytics" + 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 gene summary statistical metrics for gene expression across single-cell datasets. - It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. - - Consult `/omics` search endpoints to find description of parameters within the cell groups. - The response includes per-gene statistics. - - Request and response parameters are subject to change as this feature is in BETA. + 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: diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index b915a259..2313f398 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5528,17 +5528,25 @@ paths: /api/v1/as-user/omics/cells/analytics/gene-summary: post: operationId: geneSummaryAsUser - summary: "[BETA] Perform gene summary analytics" + 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 gene summary statistical metrics for gene expression across single-cell datasets. - It provides basic statistical terms - cell count, mean, median, standard deviation, quantiles, histogram. - - Consult `/omics` search endpoints to find description of parameters within the cell groups. - The response includes per-gene statistics. - - Request and response parameters are subject to change as this feature is in BETA. + 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: From 9000cffdbc259999d9c4a1da0bcbf4a7791ce89f Mon Sep 17 00:00:00 2001 From: Marijan Mihaljev Date: Wed, 12 Nov 2025 16:34:07 +0100 Subject: [PATCH 31/31] ODM-12846: Cell analytics - Gene Summary - Refactor emphasizing on return fields name --- openapi/v1/integrationCurator.yaml | 16 ++++++++-------- openapi/v1/integrationUser.yaml | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 2f256ae3..852700c9 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7086,14 +7086,14 @@ paths: 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. + - `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: diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 2313f398..268efd10 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5537,14 +5537,14 @@ paths: 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. + - `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: