Class DatasetArgService

java.lang.Object

ubic.gemma.rest.util.args.AbstractEntityArgService<ExpressionExperiment, ExpressionExperimentService>

ubic.gemma.rest.util.args.DatasetArgService

All Implemented Interfaces:

EntityArgService<ExpressionExperiment, ExpressionExperimentService>

@Service
public class DatasetArgService
extends AbstractEntityArgService<ExpressionExperiment, ExpressionExperimentService>

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	DatasetArgService.DesignChangeResult	Result of an applyDesignChange call.

Field Summary

Fields inherited from class AbstractEntityArgService

service

Constructor Summary

Constructors

Constructor	Description
DatasetArgService(ExpressionExperimentService service, SearchService searchService, ArrayDesignService adService, BioAssayService baService, OutlierDetectionService outlierDetectionService, PublicationAssociationService publicationAssociationService)

Method Summary

Modifier and Type	Method	Description
DatasetArgService.DesignChangeResult	applyDesignChange(DatasetArg<?> arg, ExperimentalDesignValueObject proposed, boolean force)	Validate and apply a proposed design replacement.
Set<AnnotationValueObject>	getAnnotations(DatasetArg<?> arg)
Set<AnnotationValueObject>	getAnnotations(DatasetArg<?> arg, boolean includeFreeText)
CursorPage<ExpressionExperimentValueObject>	getBlacklistedDatasetsByCursor(Filters filters, Cursor cursor, int limit)	Cursor-mode counterpart to ExpressionExperimentService.loadBlacklistedValueObjects(Filters, Sort, int, int).
CursorPage<ExpressionExperimentValueObject>	getDatasetsByCursor(Filters filters, Cursor cursor, int limit)	Cursor-mode counterpart to SecurableFilteringVoEnabledService.loadValueObjects(Filters, Sort, int, int).
Long	getEntityId(DatasetArg<?> datasetArg)	Retrieve an ID for a given dataset argument.
List<String>	getExcludedUris(StringArrayArg excludedUrisArg, boolean excludeFreeText, boolean excludeUncategorizedTerms)	Obtain a list of exclude URIs from an argument containing excluded URIs.
ExperimentalDesignValueObject	getExperimentalDesign(DatasetArg<?> arg)
Filters	getFilters(FilterArg<ExpressionExperiment> filterArg)	Obtain a Filters from a filter argument.
Filters	getFilters(FilterArg<ExpressionExperiment> filterArg, Collection<OntologyTerm> mentionedTerms, Collection<OntologyTerm> inferredTerms)
Filters	getFilters(FilterArg<ExpressionExperiment> filterArg, Collection<OntologyTerm> mentionedTerms, Collection<OntologyTerm> inferredTerms, long timeout, TimeUnit timeUnit)
Set<Long>	getIdsForSearchQuery(QueryArg query, Collection<Throwable> queryWarnings)	Shortcut for extracting the result IDs from getResultsForSearchQuery(QueryArg, Highlighter, Collection).
Set<Long>	getIdsForSearchQuery(QueryArg query, Map<Long,Double> scoreById, Collection<Throwable> queryWarnings)	Shortcut for extracting the result IDs and scores from getResultsForSearchQuery(QueryArg, Highlighter, Collection).
List<ArrayDesignValueObject>	getOriginalPlatforms(DatasetArg<?> arg)	The platforms the dataset was originally submitted on, before any switch — empty when it was never switched.
List<ArrayDesignValueObject>	getPlatforms(DatasetArg<?> arg)	Retrieves the Platforms of the Dataset that this argument represents.
QuantitationType	getPreferredQuantitationType(DatasetArg<?> datasetArg)
List<DatasetPublicationValueObject>	getPublications(DatasetArg<?> datasetArg)
List<DatasetPublicationValueObject>	getPublications(DatasetArg<?> datasetArg, boolean includeRejected)	A dataset's publications, each carrying the evidenced claim that attaches it.
Set<QuantitationTypeValueObject>	getQuantitationTypes(DatasetArg<?> arg)	Retrieve a dataset with quantitation type initialized.
List<SearchResult<ExpressionExperiment>>	getResultsForSearchQuery(QueryArg query, Highlighter highlighter, Collection<Throwable> queryWarnings)	Obtain the search results for a given query and highlighter.
List<BioAssayValueObject>	getSamples(DatasetArg<?> arg, boolean includePredictedOutliers)
List<BioAssayValueObject>	getSamples(DatasetArg<?> datasetArg, QuantitationType qt, boolean includePredictedOutliers)	Obtain a collection of BioAssays that represent the experiments samples for a particular quantitation type.
CursorPage<BioAssayValueObject>	getSamplesByCursor(DatasetArg<?> arg, Cursor cursor, int limit, boolean includePredictedOutliers)	Cursor-mode counterpart to getSamples(DatasetArg, boolean) for the GET /datasets/{dataset}/samples endpoint — see CURSOR_PAGINATION_STEP1_PLAN.md step 1k.
ExpressionExperimentSubSet	getSubSet(DatasetArg<?> datasetArg, Long subSetId)
List<Long>	getSubSetGroupIds(DatasetArg<?> datasetArg, ExpressionExperimentSubSet subset)
List<ExpressionExperimentSubSet>	getSubSets(DatasetArg<?> datasetArg)
List<BioAssayValueObject>	getSubSetSamples(DatasetArg<?> datasetArg, Long subSetId, boolean includePredictedOutliers)
CursorPage<BioAssayValueObject>	getSubSetSamplesByCursor(DatasetArg<?> datasetArg, Long subSetId, Cursor cursor, int limit, boolean includePredictedOutliers)	Cursor-mode counterpart to getSubSetSamples(DatasetArg, Long, boolean) for the GET /datasets/{dataset}/subSets/{subSet}/samples endpoint — see CURSOR_PAGINATION_STEP1_PLAN.md step 1u (the subset-scoped twin of step 1k for GET /datasets/{dataset}/samples).
Map<ExpressionExperimentSubSet, List<Long>>	getSubSetsGroupIds(DatasetArg<?> datasetArg)
void	populateOutliers(ExpressionExperiment ee, Collection<BioAssayValueObject> bioAssayValueObjects)	Set BioAssayValueObject.getPredictedOutlier() from the median-correlation algorithm.
DesignPreflightReport	previewDesignChange(DatasetArg<?> arg, ExperimentalDesignValueObject proposed)	Run a dry-run preflight for the proposed design replacement.
DesignPreflightReport	previewDesignChange(DatasetArg<?> arg, ExperimentalDesignValueObject proposed, DesignCommitPlan plan)	Run a dry-run preflight for a design commit, counting the bindings plan defers to a second apply pass.

