Skip to contents

Keep a subset of a cohort's subjects or assays

Source: R/filter.R
cohort_filter.Rd

Filters a cohort's subject table and sample map together, so the result stays a valid Cohort. Any loaded analysis table that has a subject_id column is filtered to match; the registry and paths are kept as they are.

Usage

cohort_filter(
  cohort,
  ...,
  subject_ids = NULL,
  assays = NULL,
  drop_sample_ids = NULL,
  drop_empty = TRUE
)

Arguments

cohort

A Cohort object.

...

Data-masked filter expressions evaluated against cohort@subject_tbl, as in dplyr::filter(). Optional.

subject_ids

Optional character vector. Keep only these subject ids.

assays

Optional character vector. Keep only sample rows with these assays.

drop_sample_ids

Optional character vector. Remove sample rows with these sample ids. Unlike subject_ids and assays, which both keep a match, this one drops a match: it is the only way to remove specific samples without also naming every sample to keep.

drop_empty

Logical. When TRUE (default), a subject left with no sample after the assays/drop_sample_ids filters is also removed from subject_tbl. When FALSE, such a subject is kept with no rows in sample_map.

Value

A new Cohort. The cache is reset, since it can hold loaded data or a translation result computed for the full set of subjects.

Details

The five ways to narrow a cohort combine: ... and subject_ids both narrow subject_tbl, and assays/drop_sample_ids narrow sample_map. sample_map is always restricted to the subjects that remain in subject_tbl after ... and subject_ids, regardless of drop_empty.

See also

subjects(), samples(), cohort_new()

Examples

data(example_cohort)

# By an expression on subject_tbl
cohort_filter(example_cohort, species == "rat")
#> 
#> ── Cohort: Cross-species genomics comparison 
#> • 2 subjects (2 rat)
#> • 6 samples (4 wes, 2 scrna)
#> ℹ Extra sample columns: fastq_1, fastq_2

# By explicit ids
cohort_filter(example_cohort, subject_ids = c("RAT001", "MOUSE001"))
#> 
#> ── Cohort: Cross-species genomics comparison 
#> • 2 subjects (1 mouse, 1 rat)
#> • 6 samples (4 wes, 2 scrna)
#> ℹ Extra sample columns: fastq_1, fastq_2

# By assay, dropping subjects left with no sample
cohort_filter(example_cohort, assays = "scrna")
#> 
#> ── Cohort: Cross-species genomics comparison 
#> • 4 subjects (2 mouse, 2 rat)
#> • 4 samples (4 scrna)
#> ℹ Extra sample columns: fastq_1, fastq_2

# By excluding specific sample ids (e.g. samples that failed QC)
bad_id <- samples(example_cohort)$sample_id[[1]]
cohort_filter(example_cohort, drop_sample_ids = bad_id)
#> 
#> ── Cohort: Cross-species genomics comparison 
#> • 4 subjects (2 mouse, 2 rat)
#> • 11 samples (7 wes, 4 scrna)
#> ℹ Extra sample columns: fastq_1, fastq_2