Package ubic.gemma.rest

Class DatasetsWebService

  • @Service
@Path("/datasets")
public class DatasetsWebService
extends Object
    RESTful interface for datasets.
    Author:
    tesarst

    • Constructor Detail

      • DatasetsWebService

        public DatasetsWebService()

    • Method Detail

      • getDatasetPlatforms

        @GET
@Path("/{dataset}/platforms")
@Produces("application/json")
public ResponseDataObject<List<ArrayDesignValueObject>> getDatasetPlatforms​(@PathParam("dataset")
                                                                            DatasetArg<?> datasetArg)
        Retrieves platforms for the given dataset.
        Parameters:
        datasetArg - can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

      • getDatasetSamples

        @GET
@Path("/{dataset}/samples")
@Produces("application/json")
public ResponseDataObject<List<BioAssayValueObject>> getDatasetSamples​(@PathParam("dataset")
                                                                       DatasetArg<?> datasetArg)
        Retrieves the samples for the given dataset.
        Parameters:
        datasetArg - can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

      • getDatasetDifferentialExpressionAnalyses

        @GET
@Path("/{dataset}/analyses/differential")
@Produces("application/json")
public ResponseDataObject<List<DifferentialExpressionAnalysisValueObject>> getDatasetDifferentialExpressionAnalyses​(@PathParam("dataset")
                                                                                                                    DatasetArg<?> datasetArg,
                                                                                                                    @QueryParam("offset") @DefaultValue("0")
                                                                                                                    OffsetArg offset,
                                                                                                                    @QueryParam("limit") @DefaultValue("20")
                                                                                                                    LimitArg limit)
        Retrieves the differential analysis results for the given dataset.
        Parameters:
        datasetArg - can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

      • getDatasetsDifferentialExpressionAnalysisResultsForGene

        @GET
@Path("/analyses/differential/results/genes/{gene}")
@Produces({"application/json","text/tab-separated-values; charset=UTF-8"})
public Object getDatasetsDifferentialExpressionAnalysisResultsForGene​(@PathParam("gene")
                                                                      GeneArg<?> geneArg,
                                                                      @QueryParam("query")
                                                                      QueryArg query,
                                                                      @QueryParam("filter") @DefaultValue("")
                                                                      FilterArg<ExpressionExperiment> filter,
                                                                      @QueryParam("offset")
                                                                      OffsetArg offsetArg,
                                                                      @QueryParam("limit")
                                                                      LimitArg limitArg,
                                                                      @QueryParam("threshold") @DefaultValue("1.0")
                                                                      Double threshold,
                                                                      @Context
                                                                      javax.ws.rs.core.HttpHeaders headers)
        Obtain differential expression analysis results for a given gene.

      • getDatasetsDifferentialExpressionAnalysisResultsForGeneInTaxon

        @GET
@Path("/analyses/differential/results/taxa/{taxon}/genes/{gene}")
@Produces({"application/json","text/tab-separated-values; charset=UTF-8"})
public Object getDatasetsDifferentialExpressionAnalysisResultsForGeneInTaxon​(@PathParam("taxon")
                                                                             TaxonArg<?> taxonArg,
                                                                             @PathParam("gene")
                                                                             GeneArg<?> geneArg,
                                                                             @QueryParam("query")
                                                                             QueryArg query,
                                                                             @QueryParam("filter") @DefaultValue("")
                                                                             FilterArg<ExpressionExperiment> filter,
                                                                             @QueryParam("offset")
                                                                             OffsetArg offsetArg,
                                                                             @QueryParam("limit")
                                                                             LimitArg limitArg,
                                                                             @QueryParam("threshold") @DefaultValue("1.0")
                                                                             Double threshold,
                                                                             @Context
                                                                             javax.ws.rs.core.HttpHeaders headers)
        Obtain differential expression analysis results for a given gene in a given taxon.

      • getDatasetAnnotations

        @GET
@Path("/{dataset}/annotations")
@Produces("application/json")
public ResponseDataObject<Set<AnnotationValueObject>> getDatasetAnnotations​(@PathParam("dataset")
                                                                            DatasetArg<?> datasetArg)
        Retrieves the annotations for the given dataset.
        Parameters:
        datasetArg - can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

      • getDatasetQuantitationTypes

        @GET
@Path("/{dataset}/quantitationTypes")
@Produces("application/json")
public ResponseDataObject<Set<QuantitationTypeValueObject>> getDatasetQuantitationTypes​(@PathParam("dataset")
                                                                                        DatasetArg<?> datasetArg)
        Retrieve all available quantitation types for a dataset.

      • getDatasetExpression

        @GET