Methods inherited from class AbstractEntityArgService

checkEntity, entityArgValueOf, getArgsByPropertyName, getElementClass, getEntities, getEntities, getEntity, getFilterableProperties, getFilterablePropertyAllowedValues, getFilterablePropertyConfigAttributes, getFilterablePropertyDescription, getFilterablePropertyResolvableAllowedValuesLabels, getFilterablePropertyType, getFilters, getFilters, getSort, isFilterablePropertyDeprecated, isFilterablePropertyUsingSubquery

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DatasetArgService

@Autowired
public DatasetArgService(ExpressionExperimentService service,
 SearchService searchService,
 ArrayDesignService adService,
 BioAssayService baService,
 OutlierDetectionService outlierDetectionService,
 PublicationAssociationService publicationAssociationService)

Method Details

getEntityId

@Nullable
public Long getEntityId(DatasetArg<?> datasetArg)

Retrieve an ID for a given dataset argument.

getExcludedUris

@Nullable
public List<String> getExcludedUris(@Nullable
 StringArrayArg excludedUrisArg,
 boolean excludeFreeText,
 boolean excludeUncategorizedTerms)

Obtain a list of exclude URIs from an argument containing excluded URIs.

Parameters:

excludedUrisArg - argument containing excluded URIs or null if unspecified

excludeFreeText - if true, null will be included in the returned list which will result in the exclusion of free-text categories or terms

Returns:

null if excludedUrisArg is null and excludeFreeText is false, otherwise a list of excluded URIs

getFilters

public Filters getFilters(FilterArg<ExpressionExperiment> filterArg)
                   throws jakarta.ws.rs.BadRequestException,
jakarta.ws.rs.ServiceUnavailableException

Description copied from interface: EntityArgService

Obtain a Filters from a filter argument.

Specified by:

getFilters in interface EntityArgService<ExpressionExperiment, ExpressionExperimentService>

Overrides:

