From 90eed36878b6ae47632f28a17b3d078b00928eea Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Fri, 24 Oct 2025 15:12:13 +0200 Subject: [PATCH 01/16] 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/16] 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/16] 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/16] 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/16] 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/16] 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/16] 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/16] 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/16] 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/16] 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 76adcb2eba30e4f1662e2b9b7e5a024c3eb443e7 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 5 Nov 2025 18:27:39 +0100 Subject: [PATCH 11/16] 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 12/16] =?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 84f2551e2880eeae5e2a3c6e2d38a241ca3c9786 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Thu, 6 Nov 2025 18:12:28 +0100 Subject: [PATCH 13/16] 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 54bf9e08653803b27ac042867b93fdfa6e83a466 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Mon, 10 Nov 2025 15:36:37 +0100 Subject: [PATCH 14/16] 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 012efda84b009d2b5b8162cbda4ce790f0d8fe84 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 12 Nov 2025 14:52:42 +0100 Subject: [PATCH 15/16] !!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 27ad841e1644c6755e3e2539376882d058eec9b5 Mon Sep 17 00:00:00 2001 From: Mikhail Smazhevsky Date: Wed, 12 Nov 2025 16:04:17 +0100 Subject: [PATCH 16/16] !!ODM-12847: minor --- openapi/v1/integrationCurator.yaml | 1 + openapi/v1/integrationUser.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 8443ff5f..6a9bf320 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7042,6 +7042,7 @@ paths: - `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 0d388a98..151f94b2 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5493,6 +5493,7 @@ paths: - `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.