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