diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integrationCurator.yaml index 6a9bf320..29078f72 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integrationCurator.yaml @@ -7075,6 +7075,59 @@ paths: security: - Access-token: [ ] - Genestack-API-Token: [ ] + /api/v1/as-curator/omics/cells/analytics/gene-summary: + post: + operationId: geneSummaryAsCurator + 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 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: + application/json: + schema: + $ref: "#/components/schemas/GSRequest" + responses: + "200": + description: Gene summary result + content: + application/json: + schema: + $ref: "#/components/schemas/GSResponse" + "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 @@ -7430,6 +7483,10 @@ components: $ref: "./schemas/cell/DERequest.yaml" DEResponse: $ref: "./schemas/cell/DEResponse.yaml" + GSRequest: + $ref: "./schemas/cell/GSRequest.yaml" + GSResponse: + $ref: "./schemas/cell/GSResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 151f94b2..36e3f1cb 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -5526,6 +5526,59 @@ paths: security: - Access-token: [ ] - Genestack-API-Token: [ ] + /api/v1/as-user/omics/cells/analytics/gene-summary: + post: + operationId: geneSummaryAsUser + 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 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: + application/json: + schema: + $ref: "#/components/schemas/GSRequest" + responses: + "200": + description: Gene summary result + content: + application/json: + schema: + $ref: "#/components/schemas/GSResponse" + "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 @@ -5649,6 +5702,10 @@ components: $ref: "./schemas/cell/DERequest.yaml" DEResponse: $ref: "./schemas/cell/DEResponse.yaml" + GSRequest: + $ref: "./schemas/cell/GSRequest.yaml" + GSResponse: + $ref: "./schemas/cell/GSResponse.yaml" securitySchemes: Access-token: in: header diff --git a/openapi/v1/schemas/cell/GSRequest.yaml b/openapi/v1/schemas/cell/GSRequest.yaml new file mode 100644 index 00000000..86b90d2e --- /dev/null +++ b/openapi/v1/schemas/cell/GSRequest.yaml @@ -0,0 +1,52 @@ +type: object +properties: + cellGroup: + $ref: '#/components/schemas/CellGroupRequest' + geneNames: + type: array + items: + type: string + example: + - "ENSG00000230368" + - "ENSG00000188976" + - "ENSG00000188982" + exQuery: + type: string + example: '-3 < value < 3' +required: + - geneNames +components: + schemas: + CellGroupRequest: + type: object + properties: + studyFilter: + type: string + example: '"Study Source"=ArrayExpress' + studyQuery: + type: string + example: 'RNA-Seq of human dendritic cells' + sampleFilter: + type: string + example: '"Species or strain"="Homo sapiens"' + sampleQuery: + type: string + example: 'Clozapine' + libraryFilter: + type: string + example: '"Library Type"=RNA-Seq-1' + libraryQuery: + type: string + example: 'illumina HiSeq500' + preparationFilter: + type: string + example: 'Digestion=Trypsin' + preparationQuery: + type: string + example: 'reversed-phase liquid chromatography' + cellQuery: + type: string + example: 'cellType=Macrophage,Monocyte' + searchSpecificTerms: + type: boolean + example: false diff --git a/openapi/v1/schemas/cell/GSResponse.yaml b/openapi/v1/schemas/cell/GSResponse.yaml new file mode 100644 index 00000000..6c91f9e0 --- /dev/null +++ b/openapi/v1/schemas/cell/GSResponse.yaml @@ -0,0 +1,68 @@ +type: object +properties: + resultsPerGene: + type: array + items: + $ref: '#/components/schemas/GeneSummaryEntry' +components: + schemas: + GeneSummaryEntry: + 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