Package ubic.gemma.rest

Class TaxaWebService

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

    • Field Detail

      • log

        protected static final org.apache.commons.logging.Log log

    • Method Detail

      • getTaxa

        @GET
@Produces("application/json")
public ResponseDataObject<List<TaxonValueObject>> getTaxa()
        Lists all available taxa. Does not offer any advanced filtering or sorting functionality. The reason for this is that Taxa are a relatively small set of objects that rarely change.

      • getTaxaByIds

        @GET
@Path("/{taxa}")
@Produces("application/json")
public ResponseDataObject<List<TaxonValueObject>> getTaxaByIds​(@PathParam("taxa")
                                                               TaxonArrayArg taxaArg)
        Retrieves single taxon based on the given identifier.
        Parameters:
        taxaArg - a list of identifiers, separated by commas (','). Identifiers can be the any of taxon ID, scientific name, common name. It is recommended to use ID for efficiency.

        Only datasets that user has access to will be available.

        Do not combine different identifiers in one query.

      • getTaxonGenesOverlappingChromosome

        @GET
@Path("/{taxon}/chromosomes/{chromosome}/genes")
@Produces("application/json")
public ResponseDataObject<List<GeneValueObject>> getTaxonGenesOverlappingChromosome​(@PathParam("taxon")
                                                                                    TaxonArg<?> taxonArg,
                                                                                    @PathParam("chromosome")
                                                                                    String chromosomeName,
                                                                                    @QueryParam("strand")
                                                                                    String strand,
                                                                                    @QueryParam("start")
                                                                                    Long start,
                                                                                    @QueryParam("size")
                                                                                    Integer size)
        Finds genes overlapping a given region.
        Parameters:
        taxonArg - can either be Taxon ID or one of its string identifiers: scientific name, common name. It is recommended to use the ID for efficiency.
        chromosomeName - - eg: 3, 21, X
        strand - - '+' or '-'. Defaults to '+'. (WIP, currently does not do anything).
        start - - start of the region (nucleotide position).
        size - - size of the region (in nucleotides).
        Returns:
        GeneValue objects of the genes in the region.

      • getTaxonGenes

        @GET
@Path("/{taxon}/genes/{gene}")
@Produces("application/json")
public ResponseDataObject<List<GeneValueObject>> getTaxonGenes​(@PathParam("taxon")
                                                               TaxonArg<?> taxonArg,
                                                               @PathParam("gene")
                                                               GeneArg<?> geneArg)
        Retrieves genes matching the identifier on the given taxon.
        Parameters:
        taxonArg - can either be Taxon ID or one of its string identifiers: scientific name, common name. It is recommended to use the ID for efficiency.
        geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

      • getGenesEvidenceInTaxon

        @GET
@Path("/{taxon}/genes/{gene}/evidence")
@Produces("application/json")
@Deprecated
public ResponseDataObject<List<GeneEvidenceValueObject>> getGenesEvidenceInTaxon​(@PathParam("taxon")
                                                                                 TaxonArg<?> taxonArg,
                                                                                 @PathParam("gene")
                                                                                 GeneArg<?> geneArg)
        Deprecated.
        Retrieves gene evidence for the gene on the given taxon.
        Parameters:
        taxonArg - can either be Taxon ID or one of its string identifiers: scientific name, common name. It is recommended to use the ID for efficiency.
        geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

      • getGeneLocationsInTaxon

        @GET
@Path("/{taxon}/genes/{gene}/locations")
@Produces("application/json")
public ResponseDataObject<List<PhysicalLocationValueObject>> getGeneLocationsInTaxon​(@PathParam("taxon")
                                                                                     TaxonArg<?> taxonArg,
                                                                                     @PathParam("gene")
                                                                                     GeneArg<?> geneArg)
        Retrieves gene location for the gene on the given taxon.
        Parameters:
        taxonArg - can either be Taxon ID or one of its string identifiers: scientific name, common name. It is recommended to use the ID for efficiency.
        geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

      • getTaxonDatasets

        @GET
@Path("/{taxon}/datasets")
@Produces("application/json")
public FilteredAndPaginatedResponseDataObject<ExpressionExperimentValueObject> getTaxonDatasets​(@PathParam("taxon")
                                                                                                TaxonArg<?> taxonArg,
                                                                                                @QueryParam("filter") @DefaultValue("")
                                                                                                FilterArg<ExpressionExperiment> filter,
                                                                                                @QueryParam("offset") @DefaultValue("0")
                                                                                                OffsetArg offset,
                                                                                                @QueryParam("limit") @DefaultValue("20")
                                                                                                LimitArg limit,
                                                                                                @QueryParam("sort") @DefaultValue("+id")
                                                                                                SortArg<Taxon> sort)
        Retrieves datasets for the given taxon. Filtering allowed exactly like in DatasetsWebService#getDatasets(String, FilterArg, OffsetArg, LimitArg, SortArg).
        Parameters:
        taxonArg - can either be Taxon ID, Taxon NCBI ID, or one of its string identifiers: scientific name, common name. It is recommended to use the ID for efficiency.

      • getTaxonPhenotypes

        @GET
@Path("/{taxon}/phenotypes")
@Produces("application/json")
public ResponseDataObject<Collection<?>> getTaxonPhenotypes​(@PathParam("taxon")
                                                            TaxonArg<?> taxonArg,
                                                            @QueryParam("editableOnly") @DefaultValue("false")
                                                            Boolean editableOnly,
                                                            @QueryParam("tree") @DefaultValue("false")
                                                            Boolean tree)
        Loads all phenotypes for the given taxon. Unfortunately, pagination is not possible as the phenotypes are loaded in a tree structure.

        TODO: We need to split this in two methods because otherwise we cannot infer the type this endpoint is producing and provide a backward compatible switch.

        Parameters:
        taxonArg - the taxon to list the phenotypes for.
        editableOnly - whether to only list editable phenotypes.
        tree - whether the returned structure should be an actual tree (nested JSON objects). Default is false - the tree is flattened and the edges of the tree are stored in the values of the value object.
        Returns:
        a list of Simple Tree value objects allowing a reconstruction of a tree, or an actual tree structure of TreeCharacteristicValueObjects, if the

      • findCandidateGenesInTaxon

        @GET
@Path("/{taxon}/phenotypes/candidates")
@Produces("application/json")
@Deprecated
public ResponseDataObject<Set<GeneEvidenceValueObject>> findCandidateGenesInTaxon​(@PathParam("taxon")
                                                                                  TaxonArg<?> taxonArg,
                                                                                  @QueryParam("phenotypes")
                                                                                  StringArrayArg phenotypes,
                                                                                  @QueryParam("editableOnly") @DefaultValue("false")
                                                                                  Boolean editableOnly)
        Deprecated.
        Given a set of phenotypes, return all genes associated with them.
        Parameters:
        taxonArg - the taxon to list the genes for.
        editableOnly - whether to only list editable genes.
        phenotypes - phenotype value URIs separated by commas.
        Returns:
        a list of genes associated with given phenotypes.