## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  crop = NULL,
  echo = TRUE, fig.width = 3.8, fig.height = 3.8, dpi = 72, out.width = "60%")

## ---- echo=FALSE, fig.height=4.2, fig.width=2.6, fig.align='centre', out.width = "85%"----
knitr::include_graphics("SPIAT-overview.jpg")

## ----install, eval = FALSE----------------------------------------------------
#  if (!requireNamespace("BiocManager", quietly = TRUE)) {
#        install.packages("BiocManager")}
#  # The following initialises usage of Bioc devel
#  BiocManager::install(version="devel")
#  BiocManager::install("SPIAT")

## ----install_github, eval = FALSE---------------------------------------------
#  if (!requireNamespace("devtools", quietly = TRUE)) {
#        install.packages("devtools")}
#  devtools::install_github("TrigosTeam/SPIAT")

## ----"citation"---------------------------------------------------------------
## Citation info
citation("SPIAT")

## ----message=FALSE------------------------------------------------------------
library(SPIAT)

## -----------------------------------------------------------------------------
# Construct a dummy marker intensity matrix
## rows are markers, columns are cells
intensity_matrix <- matrix(c(14.557, 0.169, 1.655, 0.054,
                             17.588, 0.229, 1.188, 2.074, 
                             21.262, 4.206,  5.924, 0.021), nrow = 4, ncol = 3)
# define marker names as rownames
rownames(intensity_matrix) <- c("DAPI", "CD3", "CD4", "AMACR")
# define cell IDs as colnames
colnames(intensity_matrix) <- c("Cell_1", "Cell_2", "Cell_3") 

# Construct a dummy metadata (phenotypes, x/y coordinates)
# the order of the elements in these vectors correspond to the cell order 
# in `intensity matrix`
phenotypes <- c("OTHER",  "AMACR", "CD3,CD4")
coord_x <- c(82, 171, 184)
coord_y <- c(30, 22, 38)

general_format_image <- format_image_to_spe(format = "general", 
                                            intensity_matrix = intensity_matrix,
                                            phenotypes = phenotypes, 
                                            coord_x = coord_x,coord_y = coord_y)

## -----------------------------------------------------------------------------
# phenotypes and cell properties (if available)
colData(general_format_image)
# cell coordinates
spatialCoords(general_format_image)
# marker intensities
assay(general_format_image)

## ----message=FALSE------------------------------------------------------------
raw_inform_data <- system.file("extdata", "tiny_inform.txt.gz", package = "SPIAT")
markers <- c("DAPI", "CD3", "PD-L1", "CD4", "CD8", "AMACR")
locations <- c("Nucleus","Cytoplasm", "Membrane","Cytoplasm","Cytoplasm",
               "Cytoplasm") # The order is the same as `markers`.
formatted_image <- format_image_to_spe(format="inForm", path=raw_inform_data, 
                                       markers=markers, locations=locations)

## ----message=FALSE------------------------------------------------------------
raw_inform_data <- system.file("extdata", "tiny_inform.txt.gz", package = "SPIAT")
markers <- c("DAPI", "CD3", "PD-L1", "CD4", "CD8", "AMACR")
intensity_columns_interest <- c(
  "Nucleus DAPI (DAPI) Mean (Normalized Counts, Total Weighting)",
  "Cytoplasm CD3 (Opal 520) Mean (Normalized Counts, Total Weighting)", 
  "Membrane PD-L1 (Opal 540) Mean (Normalized Counts, Total Weighting)",
  "Cytoplasm CD4 (Opal 620) Mean (Normalized Counts, Total Weighting)",
  "Cytoplasm CD8 (Opal 650) Mean (Normalized Counts, Total Weighting)", 
  "Cytoplasm AMACR (Opal 690) Mean (Normalized Counts, Total Weighting)"
  ) # The order is the same as `markers`.
formatted_image <- format_inform_to_spe(path=raw_inform_data, markers=markers,
                     intensity_columns_interest=intensity_columns_interest)
class(formatted_image) # The formatted image is a SpatialExperiment object
dim(colData(formatted_image))
dim(assay(formatted_image))