getFilters in class AbstractEntityArgService<ExpressionExperiment, ExpressionExperimentService>

Throws:

jakarta.ws.rs.BadRequestException - if the argument is malformed

jakarta.ws.rs.ServiceUnavailableException

getFilters

public Filters getFilters(FilterArg<ExpressionExperiment> filterArg,
 @Nullable
 Collection<OntologyTerm> mentionedTerms,
 @Nullable
 Collection<OntologyTerm> inferredTerms)
                   throws jakarta.ws.rs.ServiceUnavailableException

Throws:

jakarta.ws.rs.ServiceUnavailableException

getFilters

public Filters getFilters(FilterArg<ExpressionExperiment> filterArg,
 @Nullable
 Collection<OntologyTerm> mentionedTerms,
 @Nullable
 Collection<OntologyTerm> inferredTerms,
 long timeout,
 TimeUnit timeUnit)
                   throws TimeoutException

Throws:

TimeoutException

getDatasetsByCursor

public CursorPage<ExpressionExperimentValueObject> getDatasetsByCursor(@Nullable
 Filters filters,
 @Nullable
 Cursor cursor,
 int limit)

Cursor-mode counterpart to SecurableFilteringVoEnabledService.loadValueObjects(Filters, Sort, int, int). Always sorts by ascending id (the primary key, indexed and unique) — see CURSOR_PAGINATION_STEP1_PLAN.md step 1d. The caller's Filters still applies (so endpoints like GET /taxa/{taxon}/datasets can pre-compose the taxon.id = ? constraint into the filter and pass it through). The user's ?sort= arg is intentionally not honoured in cursor mode because the DAO currently restricts cursors to single-component id sorts (recce sec. 3.4 — to be lifted in phase B once the index audit is complete).

getBlacklistedDatasetsByCursor

public CursorPage<ExpressionExperimentValueObject> getBlacklistedDatasetsByCursor(@Nullable
 Filters filters,
 @Nullable
 Cursor cursor,
 int limit)

Cursor-mode counterpart to ExpressionExperimentService.loadBlacklistedValueObjects(Filters, Sort, int, int). Always sorts by ascending id (the primary key, indexed and unique) — see CURSOR_PAGINATION_STEP1_PLAN.md step 1t (the EE-targeted twin of step 1h). The caller's Filters still applies on top of the blacklist short-name/accession predicate composed inside the DAO. The user's ?sort= arg is intentionally not honoured in cursor mode because the DAO currently restricts cursors to single-component id sorts (recce §3.4 — to be lifted in phase B once the index audit is complete).

getResultsForSearchQuery

public List<SearchResult<ExpressionExperiment>> getResultsForSearchQuery(QueryArg query,
 @Nullable
 Highlighter highlighter,
 @Nullable
 Collection<Throwable> queryWarnings)
                                                                  throws jakarta.ws.rs.BadRequestException,
jakarta.ws.rs.ServiceUnavailableException,
jakarta.ws.rs.InternalServerErrorException

Obtain the search results for a given query and highlighter.

Parameters:

highlighter - a highlighter to use for the query or null to ignore

queryWarnings - a collection that will receive warnings regarding the full-text query

Throws:

jakarta.ws.rs.BadRequestException - if the query is empty

jakarta.ws.rs.ServiceUnavailableException - if the search times out

jakarta.ws.rs.InternalServerErrorException - for any other search-related exceptions

getIdsForSearchQuery

public Set<Long> getIdsForSearchQuery(QueryArg query,
 Map<Long,Double> scoreById,
 @Nullable
 Collection<Throwable> queryWarnings)

Shortcut for extracting the result IDs and scores from getResultsForSearchQuery(QueryArg, Highlighter, Collection).

See Also:

• getResultsForSearchQuery(QueryArg, Highlighter, Collection)

getIdsForSearchQuery

public Set<Long> getIdsForSearchQuery(QueryArg query,
 @Nullable
 Collection<Throwable> queryWarnings)

Shortcut for extracting the result IDs from getResultsForSearchQuery(QueryArg, Highlighter, Collection).

See Also:

• getResultsForSearchQuery(QueryArg, Highlighter, Collection)

getQuantitationTypes

public Set<QuantitationTypeValueObject> getQuantitationTypes(DatasetArg<?> arg)

Retrieve a dataset with quantitation type initialized.

getPlatforms

