Filter to keep only abundant transcripts/genes in a per-category manner

Source: R/keep_identify_abundant_per_category.R

Filters the data to keep only transcripts/genes that are consistently expressed above a threshold across samples. This is a filtering version of identify_abundant_per_category() that removes low-abundance features instead of just marking them.

keep_abundant_per_category(
  .data,
  abundance = assayNames(.data)[1],
  design = NULL,
  formula_design = NULL,
  minimum_counts = 10,
  minimum_proportion = 0.7,
  minimum_count_per_million = NULL,
  minimum_category = 1,
  force = FALSE,
  coerce_design = FALSE,
  ...
)

# S4 method for class 'SummarizedExperiment'
keep_abundant_per_category(
  .data,
  abundance = assayNames(.data)[1],
  design = NULL,
  formula_design = NULL,
  minimum_counts = 10,
  minimum_proportion = 0.7,
  minimum_count_per_million = NULL,
  minimum_category = 1,
  force = FALSE,
  coerce_design = FALSE,
  ...
)

# S4 method for class 'RangedSummarizedExperiment'
keep_abundant_per_category(
  .data,
  abundance = assayNames(.data)[1],
  design = NULL,
  formula_design = NULL,
  minimum_counts = 10,
  minimum_proportion = 0.7,
  minimum_count_per_million = NULL,
  minimum_category = 1,
  force = FALSE,
  coerce_design = FALSE,
  ...
)

Arguments

.data

A `SummarizedExperiment` object containing transcript/gene abundance data

abundance

The name of the transcript/gene abundance column (character, preferred)

design

A design matrix for more complex experimental designs.

formula_design

A formula to generate the design matrix. Overrides `design` when both are provided

minimum_counts

The minimum count threshold for a feature to be considered abundant

minimum_proportion

The minimum proportion of samples in which a feature must be abundant

minimum_count_per_million

...

minimum_category

The minimum number of categories/experimental groups that have sufficient abundance samples.

force

Should existing .abundant column be replaced; defaults to FALSE.

coerce_design

Should non-categorical design matrix be coerced; defaults to FALSE.

...

Further arguments taken for compatibility, but are not used.

Value

Returns a filtered version of the input object containing only the features that passed the abundance threshold criteria.

Details

[Experimental]

This function provides an alternative filtering solution for edgeR's filterByExpr() function to identify consistently expressed features. A feature is considered abundant if it has CPM > minimum_counts in at least minimum_proportion of samples in at least minimum_category experimental groups (defined by design/formula_design).

This function is similar to identify_abundant_per_category() but in addition to writing to an .abundant column, it also filters out the low-abundance features directly.

References

Mangiola, S., Molania, R., Dong, R., Doyle, M. A., & Papenfuss, A. T. (2021). tidybulk: an R tidy framework for modular transcriptomic data analysis. Genome Biology, 22(1), 42. doi:10.1186/s13059-020-02233-7

McCarthy, D. J., Chen, Y., & Smyth, G. K. (2012). Differential expression analysis of multifactor RNA-Seq experiments with respect to biological variation. Nucleic Acids Research, 40(10), 4288-4297. DOI: 10.1093/bioinformatics/btp616

Examples

## Load airway dataset for examples

  data('airway', package = 'airway')
  # Ensure a 'condition' column exists for examples expecting it

    SummarizedExperiment::colData(airway)$condition <- SummarizedExperiment::colData(airway)$dex


# Basic usage
airway |> keep_abundant_per_category()
#> Warning: Neither formula_design and design provided; build design from formula ~ 1 .
#> # A SummarizedExperiment-tibble abstraction: Features=15272 | Samples=8 | 
#> #   Assays=counts
#> #                                 |----------------- COVARIATES ---------------|
#>        .feature  .sample | counts | SampleName cell  dex   albut Run   avgLength
#>        <chr>     <chr>   | <chr>  | <fct>      <fct> <fct> <fct> <fct> <chr>    
#> 1      ENSG0000… SRR103… | 679    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 2      ENSG0000… SRR103… | 467    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 3      ENSG0000… SRR103… | 260    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 4      ENSG0000… SRR103… | 60     | GSM1275862 N613… untrt untrt SRR1… 126      
#> 5      ENSG0000… SRR103… | 3251   | GSM1275862 N613… untrt untrt SRR1… 126      
#>        --------  ------- - ------ - ---------- ----  ---   ----- ---   ---------
#> 122172 ENSG0000… SRR103… | 17     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 122173 ENSG0000… SRR103… | 17     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 122174 ENSG0000… SRR103… | 12     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 122175 ENSG0000… SRR103… | 10     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 122176 ENSG0000… SRR103… | 11     | GSM1275875 N061… trt   untrt SRR1… 98       
#> # ℹ 16 more variables: Experiment <fct>, Sample <fct>, BioSample <fct>,
#> #   condition <fct>, `|` <|>, gene_id <chr>, gene_name <chr>, entrezid <chr>,
#> #   gene_biotype <chr>, gene_seq_start <chr>, gene_seq_end <chr>,
#> #   seq_name <chr>, seq_strand <chr>, seq_coord_system <chr>, symbol <chr>,
#> #   .abundant <chr>

