Getting Started with omicslog

Installation

You can install the omicslog package from Bioconductor using the following commands:


if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("omicslog")

Introduction

The omicslog package provides logging capabilities for SingleCellExperiment and SummarizedExperiment objects. This is particularly useful for tracking transformations in complex analysis workflows.


library(SummarizedExperiment)
library(tidySummarizedExperiment)
library(omicslog)
data(airway, package="airway")

Pipeline Workflow

Omicslog logs chain operations in a pipeline workflow. Here’s an example of a complete workflow using the airway dataset:


# Complete workflow in a single pipeline
result <- 
  airway |>
  log_start() |>
  filter(dex == "untrt") |>
  select(!albut) |>
  mutate(dex_upper = toupper(dex)) |>
  extract(col = dex,into = "treat") |>
  mutate(Run = tolower(Run)) |> 
  filter(.feature == "ENSG00000000003") |>
  slice(3)


# View the object with the top log history as text
result
#> class: SummarizedExperimentLogged 
#> dim: 1 1 
#> metadata(5): '' latest_filter_scope_report latest_select_scope_report
#>   latest_mutate_scope_report latest_join_scope_report
#> assays(1): counts
#> rownames(1): ENSG00000000003
#> rowData names(10): gene_id gene_name ... seq_coord_system symbol
#> colnames(1): SRR1039516
#> colData names(9): SampleName cell ... BioSample dex_upper
#> 
#> Operation log:
#> [2026-11-18 09:54:16] filter: removed 4 observation(s) (50%), 4 observation(s) remaining
#> [2026-11-18 09:54:16] select: removed 1 (11%), 8 column(s) remaining
#> [2026-11-18 09:54:16] mutate: added 1 new column(s): dex_upper
#> [2026-11-18 09:54:16] extract: extracted 'dex' into column: treat (original removed)
#> [2026-11-18 09:54:16] mutate: modified column(s): Run
#> [2026-11-18 09:54:18] filter: removed 63676 feature(s) (100%), 1 feature(s) remaining

# View the table with the complete log history
print(result@log_history,width=Inf)
#> # A tibble: 7 × 3
#>   Time                Operation
#>   <chr>               <chr>    
#> 1 2026-11-18 09:54:16 filter   
#> 2 2026-11-18 09:54:16 select   
#> 3 2026-11-18 09:54:16 mutate   
#> 4 2026-11-18 09:54:16 extract  
#> 5 2026-11-18 09:54:16 mutate   
#> 6 2026-11-18 09:54:18 filter   
#> 7 2026-11-18 09:54:18 slice    
#>   Message                                                   
#>   <chr>                                                     
#> 1 removed 4 observation(s) (50%), 4 observation(s) remaining
#> 2 removed 1 (11%), 8 column(s) remaining                    
#> 3 added 1 new column(s): dex_upper                          
#> 4 extracted 'dex' into column: treat (original removed)     
#> 5 modified column(s): Run                                   
#> 6 removed 63676 feature(s) (100%), 1 feature(s) remaining   
#> 7 kept 1/4 rows (25.0%); removed 3 rows

Base R Pipeline

Here’s the same workflow implemented using base R operations:


# switch printing to Bioconductor style
options(restore_SummarizedExperiment_show = TRUE)

# Start with logging
result_base <- log_start(airway)

# Filter samples by dex
result_base <- result_base[, colData(result_base)$dex == "untrt"]

# Add new column with uppercase dex
colData(result_base)$dex_upper <- toupper(colData(result_base)$dex)

# Modify Run column to lowercase
colData(result_base)$Run <- tolower(colData(result_base)$Run)

# Filter features
result_base <- result_base[rownames(result_base) == "ENSG00000000003", ]

# View the object with the top log history as text
result_base
#> class: SummarizedExperimentLogged 
#> dim: 1 4 
#> metadata(1): ''
#> assays(1): counts
#> rownames(1): ENSG00000000003
#> rowData names(10): gene_id gene_name ... seq_coord_system symbol
#> colnames(4): SRR1039508 SRR1039512 SRR1039516 SRR1039520
#> colData names(10): SampleName cell ... BioSample dex_upper
#> 
#> Operation log:
#> [2026-11-18 09:54:18] subset: removed 4 observation(s) (50%), 4 observation(s) remaining
#> [2026-11-18 09:54:18] colData<-: added 1 new column(s): dex_upper
#> [2026-11-18 09:54:18] colData<-: modified column 'Run'
#> [2026-11-18 09:54:18] subset: removed 63676 feature(s) (100%), 1 feature(s) remaining