public List<ArrayDesignValueObject> getPlatforms(DatasetArg<?> arg)

Retrieves the Platforms of the Dataset that this argument represents.

Returns:

a collection of Platforms that the dataset represented by this argument is in.

getOriginalPlatforms

public List<ArrayDesignValueObject> getOriginalPlatforms(DatasetArg<?> arg)

The platforms the dataset was originally submitted on, before any switch — empty when it was never switched. Plural because a dataset's assays need not have come from one submitted platform.

getSamples

public List<BioAssayValueObject> getSamples(DatasetArg<?> arg,
 boolean includePredictedOutliers)

Returns:

a collection of BioAssays that represent the experiments samples.

Uses the narrow ExpressionExperimentService.thawBioAssays(ExpressionExperiment) thaw rather than the broader thawLite: the BioAssayValueObject ctor only reads the per-assay shape (array design, original platform, biomaterial-with-factor-values), so warming the nine EE-level lazy collections that thawLite touches (publications, otherParts, factors, factor values, quantitation types, characteristics, accession, mean-variance, geeq, curationDetails) is dead pre-fetch on this code path. See SAMPLES_DESIGN_PERF_RECCE.md for the measurement.

getSamplesByCursor

public CursorPage<BioAssayValueObject> getSamplesByCursor(DatasetArg<?> arg,
 @Nullable
 Cursor cursor,
 int limit,
 boolean includePredictedOutliers)

