--- a
+++ b/R/api_higher.R
@@ -0,0 +1,67 @@
+# FUN: higher API functions
+
+##' Get hosts of XenaHub object
+##' @param x a [XenaHub] object
+##' @importFrom methods slot
+##' @return a character vector contains hosts
+##' @export
+##' @examples xe = XenaGenerate(subset = XenaHostNames == "tcgaHub"); hosts(xe)
+hosts <- function(x) {
+  unname(slot(x, "hosts"))
+}
+##' Get cohorts of XenaHub object
+##' @param x a [XenaHub] object
+##' @return a character vector contains cohorts
+##' @importFrom methods slot
+##' @export
+##' @examples xe = XenaGenerate(subset = XenaHostNames == "tcgaHub"); cohorts(xe)
+cohorts <- function(x) {
+  slot(x, "cohorts")
+}
+##' Get datasets of XenaHub object
+##' @param x a [XenaHub] object
+##' @return a character vector contains datasets
+##' @importFrom methods slot
+##' @export
+##' @examples xe = XenaGenerate(subset = XenaHostNames == "tcgaHub"); datasets(xe)
+datasets <- function(x) {
+  slot(x, "datasets")
+}
+
+##' Get Samples of a XenaHub object according to 'by' and 'how' action arguments
+##'
+##' One is often interested in identifying samples or features present in each data set,
+##' or shared by all data sets, or present in any of several data sets.
+##' Identifying these samples, including samples in arbitrarily chosen data sets.
+##' @param x a [XenaHub] object
+##' @param i default is a empty character, it is used to specify
+##' the host, cohort or dataset by `by` option otherwise
+##' info will be automatically extracted by code
+##' @param by a character specify `by` action
+##' @param how a character specify `how` action
+##' @return a list include samples
+##' @export
+##' @examples
+##' \dontrun{
+##' xe = XenaHub(cohorts = "Cancer Cell Line Encyclopedia (CCLE)")
+##' # samples in each dataset, first host
+##' x = samples(xe, by="datasets", how="each")[[1]]
+##' lengths(x)        # data sets in ccle cohort on first (only) host
+##' }
+
+samples <- function(x,
+                    i = character(),
+                    by = c("hosts", "cohorts", "datasets"),
+                    how = c("each", "any", "all")) {
+  stopifnot(methods::is(x, "XenaHub"), is.character(i))
+  by <- match.arg(by)
+  how <- match.arg(how)
+
+  fun <- switch(
+    match.arg(by),
+    hosts = .samples_by_host,
+    cohorts = .samples_by_cohort,
+    datasets = .samples_by_dataset
+  )
+  fun(x, i, how)
+}