# View the table with the complete log history
print(result_base@log_history,width=Inf)
#> # A tibble: 4 × 3
#>   Time                Operation
#>   <chr>               <chr>    
#> 1 2026-11-18 09:54:18 subset   
#> 2 2026-11-18 09:54:18 colData<-
#> 3 2026-11-18 09:54:18 colData<-
#> 4 2026-11-18 09:54:18 subset   
#>   Message                                                   
#>   <chr>                                                     
#> 1 removed 4 observation(s) (50%), 4 observation(s) remaining
#> 2 added 1 new column(s): dex_upper                          
#> 3 modified column 'Run'                                     
#> 4 removed 63676 feature(s) (100%), 1 feature(s) remaining

SingleCellExperiment Example

omicslog also supports SingleCellExperiment objects. Here’s an example using the pbmc_small dataset:


data(pbmc_small, package="tidySingleCellExperiment")
pbmc_logged <- log_start(pbmc_small)
pbmc_logged <- pbmc_logged[, colData(pbmc_logged)$groups == "g1"]
pbmc_logged <- pbmc_logged[rownames(pbmc_logged) %in% c("ENSG00000198888", "ENSG00000198786"), ]
pbmc_logged
#> class: SingleCellExperimentLogged 
#> dim: 0 44 
#> metadata(0):
#> assays(2): counts logcounts
#> rownames(0):
#> rowData names(5): vst.mean vst.variance vst.variance.expected
#>   vst.variance.standardized vst.variable
#> colnames(44): CATGGCCTGTGCAT TCTGATACACGTGT ... AGTCTTACTTCGGA
#>   CTTGATTGATCTTC
#> colData names(9): orig.ident nCount_RNA ... file ident
#> reducedDimNames(2): PCA TSNE
#> mainExpName: NULL
#> altExpNames(0):
#> 
#> Operation log:
#> [2026-11-18 09:54:18] subset: removed 36 observation(s) (45%), 44 observation(s) remaining
#> [2026-11-18 09:54:18] subset: removed 230 feature(s) (100%), 0 feature(s) remaining

Session Info

#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats4    stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#>  [1] omicslog_0.99.0                 SingleCellExperiment_1.35.2    
#>  [3] ggplot2_4.0.4                   tidyr_1.3.2                    
#>  [5] dplyr_1.2.1                     tidySummarizedExperiment_1.23.2
#>  [7] ttservice_0.5.3                 SummarizedExperiment_1.43.0    
#>  [9] Biobase_2.73.2                  GenomicRanges_1.65.4           
#> [11] Seqinfo_1.3.2                   IRanges_2.47.5                 
#> [13] S4Vectors_0.51.10               BiocGenerics_0.59.13           
#> [15] generics_0.1.4                  MatrixGenerics_1.25.0          
#> [17] matrixStats_1.5.0               BiocStyle_2.41.0               
#> 
#> loaded via a namespace (and not attached):
#>  [1] gtable_0.3.6        xfun_0.62           bslib_0.12.0       
#>  [4] htmlwidgets_1.6.4   lattice_0.23-1      vctrs_0.7.3        
#>  [7] tools_4.6.2         tidyprint_1.1.1     tibble_3.3.1       
#> [10] fansi_1.0.7         pkgconfig_2.0.3     Matrix_1.7-6       
#> [13] data.table_1.18.6.1 RColorBrewer_1.1-3  S7_0.2.2           
#> [16] lifecycle_1.0.5     compiler_4.6.2      farver_2.1.2       
#> [19] stringr_1.6.0       htmltools_0.5.9     sys_3.4.3          
#> [22] buildtools_1.0.0    sass_0.4.10         yaml_2.3.12        
#> [25] plotly_4.12.1       pillar_1.11.1       jquerylib_0.1.4    
#> [28] ellipsis_0.3.3      DelayedArray_0.39.8 cachem_1.1.0       
#> [31] abind_1.4-8         tidyselect_1.2.1    digest_0.6.39      
#> [34] stringi_1.8.9       purrr_1.2.2         maketools_1.3.2    
#> [37] fastmap_1.2.0       grid_4.6.2          cli_3.6.6          
#> [40] SparseArray_1.13.5  magrittr_2.0.5      S4Arrays_1.13.2    
#> [43] utf8_1.2.6          withr_3.0.3         scales_1.4.0       
#> [46] rmarkdown_2.32      XVector_0.53.0      httr_1.4.9         
#> [49] otel_0.3.0          evaluate_1.0.5      knitr_1.52         
#> [52] viridisLite_0.4.3   rlang_1.3.0         glue_1.8.1         
#> [55] BiocManager_1.30.27 jsonlite_2.0.0      R6_2.6.1