## ----message=FALSE------------------------------------------------------------
raw_halo_data <- system.file("extdata", "tiny_halo.csv.gz", package = "SPIAT")
markers <- c("DAPI", "CD3", "PD-L1", "CD4", "CD8", "AMACR")
intensity_columns_interest <- c("Dye 1 Nucleus Intensity",
                                "Dye 2 Cytoplasm Intensity",
                                "Dye 3 Membrane Intensity",
                                "Dye 4 Cytoplasm Intensity",
                                "Dye 5 Cytoplasm Intensity",
                                "Dye 6 Cytoplasm Intensity")
dye_columns_interest <- c("Dye 1 Positive Nucleus",
                          "Dye 2 Positive Cytoplasm",
                          "Dye 3 Positive Membrane",
                          "Dye 4 Positive Cytoplasm",
                          "Dye 5 Positive Cytoplasm",
                          "Dye 6 Positive Cytoplasm")
formatted_image <- format_halo_to_spe(
  path=raw_halo_data, markers=markers,
  intensity_columns_interest=intensity_columns_interest,
  dye_columns_interest=dye_columns_interest)
class(formatted_image) # The formatted image is a SpatialExperiment object
dim(colData(formatted_image))
dim(assay(formatted_image))

## -----------------------------------------------------------------------------
data("simulated_image")

## -----------------------------------------------------------------------------
class(simulated_image)

## -----------------------------------------------------------------------------
dim(simulated_image)

## -----------------------------------------------------------------------------
# take a look at first 5 columns
assay(simulated_image)[, 1:5]

## -----------------------------------------------------------------------------
# take a look at first 5 rows
colData(simulated_image)[1:5, ]

## -----------------------------------------------------------------------------
# take a look at first 5 rows
spatialCoords(simulated_image)[1:5, ]

## -----------------------------------------------------------------------------
unique(simulated_image$Phenotype)

## -----------------------------------------------------------------------------
split_image <- image_splitter(simulated_image, number_of_splits=3, plot = FALSE)

## ---- fig.height=6, fig.width = 4---------------------------------------------
predicted_image <- predict_phenotypes(spe_object = simulated_image,
                                      thresholds = NULL,
                                      tumour_marker = "Tumour_marker",
                                      baseline_markers = c("Immune_marker1", 
                                                           "Immune_marker2", 
                                                           "Immune_marker3", 
                                                           "Immune_marker4"),
                                      reference_phenotypes = TRUE)

## ---- fig.width = 9, fig.height=2, out.width="100%"---------------------------
marker_prediction_plot(predicted_image, marker="Immune_marker1")

## ---- eval=FALSE--------------------------------------------------------------
#  predicted_image2 <- predict_phenotypes(spe_object = simulated_image,
#                                        thresholds = NULL,
#                                        tumour_marker = "Tumour_marker",
#                                        baseline_markers = c("Immune_marker1",
#                                                             "Immune_marker2",
#                                                             "Immune_marker3",
#                                                             "Immune_marker4"),
#                                        reference_phenotypes = FALSE)

## ---- include=FALSE-----------------------------------------------------------
predicted_image2 <- predict_phenotypes(spe_object = simulated_image,
                                      thresholds = NULL,
                                      tumour_marker = "Tumour_marker",
                                      baseline_markers = c("Immune_marker1", 
                                                           "Immune_marker2", 
                                                           "Immune_marker3", 
                                                           "Immune_marker4"),
                                      reference_phenotypes = FALSE)

## -----------------------------------------------------------------------------
formatted_image <- define_celltypes(
    simulated_image, 
    categories = c("Tumour_marker","Immune_marker1,Immune_marker2", 
                   "Immune_marker1,Immune_marker3", 
                   "Immune_marker1,Immune_marker2,Immune_marker4", "OTHER"), 
    category_colname = "Phenotype", 
    names = c("Tumour", "Immune1", "Immune2", "Immune3", "Others"),
    new_colname = "Cell.Type")

## ---- fig.height = 2, fig.width = 3.2-----------------------------------------
marker_intensity_boxplot(formatted_image, "Immune_marker1")

## ---- fig.height=3, fig.width=6, dpi = 72, out.width="100%"-------------------
plot_cell_marker_levels(formatted_image, "Immune_marker1")

## ---- fig.height = 2.2, out.width="75%"---------------------------------------
plot_marker_level_heatmap(formatted_image, num_splits = 100, "Tumour_marker")

