diff --git a/src/main/java/org/cbioportal/service/CopyNumberSegmentService.java b/src/main/java/org/cbioportal/service/CopyNumberSegmentService.java index f251e710474..43a811b380e 100644 --- a/src/main/java/org/cbioportal/service/CopyNumberSegmentService.java +++ b/src/main/java/org/cbioportal/service/CopyNumberSegmentService.java @@ -9,17 +9,96 @@ public interface CopyNumberSegmentService { - List getCopyNumberSegmentsInSampleInStudy(String studyId, String sampleId, String chromosome, String projection, - Integer pageSize, Integer pageNumber, String sortBy, - String direction) - throws SampleNotFoundException, StudyNotFoundException; + /** + * Retrieves sorted list of copy number segments for a specific sample + * within a specific study. This method allows filtering by chromosome and projection. + * + * @param studyId the ID of the study + * @param sampleId the ID of the sample + * @param chromosome the chromosome to filter by + * @param projection the projection type + * @param pageSize the number of records per page + * @param pageNumber the page number to retrieve + * @param sortBy the field to sort the results by + * @param direction the sort direction (e.g., ASC or DESC) + * @return a list of copy number segments + * @throws SampleNotFoundException if the sample is not found + * @throws StudyNotFoundException if the study is not found + */ + List getCopyNumberSegmentsInSampleInStudy( + String studyId, + String sampleId, + String chromosome, + String projection, + Integer pageSize, + Integer pageNumber, + String sortBy, + String direction + ) throws SampleNotFoundException, StudyNotFoundException; - BaseMeta getMetaCopyNumberSegmentsInSampleInStudy(String studyId, String sampleId, String chromosome) - throws SampleNotFoundException, StudyNotFoundException; + /** + * Retrieves metadata for copy number segments for a specific sample + * within a specific study, filtered by chromosome. + * + * @param studyId the ID of the study + * @param sampleId the ID of the sample + * @param chromosome the chromosome to filter by + * @return the metadata for the copy number segments + * @throws SampleNotFoundException if the sample is not found + * @throws StudyNotFoundException if the study is not found + */ + BaseMeta getMetaCopyNumberSegmentsInSampleInStudy( + String studyId, + String sampleId, + String chromosome + ) throws SampleNotFoundException, StudyNotFoundException; - List fetchCopyNumberSegments(List studyIds, List sampleIds, String chromosome, String projection); + /** + * Fetches copy number segments for multiple studies and samples, + * filtered by chromosome and projection. + * + * @param studyIds a list of study IDs + * @param sampleIds a list of sample IDs + * @param chromosome the chromosome to filter by + * @param projection the projection type + * @return a list of copy number segments + */ + List fetchCopyNumberSegments( + List studyIds, + List sampleIds, + String chromosome, + String projection + ); - BaseMeta fetchMetaCopyNumberSegments(List studyIds, List sampleIds, String chromosome); + /** + * Fetches metadata for copy number segments for multiple studies and samples, + * filtered by chromosome. + * + * @param studyIds a list of study IDs + * @param sampleIds a list of sample IDs + * @param chromosome the chromosome to filter by + * @return the metadata for the copy number segments + */ + BaseMeta fetchMetaCopyNumberSegments( + List studyIds, + List sampleIds, + String chromosome + ); - List getCopyNumberSegmentsBySampleListId(String studyId, String sampleListId, String chromosome, String projection); + /** + * Retrieves copy number segments for a list of samples within a study, + * filtered by chromosome and projection. + * + * @param studyId the ID of the study + * @param sampleListId the ID of the sample list + * @param chromosome the chromosome to filter by + * @param projection the projection type + * @return a list of copy number segments + */ + List getCopyNumberSegmentsBySampleListId( + String studyId, + String sampleListId, + String chromosome, + String projection + ); } diff --git a/src/main/java/org/cbioportal/service/DiscreteCopyNumberService.java b/src/main/java/org/cbioportal/service/DiscreteCopyNumberService.java index 7dbd1e8a5a9..7d7495cd900 100644 --- a/src/main/java/org/cbioportal/service/DiscreteCopyNumberService.java +++ b/src/main/java/org/cbioportal/service/DiscreteCopyNumberService.java @@ -8,46 +8,147 @@ public interface DiscreteCopyNumberService { - List getDiscreteCopyNumbersInMolecularProfileBySampleListId(String molecularProfileId, - String sampleListId, - List entrezGeneIds, - List alterationTypes, - String projection) - throws MolecularProfileNotFoundException; - - BaseMeta getMetaDiscreteCopyNumbersInMolecularProfileBySampleListId(String molecularProfileId, String sampleListId, - List entrezGeneIds, - List alterationTypes) - throws MolecularProfileNotFoundException; - - List fetchDiscreteCopyNumbersInMolecularProfile(String molecularProfileId, - List sampleIds, - List entrezGeneIds, - List alterationTypes, - String projection) - throws MolecularProfileNotFoundException; - - List getDiscreteCopyNumbersInMultipleMolecularProfiles(List molecularProfileIds, - List sampleIds, - List entrezGeneIds, - List alterationTypes, - String projection); - - List getDiscreteCopyNumbersInMultipleMolecularProfilesByGeneQueries(List molecularProfileIds, - List sampleIds, - List geneQueries, - String projection); - - BaseMeta fetchMetaDiscreteCopyNumbersInMolecularProfile(String molecularProfileId, List sampleIds, - List entrezGeneIds, List alterationTypes) - throws MolecularProfileNotFoundException; - - List getSampleCountByGeneAndAlterationAndSampleIds(String molecularProfileId, - List sampleIds, - List entrezGeneIds, - List alterations) - throws MolecularProfileNotFoundException; - - List fetchCopyNumberCounts(String molecularProfileId, List entrezGeneIds, - List alterations) throws MolecularProfileNotFoundException; -} + /** + * Retrieves discrete copy number data for a specific molecular profile based on a sample list ID. + * Allows filtering by gene IDs, alteration types, and projection type. + * + * @param molecularProfileId the ID of the molecular profile + * @param sampleListId the ID of the sample list + * @param entrezGeneIds a list of Entrez gene IDs to filter by + * @param alterationTypes a list of alteration types to filter by + * @param projection the projection type + * @return a list of discrete copy number data + * @throws MolecularProfileNotFoundException if the molecular profile is not found + */ + List getDiscreteCopyNumbersInMolecularProfileBySampleListId( + String molecularProfileId, + String sampleListId, + List entrezGeneIds, + List alterationTypes, + String projection + ) throws MolecularProfileNotFoundException; + + /** + * Retrieves metadata for discrete copy number data in a specific molecular profile + * using a sample list ID and filters by gene IDs and alteration types. + * + * @param molecularProfileId the ID of the molecular profile + * @param sampleListId the ID of the sample list + * @param entrezGeneIds a list of Entrez gene IDs to filter by + * @param alterationTypes a list of alteration types to filter by + * @return metadata for the discrete copy number data + * @throws MolecularProfileNotFoundException if the molecular profile is not found + */ + BaseMeta getMetaDiscreteCopyNumbersInMolecularProfileBySampleListId( + String molecularProfileId, + String sampleListId, + List entrezGeneIds, + List alterationTypes + ) throws MolecularProfileNotFoundException; + + /** + * Fetches discrete copy number data for a specific molecular profile based on sample IDs. + * Filters by gene IDs, alteration types, and projection type. + * + * @param molecularProfileId the ID of the molecular profile + * @param sampleIds a list of sample IDs + * @param entrezGeneIds a list of Entrez gene IDs to filter by + * @param alterationTypes a list of alteration types to filter by + * @param projection the projection type + * @return a list of discrete copy number data + * @throws MolecularProfileNotFoundException if the molecular profile is not found + */ + List fetchDiscreteCopyNumbersInMolecularProfile( + String molecularProfileId, + List sampleIds, + List entrezGeneIds, + List alterationTypes, + String projection + ) throws MolecularProfileNotFoundException; + + /** + * Retrieves discrete copy number data for multiple molecular profiles based on sample IDs. + * Filters by gene IDs, alteration types, and projection type. + * + * @param molecularProfileIds a list of molecular profile IDs + * @param sampleIds a list of sample IDs + * @param entrezGeneIds a list of Entrez gene IDs to filter by + * @param alterationTypes a list of alteration types to filter by + * @param projection the projection type + * @return a list of discrete copy number data + */ + List getDiscreteCopyNumbersInMultipleMolecularProfiles( + List molecularProfileIds, + List sampleIds, + List entrezGeneIds, + List alterationTypes, + String projection + ); + + /** + * Retrieves discrete copy number data for multiple molecular profiles using gene queries. + * + * @param molecularProfileIds a list of molecular profile IDs + * @param sampleIds a list of sample IDs + * @param geneQueries a list of gene filter queries + * @param projection the projection type + * @return a list of discrete copy number data + */ + List getDiscreteCopyNumbersInMultipleMolecularProfilesByGeneQueries( + List molecularProfileIds, + List sampleIds, + List geneQueries, + String projection + ); + + /** + * Fetches metadata for discrete copy number data in a specific molecular profile based on sample IDs. + * Filters by gene IDs and alteration types. + * + * @param molecularProfileId the ID of the molecular profile + * @param sampleIds a list of sample IDs + * @param entrezGeneIds a list of Entrez gene IDs to filter by + * @param alterationTypes a list of alteration types to filter by + * @return metadata for the discrete copy number data + * @throws MolecularProfileNotFoundException if the molecular profile is not found + */ + BaseMeta fetchMetaDiscreteCopyNumbersInMolecularProfile( + String molecularProfileId, + List sampleIds, + List entrezGeneIds, + List alterationTypes + ) throws MolecularProfileNotFoundException; + + /** + * Retrieves sample counts grouped by gene and alteration type for specific sample IDs + * in a molecular profile. + * + * @param molecularProfileId the ID of the molecular profile + * @param sampleIds a list of sample IDs + * @param entrezGeneIds a list of Entrez gene IDs + * @param alterations a list of alteration types + * @return a list of copy number counts by gene + * @throws MolecularProfileNotFoundException if the molecular profile is not found + */ + List getSampleCountByGeneAndAlterationAndSampleIds( + String molecularProfileId, + List sampleIds, + List entrezGeneIds, + List alterations + ) throws MolecularProfileNotFoundException; + + /** + * Fetches copy number counts grouped by gene and alteration type for a specific molecular profile. + * + * @param molecularProfileId the ID of the molecular profile + * @param entrezGeneIds a list of Entrez gene IDs + * @param alterations a list of alteration types + * @return a list of copy number counts + * @throws MolecularProfileNotFoundException if the molecular profile is not found + */ + List fetchCopyNumberCounts( + String molecularProfileId, + List entrezGeneIds, + List alterations + ) throws MolecularProfileNotFoundException; +} \ No newline at end of file diff --git a/src/main/java/org/cbioportal/service/GenericAssayService.java b/src/main/java/org/cbioportal/service/GenericAssayService.java index 8f85a4fd179..0ea02ca7024 100644 --- a/src/main/java/org/cbioportal/service/GenericAssayService.java +++ b/src/main/java/org/cbioportal/service/GenericAssayService.java @@ -7,18 +7,73 @@ import org.cbioportal.service.exception.MolecularProfileNotFoundException; public interface GenericAssayService { - - List getGenericAssayMetaByStableIdsAndMolecularIds(List stableIds, List molecularProfileIds, String projection); - List getGenericAssayData(String molecularProfileId, String sampleListId, - List genericAssayStableIds, String projection) - throws MolecularProfileNotFoundException; + /** + * Retrieves metadata for generic assay data based on a list of stable IDs and molecular profile IDs. + * Allows filtering by projection type. + * + * @param stableIds a list of stable IDs for the generic assays + * @param molecularProfileIds a list of molecular profile IDs + * @param projection the projection type + * @return a list of generic assay metadata + */ + List getGenericAssayMetaByStableIdsAndMolecularIds( + List stableIds, + List molecularProfileIds, + String projection + ); - List fetchGenericAssayData(String molecularProfileId, List sampleIds, - List genericAssayStableIds, String projection) - throws MolecularProfileNotFoundException; + /** + * Retrieves generic assay data for a specific molecular profile and sample list. + * Filters by a list of stable IDs and allows specifying a projection type. + * + * @param molecularProfileId the ID of the molecular profile + * @param sampleListId the ID of the sample list + * @param genericAssayStableIds a list of stable IDs for the generic assays + * @param projection the projection type + * @return a list of generic assay data + * @throws MolecularProfileNotFoundException if the molecular profile is not found + */ + List getGenericAssayData( + String molecularProfileId, + String sampleListId, + List genericAssayStableIds, + String projection + ) throws MolecularProfileNotFoundException; - List fetchGenericAssayData(List molecularProfileIds, List sampleIds, - List genericAssayStableIds, String projection) - throws MolecularProfileNotFoundException; + /** + * Fetches generic assay data for a specific molecular profile and a list of sample IDs. + * Filters by a list of stable IDs and allows specifying a projection type. + * + * @param molecularProfileId the ID of the molecular profile + * @param sampleIds a list of sample IDs + * @param genericAssayStableIds a list of stable IDs for the generic assays + * @param projection the projection type + * @return a list of generic assay data + * @throws MolecularProfileNotFoundException if the molecular profile is not found + */ + List fetchGenericAssayData( + String molecularProfileId, + List sampleIds, + List genericAssayStableIds, + String projection + ) throws MolecularProfileNotFoundException; + + /** + * Fetches generic assay data for multiple molecular profiles and sample IDs. + * Filters by a list of stable IDs and allows specifying a projection type. + * + * @param molecularProfileIds a list of molecular profile IDs + * @param sampleIds a list of sample IDs + * @param genericAssayStableIds a list of stable IDs for the generic assays + * @param projection the projection type + * @return a list of generic assay data + * @throws MolecularProfileNotFoundException if any of the molecular profiles are not found + */ + List fetchGenericAssayData( + List molecularProfileIds, + List sampleIds, + List genericAssayStableIds, + String projection + ) throws MolecularProfileNotFoundException; } diff --git a/src/main/java/org/cbioportal/service/GenesetHierarchyService.java b/src/main/java/org/cbioportal/service/GenesetHierarchyService.java index 4aea20dab8e..db0ca4cf66f 100644 --- a/src/main/java/org/cbioportal/service/GenesetHierarchyService.java +++ b/src/main/java/org/cbioportal/service/GenesetHierarchyService.java @@ -8,12 +8,62 @@ public interface GenesetHierarchyService { - List fetchGenesetHierarchyInfo(String geneticProfileId, Integer percentile, Double scoreThreshold, Double pvalueThreshold) throws MolecularProfileNotFoundException; + /** + * Fetches gene set hierarchy information for a specific genetic profile. + * Filters results based on percentile, score threshold, and p-value threshold. + * + * @param geneticProfileId the ID of the genetic profile + * @param percentile the percentile threshold to filter gene sets + * @param scoreThreshold the score threshold to filter gene sets + * @param pvalueThreshold the p-value threshold to filter gene sets + * @return a list of gene set hierarchy information + * @throws MolecularProfileNotFoundException if the genetic profile is not found + */ + List fetchGenesetHierarchyInfo( + String geneticProfileId, + Integer percentile, + Double scoreThreshold, + Double pvalueThreshold + ) throws MolecularProfileNotFoundException; - List fetchGenesetHierarchyInfo(String geneticProfileId, Integer percentile, Double scoreThreshold, - Double pvalueThreshold, List sampleIds) throws MolecularProfileNotFoundException; + /** + * Fetches gene set hierarchy information for a specific genetic profile and a list of sample IDs. + * Filters results based on percentile, score threshold, and p-value threshold. + * + * @param geneticProfileId the ID of the genetic profile + * @param percentile the percentile threshold to filter gene sets + * @param scoreThreshold the score threshold to filter gene sets + * @param pvalueThreshold the p-value threshold to filter gene sets + * @param sampleIds a list of sample IDs to filter the results + * @return a list of gene set hierarchy information + * @throws MolecularProfileNotFoundException if the genetic profile is not found + */ + List fetchGenesetHierarchyInfo( + String geneticProfileId, + Integer percentile, + Double scoreThreshold, + Double pvalueThreshold, + List sampleIds + ) throws MolecularProfileNotFoundException; - List fetchGenesetHierarchyInfo(String geneticProfileId, Integer percentile, Double scoreThreshold, - Double pvalueThreshold, String sampleListId) throws MolecularProfileNotFoundException, SampleListNotFoundException; - -} + /** + * Fetches gene set hierarchy information for a specific genetic profile and a sample list ID. + * Filters results based on percentile, score threshold, and p-value threshold. + * + * @param geneticProfileId the ID of the genetic profile + * @param percentile the percentile threshold to filter gene sets + * @param scoreThreshold the score threshold to filter gene sets + * @param pvalueThreshold the p-value threshold to filter gene sets + * @param sampleListId the ID of the sample list to filter the results + * @return a list of gene set hierarchy information + * @throws MolecularProfileNotFoundException if the genetic profile is not found + * @throws SampleListNotFoundException if the sample list is not found + */ + List fetchGenesetHierarchyInfo( + String geneticProfileId, + Integer percentile, + Double scoreThreshold, + Double pvalueThreshold, + String sampleListId + ) throws MolecularProfileNotFoundException, SampleListNotFoundException; +} \ No newline at end of file diff --git a/src/main/java/org/cbioportal/service/SampleListService.java b/src/main/java/org/cbioportal/service/SampleListService.java index bae2e8205e5..97a9d545342 100644 --- a/src/main/java/org/cbioportal/service/SampleListService.java +++ b/src/main/java/org/cbioportal/service/SampleListService.java @@ -9,21 +9,101 @@ public interface SampleListService { - List getAllSampleLists(String projection, Integer pageSize, Integer pageNumber, String sortBy, - String direction); - - BaseMeta getMetaSampleLists(); - - SampleList getSampleList(String sampleListId) throws SampleListNotFoundException; - - List getAllSampleListsInStudy(String studyId, String projection, Integer pageSize, Integer pageNumber, - String sortBy, String direction) throws StudyNotFoundException; - - BaseMeta getMetaSampleListsInStudy(String studyId) throws StudyNotFoundException; - - List getAllSampleIdsInSampleList(String sampleListId) throws SampleListNotFoundException; - - List fetchSampleLists(List sampleListIds, String projection); - - List getAllSampleListsInStudies(List studyIds, String projection); -} + /** + * Retrieves all sample lists with optional pagination, sorting, and projection settings. + * + * @param projection the projection type to specify the fields to include + * @param pageSize the number of sample lists to return per page + * @param pageNumber the page number to retrieve + * @param sortBy the field by which to sort the results + * @param direction the sort direction (e.g., ASC or DESC) + * @return a list of sample lists + */ + List getAllSampleLists( + String projection, + Integer pageSize, + Integer pageNumber, + String sortBy, + String direction + ); + + /** + * Retrieves metadata for all sample lists. + * + * @return metadata for all sample lists + */ + BaseMeta getMetaSampleLists(); + + /** + * Retrieves a specific sample list by its ID. + * + * @param sampleListId the ID of the sample list + * @return the sample list + * @throws SampleListNotFoundException if the sample list is not found + */ + SampleList getSampleList(String sampleListId) throws SampleListNotFoundException; + + /** + * Retrieves all sample lists within a specific study. + * Supports pagination, sorting, and projection settings. + * + * @param studyId the ID of the study + * @param projection the projection type to specify the fields to include + * @param pageSize the number of sample lists to return per page + * @param pageNumber the page number to retrieve + * @param sortBy the field by which to sort the results + * @param direction the sort direction (e.g., ASC or DESC) + * @return a list of sample lists within the study + * @throws StudyNotFoundException if the study is not found + */ + List getAllSampleListsInStudy( + String studyId, + String projection, + Integer pageSize, + Integer pageNumber, + String sortBy, + String direction + ) throws StudyNotFoundException; + + /** + * Retrieves metadata for all sample lists within a specific study. + * + * @param studyId the ID of the study + * @return metadata for the sample lists in the study + * @throws StudyNotFoundException if the study is not found + */ + BaseMeta getMetaSampleListsInStudy(String studyId) throws StudyNotFoundException; + + /** + * Retrieves all sample IDs associated with a specific sample list. + * + * @param sampleListId the ID of the sample list + * @return a list of sample IDs + * @throws SampleListNotFoundException if the sample list is not found + */ + List getAllSampleIdsInSampleList(String sampleListId) throws SampleListNotFoundException; + + /** + * Fetches multiple sample lists by their IDs with optional projection settings. + * + * @param sampleListIds a list of sample list IDs + * @param projection the projection type to specify the fields to include + * @return a list of sample lists + */ + List fetchSampleLists( + List sampleListIds, + String projection + ); + + /** + * Retrieves all sample lists across multiple studies with optional projection settings. + * + * @param studyIds a list of study IDs + * @param projection the projection type to specify the fields to include + * @return a list of sample lists across the specified studies + */ + List getAllSampleListsInStudies( + List studyIds, + String projection + ); + }