---
title: "tidyprint"
output:
  BiocStyle::html_document:
    toc: true
    toc_float: true
params:
  demo_metadata: true
vignette: >
  %\VignetteIndexEntry{tidyprint}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
knit: >
    (function(x, ...){
        proj_root <- rprojroot::find_package_root_file() |> normalizePath()
        rmarkdown::render(
            x, 
            output_file = "README.md", 
            output_format = "github_document", 
            output_dir = proj_root, 
            knit_root_dir = proj_root, 
            params = list( demo_metadata = FALSE ) 
        )
        rmarkdown::render(
            x,
            output_format = "html_document",
            params = list(
                demo_metadata = TRUE
            )
        )
    })
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>"
)
root_dir <- knitr::opts_knit$get("root.dir")
if (!is.null(root_dir)){
    # This hack fixes the relative image paths. 
    # See https://github.com/rstudio/rmarkdown/issues/2473
    knitr::opts_knit$set(
        output.dir = root_dir
    )
}
proj_root <- rprojroot::find_package_root_file() |> normalizePath() 
# Utility function for figures to force them to have the correct path
find_figure <- function(names){
    rprojroot::find_package_root_file() |>
        file.path("man", "figures", names) 
}
```

<!-- badges: start -->

[![Lifecycle:experimental](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)

<!-- badges: end -->

## Introduction

**tidyprint** is an R package that provides a centralised tidy display strategy for biological data (e.g. SummarizedExperiment) and centralised messaging styles for the `tidyomics` packages. This package addresses a critical need in the Bioconductor ecosystem for improved data visualization and user experience when working with genomic data.


**tidyprint** fills this important gap by:

1. **Enhancing Data Discoverability**: Large genomic datasets often contain millions of features and thousands of samples, making it difficult to quickly understand data structure and content. tidyprint provides intuitive, compact visualizations that help researchers immediately grasp their data's dimensions and key characteristics.

2. **Improving Workflow Integration**: The package seamlessly integrates with existing Bioconductor infrastructure while providing output formats that are familiar to users of modern R data science tools, particularly the tidyverse ecosystem.

3. **Supporting Reproducible Research**: By standardizing how SummarizedExperiment objects are displayed across different analysis contexts, tidyprint promotes consistency in scientific communication and documentation.

4. **Addressing Scalability Challenges**: As genomic datasets continue to grow in size and complexity, traditional display methods become inadequate. tidyprint's adaptive display strategies ensure that users can effectively explore data regardless of scale.

5. **Fostering Community Standards**: The package establishes conventions for data display that can be adopted across the Bioconductor ecosystem, promoting consistency and reducing the learning curve for new users.

### Package Overview

**tidyprint** provides an improved display for SummarizedExperiment objects with a tidy tibble-style format that makes genomic data more accessible and easier to explore.

------------------------------------------------------------------------

## Installation

You need the `remotes` package to install from GitHub. If you don't have it, install it via:

```{r eval=FALSE}
install.packages("remotes")
```

Then install **tidyprint** from GitHub:

```{r eval=FALSE}
remotes::install_github("tidyomics/tidyprint")
```

When available in Bioconductor, install with:

```{r eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("tidyprint")
```

------------------------------------------------------------------------

## Demo

Below is an example demonstrating how to use **tidyprint** with a sample `SummarizedExperiment` object.

### Load Required Packages

```{r load-packages, message = FALSE, warnings = FALSE}
library(dplyr)
library(tidyr)
library(airway)
data(airway)
```

### **SummarizedExperiment**

The standard SummarizedExperiment display:

```{r se_raw-display}
airway 
```

------------------------------------------------------------------------

## Opting In and Out of Tidy Print

By default, **tidyprint** does not change the standard SummarizedExperiment print format. You can opt in to use the tidy print format, and opt out at any time. The setting can be configured for the current R session only, or saved to persist across sessions.

```{r load-tidyprint}
library(tidyprint)
```

```{r turn-off-tidy-print, echo=FALSE, message=FALSE, warning=FALSE}
# This makes sure that the vignette is not affected by the local tidy print setting
tidy_print_off()
```

```{r display-airway}
airway
```

### Opt In to Tidy Print

To enable the tidy print format, use `tidy_print_on()`. By default, this only affects the current R session:

```{r opt-in-session}
# Enable tidy print for current session only
tidy_print_on()
airway  
```

If you want the setting to persist across R sessions, use `remember = TRUE`:

```{r opt-in-persistent, eval=FALSE}
# Enable tidy print and remember the setting
tidy_print_on(remember = TRUE)
airway  # Will display with tidy format in all future sessions
```

When `remember = TRUE`, the setting is saved to a cache file in your R configuration directory, so it will automatically be enabled when you start new R sessions.

### Opt Out of Tidy Print

To return to the standard SummarizedExperiment print format, use `tidy_print_off()`. By default, this only affects the current session:

```{r opt-out-session, eval=FALSE}
# Disable tidy print for current session only
tidy_print_off()
airway  # Will display with standard format
```

To permanently disable tidy print and clear any saved preference:

```{r opt-out-persistent, eval=FALSE}
# Disable tidy print and remember the setting
tidy_print_off(remember = TRUE)
airway  # Will display with standard format in all future sessions
```

## Messaging function

We integrated a messaging function providing standardized, visually appealing messages for packages within the tidyomics ecosystem. It automatically detects the calling package to provide contextualized messaging, such as "tidyprint says" or "tidybulk says", enhancing consistency and readability across projects.

To use the `tidy_message` function:

```{r tidy-message-example}
tidyprint::tidy_message('message to print')
```

You can specify the type of message as

-   info (default)

-   success

-   warning

-   danger

```{r demo-tidy-message}
demo_tidy_message()
```

The above code demonstrates calling `tidy_message` within a package function, showing the name of package.

## Session info

```{r session-info}
sessionInfo()
```