## -----------------------------------------------------------------------------
data_subset <- select_celltypes(
  formatted_image, keep=TRUE,
  celltypes = c("Tumour_marker","Immune_marker1,Immune_marker3", 
                "Immune_marker1,Immune_marker2",
                "Immune_marker1,Immune_marker2,Immune_marker4"),
  feature_colname = "Phenotype")
# have a look at what phenotypes are present
unique(data_subset$Phenotype)

## -----------------------------------------------------------------------------
predicted_image2 <- define_celltypes(
  predicted_image2, 
  categories = c("Tumour_marker", "Immune_marker1,Immune_marker2",
                 "Immune_marker1,Immune_marker3", 
                 "Immune_marker1,Immune_marker2,Immune_marker4"), 
  category_colname = "Phenotype",
  names = c("Tumour", "Immune1", "Immune2",  "Immune3"),
  new_colname = "Cell.Type")

# Delete cells with unrealistic marker combinations from the dataset
predicted_image2 <- 
  select_celltypes(predicted_image2, "Undefined", feature_colname = "Cell.Type",
                   keep = FALSE)

# TSNE plot
g <- dimensionality_reduction_plot(predicted_image2, plot_type = "TSNE", 
                                   feature_colname = "Cell.Type")

## ---- echo=TRUE, eval=FALSE---------------------------------------------------
#  plotly::ggplotly(g)

## ---- echo=FALSE, fig.width = 4, fig.height = 4, out.width = "70%"------------
knitr::include_graphics("tSNE1.jpg")

## ---- eval=FALSE--------------------------------------------------------------
#  predicted_image2 <-
#    select_celltypes(predicted_image2, c("Cell_3302", "Cell_4917", "Cell_2297",
#                                         "Cell_488", "Cell_4362", "Cell_4801",
#                                         "Cell_2220", "Cell_3431", "Cell_533",
#                                         "Cell_4925", "Cell_4719", "Cell_469",
#                                         "Cell_1929", "Cell_310", "Cell_2536",
#                                         "Cell_321", "Cell_4195"),
#                     feature_colname = "Cell.ID", keep = FALSE)

## ---- eval=FALSE--------------------------------------------------------------
#  # TSNE plot
#  g <- dimensionality_reduction_plot(predicted_image2, plot_type = "TSNE", feature_colname = "Cell.Type")
#  
#  # plotly::ggplotly(g) # uncomment this code to interact with the plot

## ---- echo=FALSE, fig.width = 4, fig.height = 4, out.width = "70%"------------
knitr::include_graphics("tSNE2.jpg")

## ---- fig.height = 2.5--------------------------------------------------------
my_colors <- c("red", "blue", "darkcyan", "darkgreen")
  
plot_cell_categories(spe_object = formatted_image, 
                     categories_of_interest = 
                       c("Tumour", "Immune1", "Immune2", "Immune3"), 
                     colour_vector = my_colors, feature_colname = "Cell.Type")

## ---- eval=FALSE--------------------------------------------------------------
#  marker_surface_plot(formatted_image, num_splits=15, marker="Immune_marker1")

## ---- echo=FALSE, out.width = "75%"-------------------------------------------
knitr::include_graphics("marker_surface1.jpg")

## ---- eval=FALSE--------------------------------------------------------------
#  marker_surface_plot_stack(formatted_image, num_splits=15, markers=c("Tumour_marker", "Immune_marker1"))

## ---- echo=FALSE, out.width = "75%"-------------------------------------------
knitr::include_graphics("marker_surface2.jpg")

## ---- fig.height = 2.5--------------------------------------------------------
my_colors <- c("red", "blue", "darkcyan", "darkgreen")
  
plot_cell_categories(spe_object = formatted_image, 
                     categories_of_interest = 
                       c("Tumour", "Immune1", "Immune2", "Immune3"), 
                     colour_vector = my_colors, 
                     feature_colname = "Cell.Type")

## ---- fig.width=3, fig.height = 2.2-------------------------------------------
p_cells <- calculate_cell_proportions(formatted_image, 
                                      reference_celltypes = NULL, 
                                      feature_colname ="Cell.Type",
                                      celltypes_to_exclude = "Others",
                                      plot.image = TRUE)
p_cells

