---
title: "cyCONDOR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{cyCONDOR}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

# Getting Started

Here we describe a basic workflow to analyse high-dimensional cytometry data with `cyCONDOR`. More detailed description of all `cyCONDOR` functionalists and visualization tools can be found in the *Articles* section. In this section we will describe how
to load data from a folder of FCS files, how to perform dimensionality reduction and clustering together with some basic visualization of the results.

We start by loading the `cyCONDOR` package.

```{r setup, warning=FALSE, message=FALSE}
library(cyCONDOR)
```

# Loading the data

With `prep_fcd()` you import the `.fcs` files to your R session. The `.fcs` files should all
be stored in a single folder *`data_path`*. Additionally an annotation table text file (*`anno_table`*) has to be provided which contains a column with the file names of the `.fcs` files and optionally addional sample information. This is an example for an *`anno_table`*:

filename          | sample_id         | condition
----------------- | ----------------- | -----------------
exp_x_sample1.fcs | sample1           | treatment
exp_x_sample2.fcs | sample2           | control


**Arguments:**

*`data_path`* = Folder where the `.fcs` files or `.csv` files are stored

*`max_cell`* = Number of cells to use for each file 

*`useCSV`* = Flag if the input are `.csv` files and not `.fcs` 

*`transformation`* = Transformation to perform ("auto_logi", "arcsinh", "clr", "none")

*`remove_param`* = Parameters to be removed from the `fcd`, "inTime" should be kept

*`anno_table`* = Path to the annotation table text file.

*`filename_col`* = Name of the column containing the file name matching with the `.fcs`/`.csv` files


```{r}
condor <- prep_fcd(data_path = "../.test_files/fcs/", 
                    max_cell = 1000, 
                    useCSV = FALSE, 
                    transformation = "auto_logi", 
                    remove_param = c("FSC-H", "SSC-H", "FSC-W", "SSC-W", "Time"), 
                    anno_table = "../.test_files/metadata.csv", 
                    filename_col = "filename"
                   )

class(condor)
```

For more details on data loading, transformation and the general structure of the `fcd` have a look at **`vignette("Data_Loading_and_Transformation")`** and **`vignette("Other_utilities")`**.



# Dimensionality Reduction

To reduce the complexity of the data set, we first perform a principal component analysis (PCA) and use those coordinates for non-linear dimensionality reduction applying e.g. the UMAP or tSNE algorithm. See **`vignette("Dimensionality_Reduction")`** for further details and alternative methods. With this approach, we can visualize the complexity of the data set in the two dimensional space.

## PCA

**Arguments:**

*`fcd`* = Flow cytometry dataset

*`data_slot`* = Data slot to use for the calculation, e.g. `"orig"` or batch corrected `"norm"`

```{r}
condor <- runPCA(fcd = condor, 
                 data_slot = "orig"
                 )
```

## UMAP

**Arguments:**

*`fcd`* = Flow cytometry dataset

*`input type`* = Data to use for the calculation of the UMAP, e.g.
"expr" or "pca"

*`data_slot`* = Data slot to use for the calculation, e.g. `"orig"` or batch corrected `"norm"`

```{r}
condor <- runUMAP(fcd = condor, 
                  input_type = "pca", 
                  data_slot = "orig"
                  )
```

### UMAP Visualization

```{r}
plot_dim_red(fcd= condor,  
             reduction_method = "umap", 
             reduction_slot = "pca_orig", 
             param = "group", 
             title = "UMAP colored by group"
             )
```

## tSNE

**Arguments:**

*`fcd`* = Flow cytometry dataset

*`input type`* = Data to use for the calculation, e.g. `"expr"` or `"pca"`

*`data_slot`* = Data slot to use for the calculation, e.g. `"orig"` or batch corrected `"norm"`

```{r}
condor <- runtSNE(fcd = condor, 
                  input_type = "pca", 
                  data_slot = "orig"
                  )
```

### tSNE visualization

```{r}
plot_dim_red(fcd= condor,  
             reduction_method = "tSNE", 
             reduction_slot = "pca_orig", 
             param = "group", 
             title = "tSNE colored by group"
             )
```

# Clustering

We group cells with similar marker expression applying the Phenograph or FlowSOM clustering algorithms. For more details see **`vignette("Clustering_and_cell_annotation")`**.

## Phenograph clustering

**Arguments:**

*`fcd`* = Flow cytometry dataset

*`input type`* = Data to use for the calculation of the UMAP, e.g. `"pca"`

*`data_slot`* = Data slot to use for the calculation, e.g. `"orig"` or `"norm"`

*`k`* = K value used for clustering

```{r}
condor <- runPhenograph(fcd = condor, 
                        input_type = "pca", 
                        data_slot = "orig", 
                        k = 60
                        )
```

### Visualize Phenograph clustering

```{r}
plot_dim_red(fcd= condor,  
             reduction_method = "umap", 
             reduction_slot = "pca_orig", 
             cluster_slot = "phenograph_pca_orig_k_60",
             param = "Phenograph",
             title = "UMAP colored by Phenograph clustering"
             )
```

## FlowSOM clustering

**Arguments:**