@Path("/{dataset}/data")
@Produces("text/tab-separated-values; charset=UTF-8")
public javax.ws.rs.core.Response getDatasetExpression​(@PathParam("dataset")
                                                      DatasetArg<?> datasetArg,
                                                      @QueryParam("filter") @DefaultValue("false")
                                                      Boolean filterData)
        Retrieves the data for the given dataset.

        The returned TSV format contains the following columns:

        • Probe
        • Sequence
        • GeneSymbol (optional)
        • GeneName (optional)
        • GemmaId (optional)
        • NCBIid (optional)
        followed by one column per sample.

        Note: Additional gene information is only available if the corresponding platform's annotations has been dumped on-disk.

        Parameters:
        datasetArg - can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.
        filterData - return filtered the expression data.

      • getDatasetProcessedExpression

        @GET
@Path("/{dataset}/data/processed")
@Produces("text/tab-separated-values; charset=UTF-8")
public javax.ws.rs.core.Response getDatasetProcessedExpression​(@PathParam("dataset")
                                                               DatasetArg<?> datasetArg)
        Retrieve processed expression data.

        The payload is transparently compressed via a Content-Encoding header and streamed to avoid dumping the whole payload in memory.

      • getDatasetRawExpression

        @GET
@Path("/{dataset}/data/raw")
@Produces("text/tab-separated-values; charset=UTF-8")
public javax.ws.rs.core.Response getDatasetRawExpression​(@PathParam("dataset")
                                                         DatasetArg<?> datasetArg,
                                                         @QueryParam("quantitationType")
                                                         QuantitationTypeArg<?> quantitationTypeArg)
        Retrieve raw expression data.

        The payload is transparently compressed via a Content-Encoding header and streamed to avoid dumping the whole payload in memory.

      • getDatasetDesign

        @GET
@Path("/{dataset}/design")
@Produces("text/tab-separated-values; charset=UTF-8")
public javax.ws.rs.core.Response getDatasetDesign​(@PathParam("dataset")
                                                  DatasetArg<?> datasetArg)
        Retrieves the design for the given dataset.
        Parameters:
        datasetArg - can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

      • getDatasetHasBatchInformation

        @GET
@Secured("GROUP_ADMIN")
@Path("/{dataset}/hasbatch")
@Produces("application/json")
public ResponseDataObject<Boolean> getDatasetHasBatchInformation​(@PathParam("dataset")
                                                                 DatasetArg<?> datasetArg)
        Indicate if the experiment has batch information.

        This does not imply that the batch information is usable. This will be true even if there is only one batch. It does not reflect the presence or absence of a batch effect.

      • getDatasetSvd

        @GET
@Path("/{dataset}/svd")
@Produces("application/json")
public ResponseDataObject<ubic.gemma.rest.DatasetsWebService.SimpleSVDValueObject> getDatasetSvd​(@PathParam("dataset")
                                                                                                 DatasetArg<?> datasetArg)
        Retrieves the design for the given dataset.
        Parameters:
        datasetArg - can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

      • getDatasetExpressionForGenesInTaxa

        @GET
@Path("/{datasets}/expressions/taxa/{taxa}/genes/{genes}")
@Produces("application/json")
public ResponseDataObject<List<ExperimentExpressionLevelsValueObject>> getDatasetExpressionForGenesInTaxa​(@PathParam("datasets")
                                                                                                          DatasetArrayArg datasets,
                                                                                                          @PathParam("taxa")
                                                                                                          TaxonArg<?> taxonArg,
                                                                                                          @PathParam("genes")
                                                                                                          GeneArrayArg genes,
                                                                                                          @QueryParam("keepNonSpecific") @DefaultValue("false")
                                                                                                          Boolean keepNonSpecific,
                                                                                                          @QueryParam("consolidate")
                                                                                                          ExpLevelConsolidationArg consolidate)
        Retrieves the expression levels of given genes on given datasets.
        Parameters:
        datasets - a list of dataset identifiers separated by commas (','). The identifiers can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

        You can combine various identifiers in one query, but an invalid identifier will cause the call to yield an error.

        taxonArg - a taxon to retrieve gene identifiers from
        genes - a list of gene identifiers, separated by commas (','). Identifiers can be one of NCBI ID, Ensembl ID or official symbol. NCBI ID is the most efficient (and guaranteed to be unique) identifier. Official symbol will return a random homologue. Use one of the IDs to specify the correct taxon - if the gene taxon does not match the taxon of the given datasets, expression levels for that gene will be missing from the response.

        You can combine various identifiers in one query, but an invalid identifier will cause the call to yield an error.

        keepNonSpecific - whether to keep elements that are mapped to multiple genes.
        consolidate - whether genes with multiple elements should consolidate the information. The options are:
        • pickmax: only return the vector that has the highest expression (mean over all its bioAssays)
        • pickvar: only return the vector with highest variance of expression across its bioAssays
        • average: create a new vector that will average the bioAssay values from all vectors

      • getDatasetExpressionPca

        @GET
