Visualization Tool for Human Organ Data

Description

This tool visualizes numerical data (such as gene expression) on a human organ map. It supports custom color schemes, organ system filtering, and bar charts for quantitative comparison.

Usage

OrgHeatmap(
  data,
  system = NULL,
  valid_organs = NULL,
  sort_by_value = TRUE,
  title = NULL,
  showall = FALSE,
  outline = TRUE,
  palette = "YlOrRd",
  color_high = NULL,
  color_low = NULL,
  color_mid = NULL,
  reverse_palette = FALSE,
  fillcolor_outline = "#F5D5B8",
  fillcolor_organ = "plasma",
  fillcolor_other = "#D3D3D3",
  organbar = TRUE,
  organbar_title = NULL,
  organbar_digit = 4,
  organbar_color = NULL,
  organbar_low = NULL,
  organbar_high = NULL,
  direction = 1,
  save_clean_data = FALSE,
  save_plot = FALSE,
  clean_data_path = file.path(getwd(), "clean_data.rds"),
  plot_path = file.path(getwd(), "organ_plot.png"),
  plot_width = 10,
  plot_height = 8,
  plot_dpi = 300,
  plot_device = "png",
  organ_system_map = organ_systems,
  organ_name_mapping = NULL,
  aggregate_method = "mean",
  organ_col = "organ",
  value_col = "value"
)

Arguments

Details

The function uses define_organ_colors() (an internal helper function) to generate unified color schemes:

1. If organbar_low and organbar_high are specified by the user, they will be used directly (highest priority);

2. If not, colors are generated from the palette (RColorBrewer) with optional reversal (reverse_palette);

3. Custom middle color (color_mid) is supported for 3-color gradients (applied to both heatmap and bar chart). For valid palette names, see RColorBrewer::brewer.pal.info.

Organ Mapping Logic

• For organ_name_mapping: Accepts a named vector, data frame, or CSV path. Internal helper create_organ_mapping() standardizes names (lowercase, underscores for spaces).

• For organ_system_map: Custom tables (data frame/CSV) are processed to align with built-in organ_systems format via create_organ_mapping().

Value

List containing:

Examples

# Load the package
library(OrgHeatmap)

# Note: Example datasets (example_Data1, example_Data2, example_Data3, expr_data)
# are included in the package's 'extdata' directory.

## Load example data files from extdata (contains example_Data1, example_Data2, example_Data3)
data_path <- system.file("extdata", "exampledata.Rdata", package = "OrgHeatmap")
load(data_path)  

# 1.Plot all organs and save results using internal saving function
result_all <- OrgHeatmap(
  example_Data3, 
  organbar = TRUE,
  save_plot = TRUE,  # Enable plot saving
  plot_path = file.path(getwd(), "all_system.png"),  # Save to current directory
  plot_width = 10,
  plot_height = 8,
  save_clean_data = TRUE,  # Enable cleaned data saving
  clean_data_path = file.path(getwd(), "all_system_clean_data.rds")
)
print(result_all$plot)  # Print the plot to the console

# 2. Plot circulatory system organs and save results
result_circulatory <- OrgHeatmap(
  example_Data3, 
  system = "circulatory",
  organbar = TRUE,
  save_plot = TRUE,
  plot_path = file.path(getwd(), "circulatory_system.png"),
  plot_width = 10,
  plot_height = 8,
  plot_device = "png",  # Specify plot format
  save_clean_data = TRUE,
  clean_data_path = file.path(getwd(), "circulatory_clean_data.rds")
)
print(result_circulatory$plot)  # Print the plot to the console

# 3. Quick color configuration with palette
# Core logic: Trigger internal color_config generation via palette parameters,
# ensuring organ and bar chart colors are synchronized
result_palette <- OrgHeatmap(
example_Data3,
system = "respiratory",  # Respiratory system
palette = "PuBuGn",      # Use RColorBrewer's blue-purple-green palette
reverse_palette = TRUE,  # Reverse palette (low value = dark green, high value = purple)
color_mid = "#87CEEB",   # Custom middle color (sky blue)
title = "Respiratory System (Palette: PuBuGn)",
organbar_title = "Mean Value",
organbar_digit = 2,
showall = TRUE,
save_plot = TRUE,
plot_path = file.path(getwd(), "respiratory_palette.png")
  # To use solid color for bars, add parameter: organbar_color = "skyblue"
  # (overrides gradient and synchronizes with organ colors)
)
print(result_palette$plot)


 ## Load the example dataset expr_data from extdata
 expr_data_path <- system.file("extdata", "expr_data.rds", package = "OrgHeatmap")
 expr_data <- readRDS(expr_data_path)

# Custom organ mapping (standardize original organ names)
custom_mapping <- c(
  "adrenal" = "adrenal_gland",
  "lymph node" = "lymph_node",
  "soft tissue" = "muscle",
  "peritoneal" = "peritoneum"
)

# Add prostate cancer-specific organs to system mapping
prostate_organ_systems <- rbind(
  organ_systems,  # Package's built-in organ system mapping
  data.frame(
    organ = c("prostate", "bone", "lymph_node", "adrenal_gland"),
    system = c("reproductive", "musculoskeletal", "lymphatic", "endocrine"),
    stringsAsFactors = FALSE
  )
)

# Generate TP53 expression heatmap and save results
tp53_plot <- OrgHeatmap(
  data = expr_data,
  value_col = "expression",  # Specify value column name as "expression"
  organ_system_map = prostate_organ_systems,  # Use custom organ system mapping
  organ_name_mapping = custom_mapping,  # Apply organ name mapping
  title = "TP53 Expression in Metastatic Prostate Cancer",
  organbar_title = "Mean Expression(log2) of TP53",
  aggregate_method = "mean",  # Calculate mean by organ
  showall = TRUE,  # Show all organ outlines
  fillcolor_other = "#DCDCDC",  # Fill color for non-target organs
  organbar_digit = 2,  # Keep 2 decimal places for bar values
  direction = -1,  # Reverse color gradient (darker = higher expression)
  save_plot = TRUE,  # Save the plot
  plot_path = file.path(getwd(), "tp53_expression_metastatic_prostate.png"),
  plot_width = 14,
  plot_height = 10,
  plot_dpi = 300,
  save_clean_data = TRUE,  # Save cleaned data
  clean_data_path = file.path(getwd(), "tp53_clean_data.rds")
)

# Print the plot
print(tp53_plot$plot)

Human body contour coordinate data

Description

Contains plotting coordinates for the human body contour, used for drawing the background outline.

Usage

human_bodycontour

Format

A data frame containing:

V1

Integer. Original index from source data (reserved for compatibility).

id

Character. Group identifier for contour segments (used to draw connected regions).

x

Numeric. X-coordinate of contour points.

y

Numeric. Y-coordinate of contour points.

Human organ coordinate data

Description

Contains plotting coordinates (x, y) for each organ, used for drawing organ contours.

Usage

human_organ_coord

Format

A list where each element is a data frame containing:

x

x-coordinate (numeric)

y

y-coordinate (numeric)

id

Group ID (for drawing polygons, integer)

Organ-system mapping data

Description

Defines the physiological system each organ belongs to, used for filtering organs by system.

Usage

organ_systems

Format

A data frame with the following columns:

organ

Organ name (character, standardized name)

system

Belonging system (character, e.g., "circulatory" for circulatory system)

Global variables

Description

Declare variables used in dplyr pipelines as global