---
title: "Plotting #4: Iterative Plotting Functions"
date: 'Compiled: `r format(Sys.Date(), "%B %d, %Y")`'
output: rmarkdown::html_vignette
theme: united
df_print: kable
vignette: >
  %\VignetteIndexEntry{Plotting #4: Iterative Plotting Functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
***

<style>
p.caption {
  font-size: 0.9em;
}
</style>
 
```{r setup, include=FALSE}
all_times <- list()  # store the time for each chunk
knitr::knit_hooks$set(time_it = local({
  now <- NULL
  function(before, options) {
    if (before) {
      now <<- Sys.time()
    } else {
      res <- difftime(Sys.time(), now, units = "secs")
      all_times[[options$label]] <<- res
    }
  }
}))
knitr::opts_chunk$set(
  tidy = TRUE,
  tidy.opts = list(width.cutoff = 95),
  message = FALSE,
  warning = FALSE,
  time_it = TRUE
)
```


# Iterative Plotting Functions  
Often times creating large numbers of plots (either as individual files or in single PDF) is part of normal workflow.  This process can be simplified by creating the plots in looping functions.  

scCustomize simplifies this process by allowing for the creation of many plots in multiple formats with self-contained loop functions.

## Iterative functions available are:  

* `Iterate_PC_Loading_Plots()`: Plots PC Heatmap and Top Loading Genes for specified number of PCs.
* `Iterate_FeaturePlot_scCustom()`: `FeaturePlot_scCustom()` for all genes in gene list.  See [Marker Identification Vignette](https://samuel-marsh.github.io/scCustomize/articles/Markers_and_Cluster_Annotation.html#extract-the-top-n-marker-genes-per-cluster-identity-treatment-etc-1) for special use case with named vector gene lists.
* `Iterate_VlnPlot_scCustom()`: Plots `VlnPlot_scCustom()` for all genes in gene list.
* `Iterate_Plot_Density_Custom()` Plots single gene density plots for all genes in gene list.
* `Iterate_Plot_Density_Joint()` Plots the joint density plots for all vectors of genes from a list of vectors.
* `Iterate_DimPlot_bySample()`: Plots `DimPlot()` one sample at a time.
* `Iterate_Cluster_Highlight_Plot()`: Plots `Cluster_Highlight_Plot()` for all clusters in given object.
* `Iterate_Meta_Highlight_Plot()` Plots `Meta_Highlight_Plot()` for all levels within given meta data column.

## Required Parameters  
Most functions that begin with `Iterate_` have shared parameters that are used to dictate file location, file name, and file type.
*The exception is `Iterate_PC_Loading_Plots()` which is slightly different (see manual entry for more info.)

* `file_path`: path to directory to save file (can also include file prefix if desired)
* `file_name`: file name (if saving as single file) or suffix to add to file name (if saving individual files the meta data variable or gene will be part of file name automatically)
* `file_type`: accepts one of following options: ".pdf", ".png", ".tiff", ".jpeg", ".svg".
* `single_pdf`: logical. Whether or not to save all plots to single PDF file vs. one file per variable/gene.
* `dpi`: Dots per inch (only relevant for non-vector based file formats).
  
## Added functionality  
`Iterate_FeaturePlot_scCustom()` has an additional helpful feature when the list of features provided is named.  See [Marker Identification & Cluster Annotation Vignette](https://samuel-marsh.github.io/scCustomize/articles/Markers_and_Cluster_Annotation.html#extract-the-top-n-marker-genes-per-cluster-identity-treatment-etc-1).

When provided with named vector such as the output from `Extract_Top_Markers()` then `Iterate_FeaturePlot_scCustom()` can detect the names and add them either to the title of the plot (if `single_pdf = TRUE`) or the file names if `FALSE`.
```{r eval=FALSE}
Iterate_FeaturePlot_scCustom(seurat_object = pbmc, gene_list = top_5_presto, single_pdf = T)
```

<center>
<img src="../reference/figures/assets/Iterate_named_plots.png" width=49%>  

*Example plot showing the gene name and additional name of the plot.*
</center>
  
## Optional Parameters  
Remaining parameters for each function are similar or identical to their non-iterative counterparts.
  
    
## More Information  
For more info on each functions and optional parameters check out the manual entry using `?Function_Name` or browsing the [Reference Manual](https://samuel-marsh.github.io/scCustomize/reference/index.html#section-iterative-plotting-functions)