*`fcd`* = Flow cytometry dataset

*`input type`* = Data to use for the calculation, e.g. `"expr"` or `"pca"`.

*`data_slot`* = Data slot to use for the calculation, e.g. `"orig"` or `"norm"`

*`nClusters`* = Number of final clusters


```{r}
condor <- runFlowSOM(fcd = condor, 
                     input_type = "expr", 
                     data_slot = "orig", 
                     nClusters = 5
                     )
```

### Visualize FlowSOM clustering

```{r}
plot_dim_red(fcd= condor,  
             reduction_method = "umap", 
             reduction_slot = "pca_orig", 
             cluster_slot = "FlowSOM_expr_orig_k_5",
             param = "FlowSOM",
             title = "UMAP colored by FlowSOM clustering"
             )
```



# Data visualization 

We can now further visualize our data set to compare the different experimental groups. Below are some examples, for more visualization options check out **`vignette("Data_Visualization")`**.

## Confusion Matrix

**Arguments:**

*`fcd`* = Flow cytometry data set

*`cluster_slot`* = String specifying which clustering slot to use to find variable specified in `cluster_var`

*`cluster_var`* = String specifying variable name in `cluster_slot` that identifies cell population labels to be used (e.g. clusters, metaclusters or predicted labels)

*`group_var`* = String indicating variable name in cell_anno that defines grouping variable to be used (x-axis), e.g. group or sample ID

```{r, fig.width=7, fig.height=3}
plot_confusion_HM(fcd = condor,
                  cluster_slot = "phenograph_pca_orig_k_60", 
                  cluster_var = "Phenograph",
                  group_var = "group", 
                  size = 30
                  )
```

## Barplot of cluster frequencies

**Arguments:**

*`fcd`* = Flow cytometry data set

*`cluster_slot`* = String specifying which clustering slot to use to find variable specified in `cluster_var`

*`cluster_var`* = String specifying variable name in `cluster_slot` that identifies cell population labels to be used (e.g. clusters, metaclusters or predicted labels)

*`group_var`* = String indicating variable name in cell_anno that defines grouping variable to be used (x-axis), e.g. group or sample ID

*`title`* = Title of the plot, default is "Counts"

```{r}
plot_frequency_barplot(fcd = condor,
                    cluster_slot = "phenograph_pca_orig_k_60",
                    cluster_var = "Phenograph",
                    group_var = "group",
                    title = "Stacked barplot of cluster frequencies" 
                    )
```

## Heatmap of protein expression 

**Arguments:**

*`fcd`* = Flow cytometry data set

*`expr_slot`* =  `expr_slot` from which to take marker expression values, default is `"orig"`

*`cluster_slot`* = String specifying which clustering slot to use to find variable specified in `cluster_var`

*`cluster_var`* = String specifying variable name in `cluster_slot` that identifies cell population labels to be used (e.g. clusters, metaclusters or predicted labels)

```{r, fig.height=5}
plot_marker_HM(fcd = condor,
               expr_slot = "orig",
               marker_to_exclude = c("FSC-A","SSC-A"),
               cluster_slot = "phenograph_pca_orig_k_60",
               cluster_var = "Phenograph"
               )
```

## Boxplot of cluster frequency 

**Arguments:**

*`fcd`* = Flow cytometry data set

*`cluster_slot`* = String specifying which clustering slot to use to find variable specified in `cluster_var`

*`cluster_var`* = String specifying variable name in `cluster_slot` that identifies cell population labels to be used (e.g. clusters, metaclusters or predicted labels)

*`sample_var`* = String indicating variable name in cell_anno that defines sample IDs to be used

*`group_var`* = String indicating variable name in cell_anno that should be used to group samples in `sample_var`

*`numeric`* = Logical, if `TRUE` numeric levels in cluster_var are ordered in increasing order and "Cluster_" is pasted before number, if `FALSE` alphabetical ordering is applied.

```{r, fig.width=2, fig.height=4}
plots <- plot_frequency_boxplot(fcd = condor,
                                cluster_slot = "phenograph_pca_orig_k_60", 
                                cluster_var = "Phenograph",
                                sample_var = "sample_ID", 
                                group_var = "group", 
                                numeric = T
                                )

plots$Cluster_7
```



# What is next?

Depending on your data set `cyCONDOR` offers various options to continue with your analysis:

  - Try out more data visualization options: **`vignette("Data_Visualization")`**
  
  - Exploratory differential analysis of cell population frequencies and marker expression: **`vignette("Differential_Analysis"`**
  
  - See **`vignette("Batch_correction")`** for more details on how to handle batch effects within `cyCONDOR`
  
  - If you have a high number of samples recorded with the same panel, check out our data projection workflow for conveniently assigning clusters and metaclusters: **`vignette("Data_Projection")`**
  
  - Train a machine learning classifier: **`vignette("Machine_learning_classifier)`**
  
  - Calculate cell trajectories and pseudotime: **`vignette("Pseudotime_analysis")`**
  
  - Import your FlowJo gating hierarchy into your `fcd`: **`vignette("Load_a_FlowJo_workspace.Rmd")`**
  


# Session Info

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

info
```