@Path("/{datasets}/expressions/pca")
@Produces("application/json")
public ResponseDataObject<List<ExperimentExpressionLevelsValueObject>> getDatasetExpressionPca​(@PathParam("datasets")
                                                                                               DatasetArrayArg datasets,
                                                                                               @QueryParam("component") @DefaultValue("1")
                                                                                               Integer component,
                                                                                               @QueryParam("limit") @DefaultValue("100")
                                                                                               LimitArg limit,
                                                                                               @QueryParam("keepNonSpecific") @DefaultValue("false")
                                                                                               Boolean keepNonSpecific,
                                                                                               @QueryParam("consolidate")
                                                                                               ExpLevelConsolidationArg consolidate)
        Retrieves the expression levels of genes highly expressed in the given component on given datasets.
        Parameters:
        datasets - a list of dataset identifiers separated by commas (','). The identifiers can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

        You can combine various identifiers in one query, but an invalid identifier will cause the call to yield an error.

        limit - maximum amount of returned gene-probe expression level pairs.
        component - the pca component to limit the results to.
        keepNonSpecific - whether to keep elements that are mapped to multiple genes.
        consolidate - whether genes with multiple elements should consolidate the information. The options are:
        • pickmax: only return the vector that has the highest expression (mean over all its bioAssays)
        • pickvar: only return the vector with highest variance of expression across its bioAssays
        • average: create a new vector that will average the bioAssay values from all vectors

      • getDatasetDifferentialExpression

        @GET
@Path("/{datasets}/expressions/differential")
@Produces("application/json")
public ResponseDataObject<List<ExperimentExpressionLevelsValueObject>> getDatasetDifferentialExpression​(@PathParam("datasets")
                                                                                                        DatasetArrayArg datasets,
                                                                                                        @QueryParam("diffExSet")
                                                                                                        Long diffExSet,
                                                                                                        @QueryParam("threshold") @DefaultValue("1.0")
                                                                                                        Double threshold,
                                                                                                        @QueryParam("limit") @DefaultValue("100")
                                                                                                        LimitArg limit,
                                                                                                        @QueryParam("keepNonSpecific") @DefaultValue("false")
                                                                                                        Boolean keepNonSpecific,
                                                                                                        @QueryParam("consolidate")
                                                                                                        ExpLevelConsolidationArg consolidate)
        Retrieves the expression levels of genes highly expressed in the given component on given datasets.
        Parameters:
        datasets - a list of dataset identifiers separated by commas (','). The identifiers can either be the ExpressionExperiment ID or its short name (e.g. GSE1234). Retrieval by ID is more efficient. Only datasets that user has access to will be available.

        You can combine various identifiers in one query, but an invalid identifier will cause the call to yield an error.

        diffExSet - the ID of the differential expression set to retrieve the data from.
        threshold - the FDR threshold that the differential expression has to meet to be included in the response.
        limit - maximum amount of returned gene-probe expression level pairs.
        keepNonSpecific - whether to keep elements that are mapped to multiple genes.
        consolidate - whether genes with multiple elements should consolidate the information. The options are:
        • pickmax: only return the vector that has the highest expression (mean over all its bioAssays)
        • pickvar: only return the vector with highest variance of expression across its bioAssays
        • average: create a new vector that will average the bioAssay values from all vectors

      • getDataset

        @GET
@Secured("GROUP_ADMIN")
@Path("/{dataset}/refresh")
@Produces("application/json")
public javax.ws.rs.core.Response getDataset​(@PathParam("dataset")
                                            DatasetArg<?> datasetArg,
                                            @QueryParam("refreshVectors") @DefaultValue("false")
                                            Boolean refreshVectors,
                                            @QueryParam("refreshReports") @DefaultValue("false")
                                            Boolean refreshReports)
        Retrieve a "refreshed" dataset.

        This has the main side effect of refreshing the second-level cache with the contents of the database.