plot_ggoutlier {GGoutlieR}

Visualize GGoutlieR results on a geographical map

Description

Visualize geo-genetic patterns of outliers with their K nearest neighbors

Usage

plot_ggoutlier(
  ggoutlier_res,
  geo_coord,
  anc_coef = NULL,
  gen_coord = NULL,
  pie_color = NULL,
  map_color = "black",
  p_thres = NULL,
  color_res = 10,
  dot_cex = NULL,
  map_type = c("geographic_knn", "genetic_knn", "both"),
  select_xlim = c(-180, 180),
  select_ylim = c(-90, 90),
  plot_xlim = NULL,
  plot_ylim = NULL,
  only_edges_in_xylim = TRUE,
  pie_r_scale = 1,
  map_resolution = "medium",
  show_knn_pie = FALSE,
  which_sample = NULL,
  add_benchmark_graph = TRUE,
  adjust_p_value_projection = FALSE,
  linewidth_range = c(0.5, 3),
  plot_labels = "auto"
)

Arguments

ggoutlier_res

output of 'ggoutlier'

geo_coord

matrix or data.frame with two columns. The first column is longitude and the second one is latitude.

anc_coef

matrix. A matrix of ancestry coefficients with samples ordered by rows. Ancestry coefficients are used to make pie charts on a geographical map. This argument is optional.

gen_coord

matrix. A matrix of "coordinates in a genetic space". It should be identical to the 'gen_coord' used for running 'ggoutlier'

pie_color

string. Colors of pie charts. colors are automatically assigned if 'pie_color = NULL' (which is the default). This argument is optional.

map_color

string. Colors of map contours. The default is 'map_color = "black"'

p_thres

numeric. A value of significant level. Only outliers (p values less than 'p_thres') are mapped on a geographical map if 'p_thres' is provided (the default is 'NULL'). This argument is optional.

color_res

integer. The resolution of color scale.

dot_cex

numeric. The size of dots denoting the positions of samples on a geographical map.

map_type

string. The type of plot to draw. It can be '"geographic_knn"', '"genetic_knn"' and '"both"'.

select_xlim

vector. Values controlling longitude boundaries of a window to select outliers to present on a geographical map. The default is 'select_xlim = c(-180,180)'.

select_ylim

vector. Values controlling latitude boundaries of a window to select outliers to present on a geographical map. The default is 'select_ylim = c(-90,90)'.

plot_xlim

vector. Values controlling longitude boundaries of a map.

plot_ylim

vector. Values controlling latitude boundaries of a map.

only_edges_in_xylim

logic. only the edges with starting points within the given 'select_xlim' and 'select_ylim' will display on a geographical map. If 'FALSE', the edges out of the given boundaries will be removed from your plot. The default is 'TRUE'.

pie_r_scale

numeric. A scale controlling the radius of pie charts

map_resolution

a character string. The resolution of the geographical map. See details of the 'scale' argument in the manual of 'rnaturalearth::ne_countries()'. The default is 'map_resolution = "medium"'

show_knn_pie

logic. If 'TRUE', the ancestry coefficients of K nearest neighbors of significant samples will display on the map. The default is 'FALSE'.

which_sample

a string vector of sample ID(s). If users want to only show specific sample(s)

add_benchmark_graph

logic. If 'TRUE', a benchmark graph with only pie charts of ancestry coefficients for comparison with the outlier graph.

adjust_p_value_projection

logic. If 'TRUE', the function will perform KNN prediction by forcing K=1 and compute new p-values for visualization.

linewidth_range

numeric. A vector of two values. It is used to control the minimal and maximal width of KNN network on the geographical map.

plot_labels

character. A string of labels for plots. The default is 'plot_labels = "auto"'. This parameter is for 'cowplot::plot_grid'.

Details

Red links on the map denote individual pairs that are genetically similar but geographically remote. The color depth and thickness of red links are proportional to -log10(p) based on the empirical Gamma distribution obtained from 'detect_outlier_in_GeneticSpace'. Blue links on the map denote individual pairs that are genetically different but geographically close. The color depth and thickness of blue links are proportional to -log10(p) based on the empirical Gamma distribution obtained from 'detect_outlier_in_GeoSpace'

Value

ggplot object. The plot is geographical map(s) with colored lines showing sample pairs with unusual geo-genetic associations.

Examples

library(GGoutlieR)
data("ipk_anc_coef") # get ancestry coefficients
data("ipk_geo_coord") # get geographical coordinates
data(ggoutlier_example) # get an example output of ggoutlier
## Not run: 
plot_ggoutlier(ggoutlier_res = ggoutlier_example,
               gen_coord = ipk_anc_coef,
               geo_coord = ipk_geo_coord,
               p_thres = 0.025,
               map_type = "both",
               select_xlim = c(-20,140),
               select_ylim = c(10,62),
               plot_xlim = c(-20,140),
               plot_ylim = c(10,62),
               pie_r_scale = 1.8,
               map_resolution = "medium")
               
## End(Not run)