EPGplotR

A Package for Plotting Insect Electrical Penetration Graph Signals in R!

---

📋 Table of Contents

• Project Description
• Installing EPGplotR
• Using EPGplotR
  • Step 1: Load a .DXX Recording
  • Step 2: Load the Corresponding .ANA File
  • Step 3: Annotate the Recordings
  • Step 4: Plot the Data
    • Option 1: Create Interactive Plots
    • Option 2: Create Static Plots
• Example Figure Generated by EPGplotR
• Key Features
• Getting Started
• Contributing
• License

---

🪲 Project Description

EPGplotR is a powerful R package designed to simplify the visualization of insect electrical penetration graph (EPG) data. It enables users to:

• Load EPG Files: Automatically load .DXX file formats (Stylet+ DAQ output files).
• Load ANA Files: Import corresponding .ANA files for plot annotations.
• Visualize Signals: Generate high-quality plots of EPG signals (both interactive and static).
• Annotate and Analyze: Label recordings with behavioral annotations and segment key areas of interest.
• Customize Plots: Built on the robust frameworks of ggplot2 and plotly, allowing extensive user customizations.

With just four commands, users can produce publication-ready figures. EPGplotR makes it easy to generate beautiful visualizations while offering significant flexibility for advanced users.

---

🚀 Installing EPGplotR

Before installing EPGplotR, ensure you have the following tools installed:

1. R: Download from CRAN.
2. RStudio: Download the desktop version from Posit.

Once these are installed, you can install EPGplotR using the install_github() function from the devtools package.

Installation Steps

1. Install devtools Package (if not already installed):

   install.packages("devtools")

2. Load devtools into Your Environment:

   library(devtools)

3. Install EPGplotR from GitHub:

   install_github("dankunk/EPGplotR")

4. Load EPGplotR:

   library(EPGplotR)

---

💻 Using EPGplotR

Once you've loaded EPGplotR into your environment using library(EPGplotR), you're ready to start using EPGplotR.

Step 1: Load a .DXX Recording

No need to supply a path to all the recording files manually. Simply run load_d0x_files(), select the first hour file for the recording of interest (i.e. .D01), and EPGplotR will handle the rest!

# Load EPGplotR
library(EPGplotR)

# Load a recording by selecting the file via the file explorer
rec_dt <- load_d0x_files()

# Alternatively, provide a direct path using the filepath argument:
rec_dt <- load_d0x_files(filepath = "C:/Users/user/My_EPG_file_folder/recording1_ch1.D01")

Step 2: Load the Corresponding .ANA File

After loading the recordings, load the corresponding .ANA file for annotations.

# Load the corresponding ANA file via the file explorer:
ana_dt <- load_ana_file()

# Alternatively, specify the file path directly:
ana_dt <- load_ana_file(filepath = "C:/Users/user/My_ANA_file_folder/recording1_ch1.ANA")

# Or if you don't have an ANA file, proceed to the plotting functions and use no_ana = TRUE

Step 3: Annotate the Recordings

Use the assign_behavior_codes() function to add behavioral annotations from the .ANA file to your recording data.

# Annotate the rec_dt datatable with behavioral annotations:
assign_behavior_codes(rec_dt, ana_dt)

Voila! Now you're ready to plot your data. EPGplotR offers two main plotting options:

1. Interactive Plots: Utilize plotly with the plot_signal() function.

2. Static Plots: Utilize ggplot2 with the gg_plot_signal() function.

Step 4: Plot the Data

Option 1: Create Interactive Plots

This method will use plotly via the plot_signal() function.

To expedite plotting, EPGplotR offers a downsampling capability that defaults to downsampling the signal by a factor of 10Hz. To preserve proper waveform characteristics, set downsample_rate = 1.

# Interactive plots with plotly using plot_signal()
plot_signal(rec_dt)

# Ensure waveform characteristics and behavioral transitions remain intact by setting downsample_rate = 1
plot_signal(rec_dt, downsample_rate = 1)

# Change axis units from hours to seconds using the time_unit argument (default is "hours")
plot_signal(rec_dt, downsample_rate = 1, time_unit = "seconds")

# Modify transparency and add a custom plot title
plot_signal(rec_dt, downsample_rate = 1, time_unit = "seconds",
    alpha = 1,
    plot_title = "Recording 1 - Channel 1 - Alpha = 1")

Option 2: Create Static Plots

This method will use ggplot2 via the gg_plot_signal() function.

The downsample_rate argument works exactly the same as in the interactive plot.

# Create a static plot and display it in the plot window
gg_plot_signal(rec_dt, downsample_rate = 1, alpha = 0.5)

# Assign the plot to a variable for further customization
p <- gg_plot_signal(rec_dt, downsample_rate = 1, alpha = 0.5)

# Segment plots to specific ranges by adding range and range_unit arguments ("hours" or "seconds")
# Plot hours 5-8 only
gg_plot_signal(rec_dt, downsample_rate = 1, alpha = 1, range = c(5, 8), range_unit = "hours")

# Plot from 12603.5 seconds to 12605.85 seconds
gg_plot_signal(rec_dt, alpha = 1,
  downsample_rate = 1,
  range = c(12603.5, 12605.85),
  range_unit = "seconds")

# Save plots to disk using the output_file argument. If left blank, it defaults to NULL and displays the plot in the plot window
gg_plot_signal(
  rec_dt, 
  alpha = 1, 
  downsample_rate = 1, 
  range = c(12603.5, 12605.85), 
  range_unit = "seconds", 
  plot_title = "12604-12606 seconds - Rec1 - Ch1", 
  output_file = "C:/Users/user/My_plot_file_folder/segmented_recording1_ch1_ggplot.svg"
)

---

📊 Example Figure Generated by EPGplotR

---

🔧 Key Features

• Load and Process: Quickly import .DXX files and prepare them for analysis.
• Interactive Exploration: Zoom, pan, and explore waveforms for in-depth insights.
• Annotation: Add behavior-specific annotations to your plots.
• Customizable Outputs: Export high-quality, presentation-ready figures with vast control over appearance via ggplot2 and plotly.

---

📚 Getting Started (coming soon)

For more details, visit the EPGplotR Documentation to explore tutorials, examples, and detailed instructions.

---

🔗 Contributing (coming soon)

Want to contribute to EPGplotR? We welcome contributions! Check out our Contribution guidelines for this project for details on how to get started.

---

📝 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Written November 2024 by Daniel Kunk (PhD Candidate - Colorado State University)