diff --git a/build.gradle.kts b/build.gradle.kts index d5a33760..89132c03 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -60,7 +60,9 @@ tasks { // Workaround for https://github.com/OpenAPITools/openapi-generator/issues/21619 // The second version asks for license, which we can't provide due to unavailability of // "licenseName" and "licenseUrl" fields in the specification for python generator. - "poetry1" to "true" + "poetry1" to "true", + // All float fields accept "NaN", "Infinity", "-Infinity" values + "mapNumberTo" to "float" // "disallowAdditionalPropertiesIfNotPresent" to "true" ) } diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index a28d37a9..6a9bf320 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7021,6 +7021,60 @@ paths: summary: Stream data from a given VCF file tags: - Omics queries as Curator + /api/v1/as-curator/omics/cells/analytics/differential-expression: + post: + operationId: differentialExpressionAsCurator + summary: "[BETA] Perform differential gene expression analytics between case and control cell groups" + tags: + - "[BETA] Analytics omics queries as Curator" + # The descriptions below are also duplicated in the schema description, make sure to keep them in sync. + description: |+ + This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. + + Consult `/omics` search endpoints to find description of parameters within the cell groups. + The response includes per-gene metrics that characterize expression differences between the two groups: + - `Gene name` - gene identifier. + - `Case cell count` - number of cells expressing the gene in the case group. + - `Control cell count` - number of cells expressing the gene in the control group. + - `Average expression (case)` - mean expression level across case cells. + - `Average expression (control)` - mean expression level across control cells. + - `Expression difference` - numerical difference between average expressions. + - `Fold change` - ratio of average expressions between case and control groups. + - `U statistic` - Mann–Whitney U test statistic that measures the difference between Case and Control groups. + - `p-value` - the probability of observing results as extreme as (or more extreme than) those obtained, assuming that the null hypothesis is true. + + Results are sorted by absolute value of fold change in descending order, allowing easy identification of the most differentially expressed genes. + + Request and response parameters are subject to change as this feature is in BETA. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/DERequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DEResponse" + description: Differential expression result + "400": + content: { } + description: Entities cannot be retrieved. + "401": + content: { } + description: |- + User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) + or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). + "500": + content: { } + description: "An internal server error occurred. This indicates an unexpected\ + \ failure in the Genestack system, please file a bug report to support@genestack.com,\ + \ including the error details." + security: + - Access-token: [ ] + - Genestack-API-Token: [ ] /api/v1/as-curator/integration/studies/{id}/tasks/publish-versions: post: description: This endpoint publishes information from staging and creates new @@ -7372,6 +7426,10 @@ components: $ref: "./schemas/integration/FilterOption.yaml" AFile: $ref: "./schemas/afile/AFile.yaml" + DERequest: + $ref: "./schemas/cell/DERequest.yaml" + DEResponse: + $ref: "./schemas/cell/DEResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 7e861b23..151f94b2 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5472,6 +5472,60 @@ paths: summary: Stream data from a given VCF file tags: - Omics queries as User + /api/v1/as-user/omics/cells/analytics/differential-expression: + post: + operationId: differentialExpressionAsUser + summary: "[BETA] Perform differential gene expression analytics between case and control cell groups" + tags: + - "[BETA] Analytics omics queries as User" + # The descriptions below are also duplicated in the schema description, make sure to keep them in sync. + description: |+ + This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. + + Consult `/omics` search endpoints to find description of parameters within the cell groups. + The response includes per-gene metrics that characterize expression differences between the two groups: + - `Gene name` - gene identifier. + - `Case cell count` - number of cells expressing the gene in the case group. + - `Control cell count` - number of cells expressing the gene in the control group. + - `Average expression (case)` - mean expression level across case cells. + - `Average expression (control)` - mean expression level across control cells. + - `Expression difference` - numerical difference between average expressions. + - `Fold change` - ratio of average expressions between case and control groups. + - `U statistic` - Mann–Whitney U test statistic that measures the difference between Case and Control groups. + - `p-value` - the probability of observing results as extreme as (or more extreme than) those obtained, assuming that the null hypothesis is true. + + Results are sorted by absolute value of fold change in descending order, allowing easy identification of the most differentially expressed genes. + + Request and response parameters are subject to change as this feature is in BETA. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/DERequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DEResponse" + description: Differential expression result + "400": + content: { } + description: Entities cannot be retrieved. + "401": + content: { } + description: |- + User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) + or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). + "500": + content: { } + description: "An internal server error occurred. This indicates an unexpected\ + \ failure in the Genestack system, please file a bug report to support@genestack.com,\ + \ including the error details." + security: + - Access-token: [ ] + - Genestack-API-Token: [ ] /api/v1/as-user/integration/link/files/by/study/{id}: get: operationId: getFilesByStudyAsUser @@ -5591,6 +5645,10 @@ components: $ref: "./schemas/integration/FilterOption.yaml" AFile: $ref: "./schemas/afile/AFile.yaml" + DERequest: + $ref: "./schemas/cell/DERequest.yaml" + DEResponse: + $ref: "./schemas/cell/DEResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/schemas/cell/DERequest.yaml b/openapi/v1/schemas/cell/DERequest.yaml new file mode 100644 index 00000000..52005e11 --- /dev/null +++ b/openapi/v1/schemas/cell/DERequest.yaml @@ -0,0 +1,57 @@ +type: object +properties: + caseGroup: + $ref: '#/components/schemas/CellGroupRequest' + controlGroup: + $ref: '#/components/schemas/CellGroupRequest' + exQuery: + type: string + example: 'feature=ENSG00000230368,ENSG00000188976' + limit: + type: integer + format: int32 + description: This parameter determines the number of results to retrieve per page, with the default set at 2000. + example: 2000 + offset: + type: integer + format: int32 + description: This parameter allows skipping a specified number of results, with the default set at 0. + example: 0 +required: + - caseGroup + - controlGroup +components: + schemas: + CellGroupRequest: + type: object + properties: + studyFilter: + type: string + example: '"Study Source"=ArrayExpress' + studyQuery: + type: string + example: 'RNA-Seq of human dendritic cells' + sampleFilter: + type: string + example: '"Species or strain"="Homo sapiens"' + sampleQuery: + type: string + example: 'Clozapine' + libraryFilter: + type: string + example: '"Library Type"=RNA-Seq-1' + libraryQuery: + type: string + example: 'illumina HiSeq500' + preparationFilter: + type: string + example: 'Digestion=Trypsin' + preparationQuery: + type: string + example: 'reversed-phase liquid chromatography' + cellQuery: + type: string + example: 'cellType=Macrophage,Monocyte' + searchSpecificTerms: + type: boolean + example: false diff --git a/openapi/v1/schemas/cell/DEResponse.yaml b/openapi/v1/schemas/cell/DEResponse.yaml new file mode 100644 index 00000000..3f283aea --- /dev/null +++ b/openapi/v1/schemas/cell/DEResponse.yaml @@ -0,0 +1,91 @@ +type: object +properties: + resultsPerGene: + type: array + items: + $ref: '#/components/schemas/GeneEntry' + pagination: + $ref: '#/components/schemas/Pagination' +required: + - resultsPerGene + - pagination +components: + schemas: + GeneEntry: + type: object + # The descriptions below are also duplicated in the endpoint description, make sure to keep them in sync. + properties: + geneId: + type: string + description: Gene identifier. + example: ENSG00000230368 + caseCellCount: + type: integer + description: Number of cells expressing the gene in the case group. + example: 8450 + controlCellCount: + type: integer + description: Number of cells expressing the gene in the control group. + example: 8123 + caseAvgExpression: + type: number + format: double + description: Mean expression level across case cells. + example: 1.24 + controlAvgExpression: + type: number + format: double + description: Mean expression level across control cells. + example: 0.62 + expressionDifference: + type: number + format: double + description: Numerical difference between average expressions. + example: 0.62 + foldChange: + type: number + format: double + description: Ratio of average expressions between case and control groups. + example: 2.0 + mannWhitneyU: + type: number + format: double + description: Mann–Whitney U test statistic that measures the difference between Case and Control groups. + example: 1.5 + pValue: + type: number + format: double + description: The probability of observing results as extreme as (or more extreme than) those obtained, assuming that the null hypothesis is true. + example: 0.95 + required: + - geneId + - caseCellCount + - controlCellCount + - caseAvgExpression + - controlAvgExpression + - expressionDifference + - foldChange + - mannWhitneyU + - pValue + Pagination: + type: object + properties: + currentResultsCount: + type: integer + format: int32 + description: Number of results returned in the current response. + example: 1 + limit: + type: integer + format: int32 + description: Results limit, used in the request. + example: 2000 + offset: + type: integer + format: int32 + description: Results offset, used in the request. + example: 0 + required: + - currentResultsCount + - limit + - offset