## ---- fig.height=1.2, fig.width = 3.8-----------------------------------------
plot_cell_percentages(cell_proportions = p_cells, 
                      cells_to_exclude = "Tumour", cellprop_colname="Proportion_name")


## -----------------------------------------------------------------------------
distances <- calculate_pairwise_distances_between_celltypes(
  spe_object = formatted_image, 
  cell_types_of_interest = c("Tumour", "Immune1", "Immune3"),
  feature_colname = "Cell.Type")

## ---- fig.height = 4, fig.width=6, out.width="75%"----------------------------
plot_cell_distances_violin(distances)

## -----------------------------------------------------------------------------
summary_distances <- calculate_summary_distances_between_celltypes(distances)

summary_distances

## ---- fig.height = 2.5, out.width = "75%"-------------------------------------
plot_distance_heatmap(phenotype_distances_result = summary_distances, metric = "mean")

## -----------------------------------------------------------------------------
min_dist <- calculate_minimum_distances_between_celltypes(
  spe_object = formatted_image, 
  cell_types_of_interest = c("Tumour", "Immune1", "Immune2","Immune3", "Others"),
  feature_colname = "Cell.Type")

## ---- fig.height = 5, fig.width=8, out.width="75%"----------------------------
plot_cell_distances_violin(cell_to_cell_dist = min_dist)

## -----------------------------------------------------------------------------
min_summary_dist <- calculate_summary_distances_between_celltypes(min_dist)

# show the first five rows
min_summary_dist[seq_len(5),]

## ---- fig.height = 2.5, out.width = "75%"-------------------------------------
plot_distance_heatmap(phenotype_distances_result = min_summary_dist, metric = "mean")

## -----------------------------------------------------------------------------
average_percentage_of_cells_within_radius(spe_object = formatted_image, 
                                          reference_celltype = "Immune1", 
                                          target_celltype = "Immune2", 
                                          radius=100, feature_colname="Cell.Type")

## -----------------------------------------------------------------------------
average_marker_intensity_within_radius(spe_object = formatted_image,
                                       reference_marker ="Immune_marker3",
                                       target_marker = "Immune_marker2",
                                       radius=30)

## ---- fig.height = 2.2, fig.width = 4-----------------------------------------
plot_average_intensity(spe_object=formatted_image, reference_marker="Immune_marker3", 
                       target_marker="Immune_marker2", radii=c(30, 35, 40, 45, 50, 75, 100))

## -----------------------------------------------------------------------------
mixing_score_summary(spe_object = formatted_image, reference_celltype = "Immune1", 
                     target_celltype = "Immune2", radius=100, feature_colname ="Cell.Type")

## ---- echo=FALSE, fig.width = 2, fig.height = 1, out.width = "100%"-----------
knitr::include_graphics("cross-k-function.jpg")

## ----fig.width = 4.2----------------------------------------------------------
df_cross <- calculate_cross_functions(formatted_image, method = "Kcross", 
                                      cell_types_of_interest = c("Tumour","Immune2"), 
                                      feature_colname ="Cell.Type",
                                      dist = 100)

## -----------------------------------------------------------------------------
AUC_of_cross_function(df_cross)

## ---- echo = FALSE, fig.height = 2.5------------------------------------------
plot_cell_categories(formatted_image, c("Tumour", "Immune1", "Immune2", "Immune3"), 
                     my_colors, "Cell.Type")

## ---- fig.width = 4-----------------------------------------------------------
df_cross <- calculate_cross_functions(formatted_image, method = "Kcross", 
                                      cell_types_of_interest = c("Tumour","Immune3"), 
                                      feature_colname ="Cell.Type",
                                      dist = 100)

## -----------------------------------------------------------------------------
crossing_of_crossK(df_cross)

## -----------------------------------------------------------------------------
calculate_entropy(formatted_image, cell_types_of_interest = c("Immune1","Immune2"), 
                  feature_colname = "Cell.Type")

## ---- out.width = "70%"-------------------------------------------------------
data("defined_image")
grid <- grid_metrics(defined_image, FUN = calculate_entropy, n_split = 20,
                     cell_types_of_interest=c("Tumour","Immune3"), 
                     feature_colname = "Cell.Type")

## -----------------------------------------------------------------------------
calculate_percentage_of_grids(grid, threshold = 0.75, above = TRUE)

