Class AnnotationsWebService

java.lang.Object
ubic.gemma.rest.AnnotationsWebService
@Service @Path("/annotations") public class AnnotationsWebService extends Object
RESTful interface for annotations.
Author:
tesarst

  • Constructor Details

  • Method Details

    • getAnnotationsParents

      @GET @Path("/parents") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.AnnotationSearchResultValueObject>> getAnnotationsParents(@QueryParam("uri") String termUri, @QueryParam("direct") @DefaultValue("false") boolean direct)

    • getAnnotationsChildren

      @GET @Path("/children") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.AnnotationSearchResultValueObject>> getAnnotationsChildren(@QueryParam("uri") String termUri, @QueryParam("direct") @DefaultValue("false") boolean direct)
      Obtain the children of a given annotation.

      This is plural as we might add support for querying multiple annotations at once in the future.

    • getCanonicalUris

      @GET @Path("/canonicalUris") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.CanonicalUriValueObject>> getCanonicalUris(@QueryParam("uri") @Nullable String uri)
      Every URI Gemma resolves to a different one on read, so a caller can hold the same answer we do instead of a hand-copied subset of it.

    • getAnnotationTerm

      @GET @Path("/term") @Produces("application/json") public ResponseDataObject<AnnotationsWebService.OntologyTermValueObject> getAnnotationTerm(@QueryParam("uri") String termUri, @QueryParam("includeCitationXrefs") @DefaultValue("false") boolean includeCitationXrefs)

    • getAnnotationCategories

      @GET @Path("/categories") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.AnnotationCategoryValueObject>> getAnnotationCategories()
      List the ontology categories allowed for use in characteristics.

    • getAnnotationPredicates

      @GET @Path("/predicates") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.OntologyTermSimpleValueObject>> getAnnotationPredicates()
      List the ontology predicates allowed for use in statements.

    • getAnnotationRelations

      @GET @Path("/relations") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.AnnotationRelationValueObject>> getAnnotationRelations(@QueryParam("subject") @Nullable String subject, @QueryParam("object") @Nullable String object, @QueryParam("predicate") @Nullable String predicate, @QueryParam("subjectCategory") @Nullable String subjectCategory, @QueryParam("objectCategory") @Nullable String objectCategory, @QueryParam("basis") @Nullable String basis, @QueryParam("dataset") @Nullable Long datasetId, @QueryParam("seedDirection") @DefaultValue("OBJECT_TO_SUBJECT") String seedDirection, @QueryParam("taxonId") @Nullable Long taxonId, @QueryParam("excludeDatasets") @Nullable String excludeDatasets, @QueryParam("minSupport") @DefaultValue("0") int minSupport, @QueryParam("minSpecificity") @DefaultValue("0") double minSpecificity, @QueryParam("includeExperimentLevel") @DefaultValue("false") boolean includeExperimentLevel, @QueryParam("maxObjectBreadth") @DefaultValue("0") int maxObjectBreadth, @QueryParam("maxSubjectBreadth") @DefaultValue("-1") int maxSubjectBreadth, @QueryParam("includeRefuted") @DefaultValue("false") boolean includeRefuted, @QueryParam("includeCellTypeSubjects") @DefaultValue("false") boolean includeCellTypeSubjects, @QueryParam("limit") @DefaultValue("50") int limit)
      Relations Gemma knows between annotation terms, with the basis for each.

      Generic on purpose. "Which genotypes stand for Leigh syndrome?" and "which anatomical part does this cell line come from?" are the same query with different terms in it, so there is one endpoint rather than one per relation kind.

      Ask it from either end. subject and object both accept a term, and the row means the same thing whichever end seeded it.

    • getImpliedAnnotations

      @GET @Path("/relations/implies") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.AnnotationRelationValueObject>> getImpliedAnnotations(@QueryParam("from") @Nullable String from, @QueryParam("to") @Nullable String to, @QueryParam("excludeDatasets") @Nullable String excludeDatasets, @QueryParam("basis") @Nullable String basis, @QueryParam("taxonId") @Nullable Long taxonId, @QueryParam("maxObjectBreadth") @DefaultValue("0") int maxObjectBreadth, @QueryParam("includeExperimentLevel") @DefaultValue("false") boolean includeExperimentLevel, @QueryParam("limit") @DefaultValue("100") int limit)
      Is a term already implied by the terms an experiment carries?

      The inhibition question, and it is deliberately not the same endpoint as /annotations/relations. That one ranks and evidences, for a caller that has to CHOOSE a term; this one tests set membership, for a caller deciding whether to SUPPRESS one it was about to write. The distinction is what makes using this knowledge safe at all:

      • Generating a disease from a genotype needs a unique answer. SURF1 carries three germline disease axioms and Trp53 pairs with fifteen diseases in our corpus, so a producer asked to emit one has to pick, and picking wrong writes a false assertion into the database. This is why the curation rule forbids it.
      • Suppressing a redundant tag needs only membership. All three of SURF1's diseases go into the set, and the answer is right whichever one is meant.

      It also fails in the safe direction. A wrong association here suppresses a tag that should have been kept -- a recall miss, visible in scoring and recoverable. The same wrong association used generatively writes a wrong disease onto a dataset.

    • searchAnnotations

      @GET @Path("/search") @Produces("application/json") public AnnotationsWebService.AnnotationSearchResponseDataObject searchAnnotations(@QueryParam("query") @DefaultValue("") StringArrayArg query, @QueryParam("rank") @DefaultValue("lucene") String rank, @QueryParam("limit") @DefaultValue("20") int limit, @QueryParam("prefixes") @DefaultValue("") String prefixesParam, @QueryParam("upstream") @DefaultValue("false") boolean upstream, @QueryParam("exactLabel") @DefaultValue("false") boolean exactLabel, @QueryParam("exact_label") @DefaultValue("false") boolean exactLabelLegacy, @QueryParam("category") @DefaultValue("") String category, @QueryParam("suppressNearMatches") @DefaultValue("false") boolean suppressNearMatches, @QueryParam("suppress_near_matches") @DefaultValue("false") boolean suppressNearMatchesLegacy, @QueryParam("taxon") @Nullable TaxonArg<?> taxonArg, @QueryParam("includeGeneCount") @DefaultValue("false") boolean includeGeneCount, @QueryParam("geneCountMaxTerms") @DefaultValue("50") int geneCountMaxTerms, @QueryParam("includeGenes") @DefaultValue("true") boolean includeGenes, @QueryParam("includeExampleUsage") @DefaultValue("false") boolean includeExampleUsage, @QueryParam("excludeExperiments") @Nullable String excludeExperiments, @QueryParam("includePriorCuration") @DefaultValue("false") boolean includePriorCuration)
      Does a search for annotation tags based on the given string.
      Parameters:
      query - the search query. Either plain text, or an ontology term URI
      Returns:
      response data object with a collection of found terms, each wrapped in a CharacteristicValueObject.
      See Also:

    • searchAnnotationsBatch

      @POST @Path("/search/batch") @Consumes("application/json") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.AnnotationSearchBatchResultValueObject>> searchAnnotationsBatch(@Nullable AnnotationsWebService.AnnotationSearchBatchRequest body)

    • searchAnnotationsByPathQuery

      @GET @Path("/search/{query}") @Produces("application/json") public ResponseDataObject<List<AnnotationsWebService.AnnotationSearchResultValueObject>> searchAnnotationsByPathQuery(@PathParam("query") @DefaultValue("") StringArrayArg query)
      See Also:

    • searchDatasets

      @GET @Path("/search/datasets") @Produces("application/json") public QueriedAndFilteredAndPaginatedResponseDataObject<ExpressionExperimentValueObject> searchDatasets(@QueryParam("query") @DefaultValue("") StringArrayArg query, @QueryParam("filter") @DefaultValue("") FilterArg<ExpressionExperiment> filterArg, @QueryParam("offset") @DefaultValue("0") OffsetArg offset, @QueryParam("limit") @DefaultValue("20") LimitArg limit, @QueryParam("sort") @DefaultValue("+id") SortArg<ExpressionExperiment> sortArg)
      Does a search for datasets containing characteristics matching the given string. If filterArg, offset, limit or sortArg parameters are provided.
      Parameters:
      query - the search query. Either plain text, or an ontology term URI
      Returns:
      response data object with a collection of dataset that match the search query.
      See Also:

    • searchDatasetsByQueryInPath

      @GET @Path("/search/{query}/datasets") @Produces("application/json") public QueriedAndFilteredAndPaginatedResponseDataObject<ExpressionExperimentValueObject> searchDatasetsByQueryInPath(@PathParam("query") @DefaultValue("") StringArrayArg query, @QueryParam("filter") @DefaultValue("") FilterArg<ExpressionExperiment> filterArg, @QueryParam("offset") @DefaultValue("0") OffsetArg offset, @QueryParam("limit") @DefaultValue("20") LimitArg limit, @QueryParam("sort") @DefaultValue("+id") SortArg<ExpressionExperiment> sortArg)

    • searchTaxonDatasets

      @GET @Path("/{taxon}/search/datasets") @Produces("application/json") public QueriedAndFilteredAndPaginatedResponseDataObject<ExpressionExperimentValueObject> searchTaxonDatasets(@PathParam("taxon") TaxonArg<?> taxonArg, @QueryParam("query") @DefaultValue("") StringArrayArg query, @QueryParam("filter") @DefaultValue("") FilterArg<ExpressionExperiment> filter, @QueryParam("offset") @DefaultValue("0") OffsetArg offset, @QueryParam("limit") @DefaultValue("20") LimitArg limit, @QueryParam("sort") @DefaultValue("+id") SortArg<ExpressionExperiment> sort)
      Same as searchDatasets(StringArrayArg, FilterArg, OffsetArg, LimitArg, SortArg) but also filters by taxon.

    • searchTaxonDatasetsByQueryInPath

      @GET @Path("/{taxon}/search/{query}/datasets") @Produces("application/json") public QueriedAndFilteredAndPaginatedResponseDataObject<ExpressionExperimentValueObject> searchTaxonDatasetsByQueryInPath(@PathParam("taxon") TaxonArg<?> taxonArg, @PathParam("query") @DefaultValue("") StringArrayArg query, @QueryParam("filter") @DefaultValue("") FilterArg<ExpressionExperiment> filter, @QueryParam("offset") @DefaultValue("0") OffsetArg offset, @QueryParam("limit") @DefaultValue("20") LimitArg limit, @QueryParam("sort") @DefaultValue("+id") SortArg<ExpressionExperiment> sort)
      See Also:

    • addDatasetAnnotation

      @POST @Path("/datasets/{dataset}/annotations") @Consumes("application/json") @Produces("application/json") @PreAuthorize("hasAuthority('GROUP_CURATOR') or hasAuthority('GROUP_ADMIN')") public jakarta.ws.rs.core.Response addDatasetAnnotation(@PathParam("dataset") DatasetArg<?> datasetArg, @Nullable AnnotationsWebService.AnnotationDto body, @QueryParam("annotationSetId") @Nullable Long annotationSetId)

    • removeDatasetAnnotation

      @DELETE @Path("/datasets/{dataset}/annotations/{annotationId}") @Produces("application/json") @PreAuthorize("hasAuthority('GROUP_CURATOR') or hasAuthority('GROUP_ADMIN')") public jakarta.ws.rs.core.Response removeDatasetAnnotation(@PathParam("dataset") DatasetArg<?> datasetArg, @PathParam("annotationId") Long annotationId)

    • replaceDatasetAnnotations

      @PUT @Path("/datasets/{dataset}/annotations") @Consumes("application/json") @Produces("application/json") @PreAuthorize("hasAuthority('GROUP_CURATOR') or hasAuthority('GROUP_ADMIN')") public ResponseDataObject<AnnotationsWebService.AnnotationReplaceReport> replaceDatasetAnnotations(@PathParam("dataset") DatasetArg<?> datasetArg, @Nullable AnnotationsWebService.AnnotationsReplaceRequest body)