Cursor-mode counterpart to getSamples(DatasetArg, boolean) for the GET /datasets/{dataset}/samples endpoint — see CURSOR_PAGINATION_STEP1_PLAN.md step 1k. Walks the EE→bioAssays association directly via BioAssayService.loadValueObjectsByCursorForExpressionExperiment(ExpressionExperiment, Cursor, int); always sorts by ascending id (the primary key, indexed and unique). The thawLite step is intentionally omitted in cursor mode because the keyset HQL fetches the assays directly (it doesn't iterate ee.getBioAssays() as a lazy collection). Outliers are populated post-hoc on the returned page's data, matching the offset-mode VO shape.

Note: this branch is taken only when no quantitationType / useProcessedQuantitationType parameter is supplied — see DatasetsWebService.getDatasetSamples(DatasetArg, QuantitationTypeArg, boolean, CursorArg, LimitArg, ExcludeArg, boolean). The QT-narrowed variants intentionally remain offset-mode (they sort by BioAssay::getName and apply a BioAssayDimension restriction that is not expressible as an id-only cursor).

getSamples

public List<BioAssayValueObject> getSamples(DatasetArg<?> datasetArg,
 QuantitationType qt,
 boolean includePredictedOutliers)

Obtain a collection of BioAssays that represent the experiments samples for a particular quantitation type.

getAnnotations

public Set<AnnotationValueObject> getAnnotations(DatasetArg<?> arg)

Returns:

a collection of Annotations value objects that represent the experiments annotations.

getAnnotations

public Set<AnnotationValueObject> getAnnotations(DatasetArg<?> arg,
 boolean includeFreeText)

Parameters:

includeFreeText - also return tags with no ontology mapping

Returns:

a collection of Annotations value objects that represent the experiments annotations.

getExperimentalDesign

public ExperimentalDesignValueObject getExperimentalDesign(DatasetArg<?> arg)

Returns:

the full structured experimental design (factors, factor values with statements, and biomaterial to factor-value assignments).

previewDesignChange

public DesignPreflightReport previewDesignChange(DatasetArg<?> arg,
 ExperimentalDesignValueObject proposed)

Run a dry-run preflight for the proposed design replacement.

previewDesignChange

public DesignPreflightReport previewDesignChange(DatasetArg<?> arg,
 ExperimentalDesignValueObject proposed,
 DesignCommitPlan plan)

Run a dry-run preflight for a design commit, counting the bindings plan defers to a second apply pass. For the curation commit, which is the one caller that has a plan; a payload that can only name factor values that already exist goes through previewDesignChange(DatasetArg, ExperimentalDesignValueObject).

See Also:

• ExpressionExperimentService.previewDesignChange(ExpressionExperiment, ExperimentalDesignValueObject, DesignCommitPlan)

applyDesignChange

public DatasetArgService.DesignChangeResult applyDesignChange(DatasetArg<?> arg,
 ExperimentalDesignValueObject proposed,
 boolean force)

Validate and apply a proposed design replacement.

When the preflight report carries blockers, returns DatasetArgService.DesignChangeResult.blocked(DesignPreflightReport) without mutating state. When the preflight report has no blockers but requires consent — it would delete differential-expression analyses, or strand a subset on deleted factor values — and force is false, returns DatasetArgService.DesignChangeResult.forceRequired. Otherwise applies the change and returns DatasetArgService.DesignChangeResult.ok(ExperimentalDesignValueObject) with the fresh design VO.

getSubSets

public List<ExpressionExperimentSubSet> getSubSets(DatasetArg<?> datasetArg)

getSubSet

public ExpressionExperimentSubSet getSubSet(DatasetArg<?> datasetArg,
 Long subSetId)

getSubSetGroupIds

public List<Long> getSubSetGroupIds(DatasetArg<?> datasetArg,
 ExpressionExperimentSubSet subset)

getSubSetsGroupIds

public Map<ExpressionExperimentSubSet, List<Long>> getSubSetsGroupIds(DatasetArg<?> datasetArg)

getSubSetSamples

public List<BioAssayValueObject> getSubSetSamples(DatasetArg<?> datasetArg,
 Long subSetId,
 boolean includePredictedOutliers)

getSubSetSamplesByCursor

public CursorPage<BioAssayValueObject> getSubSetSamplesByCursor(DatasetArg<?> datasetArg,
 Long subSetId,
 @Nullable
 Cursor cursor,
 int limit,
 boolean includePredictedOutliers)

Cursor-mode counterpart to getSubSetSamples(DatasetArg, Long, boolean) for the GET /datasets/{dataset}/subSets/{subSet}/samples endpoint — see CURSOR_PAGINATION_STEP1_PLAN.md step 1u (the subset-scoped twin of step 1k for GET /datasets/{dataset}/samples). Walks the ExpressionExperimentSubSet→bioAssays association directly via BioAssayService.loadValueObjectsByCursorForSubSet(ExpressionExperimentSubSet, Cursor, int); always sorts by ascending id (primary key, indexed and unique).

The assay→source-assay mapping (used to populate the VO's sourceBioAssayId) is built post-hoc against the subset's source experiment so the VO shape matches offset mode exactly. Outliers are also populated post-hoc on the returned page.

Subset existence is validated up-front (mirroring the offset variant's NotFoundException on unknown subSetId); the getSubSetByIdWithCharacteristicsAndBioAssays loader is reused intentionally — it returns the subset entity with its source experiment populated, which the source-assay map and outlier helpers both need, without forcing the full subset.bioAssays collection to materialise (Hibernate lazy-loads on access).

getPreferredQuantitationType

public QuantitationType getPreferredQuantitationType(DatasetArg<?> datasetArg)

getPublications

public List<DatasetPublicationValueObject> getPublications(DatasetArg<?> datasetArg)

getPublications

public List<DatasetPublicationValueObject> getPublications(DatasetArg<?> datasetArg,
 boolean includeRejected)

A dataset's publications, each carrying the evidenced claim that attaches it.

Parameters:

includeRejected - also emit the publications that were considered and ruled out for this dataset. Off by default: a rejection is a record of a decision, not a publication of the dataset, and anything listing "the dataset's papers" must not pick them up by accident. Turn it on to see what a publication finder should not re-propose.

populateOutliers

public void populateOutliers(ExpressionExperiment ee,
 Collection<BioAssayValueObject> bioAssayValueObjects)

Set BioAssayValueObject.getPredictedOutlier() from the median-correlation algorithm.

This is expensive and does not scale with the number of VOs passed in: it loads the experiment's whole N×N sample-correlation matrix (SampleCoexpressionMatrix.coexpressionMatrix, a LONGBLOB) to compute the prediction, so the cost is set by the correlation analysis, not by the page size. On experiments whose matrix is dimensioned over subset assays it reaches ~100 MB and the request exceeds the 60 s proxy timeout; because OutlierDetectionService.getOutlierDetails(ExpressionExperiment) caches only on completion, a request that times out never populates the cache and the next one pays the same cost again.

Callers therefore opt in. The persisted, curator-facing BioAssayValueObject.isOutlier() flag is read from BIO_ASSAY.IS_OUTLIER by the VO constructor and is always present at no cost; only the algorithmic prediction needs this.