## -----------------------------------------------------------------------------
calculate_spatial_autocorrelation(grid, metric = "globalmoran")

## -----------------------------------------------------------------------------
gradient_positions <- c(30, 50, 100)
gradient_entropy <- 
  compute_gradient(defined_image, radii = gradient_positions, 
                   FUN = calculate_entropy,  cell_types_of_interest = c("Immune1","Immune2"),
                   feature_colname = "Cell.Type")
length(gradient_entropy)
head(gradient_entropy[[1]])

## -----------------------------------------------------------------------------
gradient_pos <- seq(50, 500, 50) ##radii
gradient_results <- entropy_gradient_aggregated(defined_image, cell_types_of_interest = c("Immune3","Tumour"),
                                                feature_colname = "Cell.Type", radii = gradient_pos)
# plot the results
plot(1:10,gradient_results$gradient_df[1, 3:12])

## ---- fig.width = 2.7, fig.height = 3-----------------------------------------
R_BC(formatted_image, cell_type_of_interest = "Tumour", "Cell.Type")

## ---- fig.width = 2.7, fig.height = 3-----------------------------------------
formatted_border <- identify_bordering_cells(formatted_image, 
                                             reference_cell = "Tumour", 
                                             feature_colname="Cell.Type")

## -----------------------------------------------------------------------------
# Get the number of tumour clusters
attr(formatted_border, "n_of_clusters")

## ---- echo=FALSE, fig.height=2, fig.width=2, out.width="75%"------------------
knitr::include_graphics("tumour-structure.jpg")

## -----------------------------------------------------------------------------
formatted_distance <- calculate_distance_to_margin(formatted_border)

## -----------------------------------------------------------------------------
names_of_immune_cells <- c("Immune1", "Immune2","Immune3")

formatted_structure <- define_structure(
  formatted_distance, cell_types_of_interest = names_of_immune_cells, 
  feature_colname = "Cell.Type", n_margin_layers = 5)

categories <- unique(formatted_structure$Structure)

## ---- fig.height = 3, fig.width = 5.8 , out.width = "90%"---------------------
plot_cell_categories(formatted_structure, feature_colname = "Structure")

## -----------------------------------------------------------------------------
immune_proportions <- calculate_proportions_of_cells_in_structure(
  spe_object = formatted_structure, 
  cell_types_of_interest = names_of_immune_cells, feature_colname ="Cell.Type")

immune_proportions

## -----------------------------------------------------------------------------
immune_distances <- calculate_summary_distances_of_cells_to_borders(
  spe_object = formatted_structure, 
  cell_types_of_interest = names_of_immune_cells, feature_colname = "Cell.Type")

immune_distances

## ---- fig.height = 2.5, out.width = "75%"-------------------------------------
data("image_no_markers")

plot_cell_categories(
  image_no_markers, c("Tumour", "Immune","Immune1","Immune2","Others"),
  c("red","blue","darkgreen", "brown","lightgray"), "Cell.Type")

## -----------------------------------------------------------------------------
average_minimum_distance(image_no_markers)

## -----------------------------------------------------------------------------
clusters <- identify_neighborhoods(
  image_no_markers, method = "hierarchical", min_neighborhood_size = 100,
  cell_types_of_interest = c("Immune", "Immune1", "Immune2"), radius = 50, 
  feature_colname = "Cell.Type")

## -----------------------------------------------------------------------------
neighorhoods_vis <- 
  composition_of_neighborhoods(clusters, feature_colname = "Cell.Type")
neighorhoods_vis <- 
  neighorhoods_vis[neighorhoods_vis$Total_number_of_cells >=5,]

## ---- fig.width = 3, fig.height = 3, out.width = "70%"------------------------
plot_composition_heatmap(neighorhoods_vis, feature_colname="Cell.Type")

## -----------------------------------------------------------------------------
average_nearest_neighbor_index(clusters, reference_celltypes=c("Cluster_1"), 
                               feature_colname="Neighborhood", p_val = 0.05)

## -----------------------------------------------------------------------------
average_nearest_neighbor_index(
  image_no_markers, reference_celltypes=c("Immune", "Immune1" , "Immune2"), 
  feature_colname="Cell.Type", p_val = 0.05)

## -----------------------------------------------------------------------------
sessionInfo()