# With custom thresholds
airway |> keep_abundant_per_category(
  minimum_counts = 5,
  minimum_proportion = 0.5
)
#> Warning: Neither formula_design and design provided; build design from formula ~ 1 .
#> # A SummarizedExperiment-tibble abstraction: Features=18032 | Samples=8 | 
#> #   Assays=counts
#> #                                 |----------------- COVARIATES ---------------|
#>        .feature  .sample | counts | SampleName cell  dex   albut Run   avgLength
#>        <chr>     <chr>   | <chr>  | <fct>      <fct> <fct> <fct> <fct> <chr>    
#> 1      ENSG0000… SRR103… | 679    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 2      ENSG0000… SRR103… | 467    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 3      ENSG0000… SRR103… | 260    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 4      ENSG0000… SRR103… | 60     | GSM1275862 N613… untrt untrt SRR1… 126      
#> 5      ENSG0000… SRR103… | 3251   | GSM1275862 N613… untrt untrt SRR1… 126      
#>        --------  ------- - ------ - ---------- ----  ---   ----- ---   ---------
#> 144252 ENSG0000… SRR103… | 12     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 144253 ENSG0000… SRR103… | 6      | GSM1275875 N061… trt   untrt SRR1… 98       
#> 144254 ENSG0000… SRR103… | 11     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 144255 ENSG0000… SRR103… | 10     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 144256 ENSG0000… SRR103… | 14     | GSM1275875 N061… trt   untrt SRR1… 98       
#> # ℹ 16 more variables: Experiment <fct>, Sample <fct>, BioSample <fct>,
#> #   condition <fct>, `|` <|>, gene_id <chr>, gene_name <chr>, entrezid <chr>,
#> #   gene_biotype <chr>, gene_seq_start <chr>, gene_seq_end <chr>,
#> #   seq_name <chr>, seq_strand <chr>, seq_coord_system <chr>, symbol <chr>,
#> #   .abundant <chr>

# Using a factor of interest
airway |> keep_abundant_per_category(formula_design = ~condition)
#> # A SummarizedExperiment-tibble abstraction: Features=16083 | Samples=8 | 
#> #   Assays=counts
#> #                                 |----------------- COVARIATES ---------------|
#>        .feature  .sample | counts | SampleName cell  dex   albut Run   avgLength
#>        <chr>     <chr>   | <chr>  | <fct>      <fct> <fct> <fct> <fct> <chr>    
#> 1      ENSG0000… SRR103… | 679    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 2      ENSG0000… SRR103… | 467    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 3      ENSG0000… SRR103… | 260    | GSM1275862 N613… untrt untrt SRR1… 126      
#> 4      ENSG0000… SRR103… | 60     | GSM1275862 N613… untrt untrt SRR1… 126      
#> 5      ENSG0000… SRR103… | 3251   | GSM1275862 N613… untrt untrt SRR1… 126      
#>        --------  ------- - ------ - ---------- ----  ---   ----- ---   ---------
#> 128660 ENSG0000… SRR103… | 12     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 128661 ENSG0000… SRR103… | 10     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 128662 ENSG0000… SRR103… | 11     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 128663 ENSG0000… SRR103… | 11     | GSM1275875 N061… trt   untrt SRR1… 98       
#> 128664 ENSG0000… SRR103… | 10     | GSM1275875 N061… trt   untrt SRR1… 98       
#> # ℹ 16 more variables: Experiment <fct>, Sample <fct>, BioSample <fct>,
#> #   condition <fct>, `|` <|>, gene_id <chr>, gene_name <chr>, entrezid <chr>,
#> #   gene_biotype <chr>, gene_seq_start <chr>, gene_seq_end <chr>,
#> #   seq_name <chr>, seq_strand <chr>, seq_coord_system <chr>, symbol <chr>,
#> #   .abundant <chr>