Skip to content

Commit 73fa614

Browse files
rhshahrhshah
committed
Merge branch 'release/0.1.6'
2 parents 2769502 + cfb014d commit 73fa614

3 files changed

Lines changed: 474 additions & 68 deletions

File tree

‎R/visualization_scripts/swimmer/README.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# Swimmer Plot Scripts
2+
3+
## Overview
4+
5+
The `swimmer` folder contains R scripts designed to create swimmer plots for visualizing treatment timelines and related data. These scripts process input data, calculate time differences, and generate swimmer plots for single and multiple treatments. The plots are saved as PDF or PNG files for further analysis and reporting.
6+
7+
## Scripts
8+
9+
### 1. `swimmer_single_treatment.R`
10+
11+
#### Description
12+
This script generates swimmer plots for single-treatment data. It processes input data, calculates time differences, and creates a swimmer plot with various visualizations, including treatment timelines and assay types.
13+
14+
#### Features
15+
- Processes input data to calculate time differences.
16+
- Generates swimmer plots for single-treatment data.
17+
- Supports multiple time units (days, weeks, months, years).
18+
- Saves the plot as a PDF file.
19+
20+
#### Arguments
21+
| Argument | Type | Description | Default Value |
22+
|-----------------|------------|-------------------------------------------------------|---------------|
23+
| `-i, --input` | `character` | File path to the input data file. | None |
24+
| `-o, --output` | `character` | File path for the output PDF file. | None |
25+
| `-t, --timeunit`| `character` | Time unit for the x-axis (days, weeks, months, years).| `days` |
26+
27+
#### Example Command
28+
```bash
29+
Rscript swimmer_single_treatment.R -i input_data.txt -o output_plot.pdf -t days
30+
```
31+
32+
---
33+
34+
### 2. `swimmer_multi_treatment.R`
35+
36+
#### Description
37+
This script generates swimmer plots for multi-treatment data. It processes metadata, calculates time differences, and creates a swimmer plot with treatment timelines and ctDNA detection points.
38+
39+
#### Features
40+
- Processes metadata to calculate time differences.
41+
- Generates swimmer plots for multi-treatment data.
42+
- Supports multiple time units (days, weeks, months, years).
43+
- Allows customization of treatment colors.
44+
- Saves the plot as a PNG file.
45+
46+
#### Arguments
47+
| Argument | Type | Description | Default Value |
48+
|-----------------|------------|-------------------------------------------------------|---------------|
49+
| `-m, --metadata`| `character` | File path to the metadata file. | None |
50+
| `-o, --resultsdir`| `character` | Output directory for the plot. | None |
51+
| `-c, --colors` | `character` | Comma-separated colors for treatment types. | `blue,red,green,yellow` |
52+
| `-t, --timeunit`| `character` | Time unit for the x-axis (days, weeks, months, years).| `days` |
53+
54+
#### Example Command
55+
```bash
56+
Rscript swimmer_multi_treatment.R -m metadata.xlsx -o /path/to/output -c blue,red,green -t weeks
57+
```
58+
59+
---
60+
61+
### 3. `dates2days.R`
62+
63+
#### Description
64+
This script converts date columns in the input data to numeric values representing time differences in specified units. The processed data is saved as a tab-delimited text file for use in swimmer plots.
65+
66+
#### Features
67+
- Converts date columns to numeric time differences.
68+
- Supports multiple time units (days, weeks, months, years).
69+
- Saves the processed data as a tab-delimited text file.
70+
71+
#### Arguments
72+
| Argument | Type | Description | Default Value |
73+
|-----------------|------------|-------------------------------------------------------|---------------|
74+
| `-i, --input` | `character` | File path to the input `.txt` file. | None |
75+
| `-o, --output` | `character` | File path for the output `.txt` file. | None |
76+
77+
#### Example Command
78+
```bash
79+
Rscript dates2days.R -i input_data.txt -o output_data.txt
80+
```
81+
82+
---
83+
84+
## Requirements
85+
86+
### R Packages
87+
The scripts require the following R packages:
88+
- `dplyr`
89+
- `ggplot2`
90+
- `lubridate`
91+
- `argparse`
92+
- `readr`
93+
- `readxl`
94+
- `tidyr`
95+
- `scales`
96+
- `gridExtra`
97+
- `cowplot`
98+
99+
Install the required packages using the following command:
100+
```R
101+
install.packages(c("dplyr", "ggplot2", "lubridate", "argparse", "readr", "readxl", "tidyr", "scales", "gridExtra", "cowplot"))
102+
```
103+
104+
---
105+
106+
## Input File Requirements
107+
108+
### Single Treatment Input File
109+
The input file for `swimmer_single_treatment.R` must contain the following columns:
110+
- `collection_date`
111+
- `start`
112+
- `endtouse`
113+
- `reason`
114+
- `assay_type`
115+
- `clinical_or_research`
116+
117+
### Multi-Treatment Metadata File
118+
The metadata file for `swimmer_multi_treatment.R` must contain the following columns:
119+
- `start`
120+
- `end`
121+
- `collection_date`
122+
- `treatment`
123+
- `ctdna_detection`
124+
125+
### Dates to Days Input File
126+
The input file for `dates2days.R` must contain date columns such as:
127+
- `pre_tx_date`
128+
- `start`
129+
- `end`
130+
131+
---
132+
133+
## Outputs
134+
135+
### Swimmer Plots
136+
- **Single Treatment**: PDF file containing the swimmer plot.
137+
- **Multi-Treatment**: PNG file containing the swimmer plot.
138+
139+
### Processed Data
140+
- Tab-delimited text file with numeric time differences for use in swimmer plots.
141+
142+
---
143+
144+
## Example Workflow
145+
146+
1. **Convert Dates to Days**:
147+
```bash
148+
Rscript dates2days.R -i input_data.txt -o processed_data.txt
149+
```
150+
151+
2. **Generate Single Treatment Swimmer Plot**:
152+
```bash
153+
Rscript swimmer_single_treatment.R -i processed_data.txt -o single_treatment_plot.pdf -t days
154+
```
155+
156+
3. **Generate Multi-Treatment Swimmer Plot**:
157+
```bash
158+
Rscript swimmer_multi_treatment.R -m metadata.xlsx -o /path/to/output -c blue,red,green -t weeks
159+
```
160+
161+
---
162+
163+
## Contact
164+
165+
For questions or issues, please contact:
166+
167+
- **Author**: Carmelina Charalambous, Alexander Ham
168+
- **Date**: 11/30/2023

‎R/visualization_scripts/vaf_overview/README.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# VAF Overview Plot Script
2+
3+
## Overview
4+
5+
This script, `vaf_overview_plot.R`, generates Variant Allele Frequency (VAF) overview plots for clinical and variant data. It creates visualizations in both PDF and HTML formats, providing insights into VAF trends, treatment durations, and reasons for stopping treatment for a specified number of patients.
6+
7+
## Features
8+
9+
- **Input Parsing**: Accepts clinical and variant data files as input.
10+
- **Data Validation**: Ensures required columns are present in the input files.
11+
- **Data Processing**:
12+
- Merges clinical and variant data.
13+
- Filters and categorizes data based on assay type.
14+
- Calculates VAF statistics (mean, max, relative VAF).
15+
- **Visualization**:
16+
- Generates plots for initial VAF, VAF trends, treatment duration, and reasons for stopping treatment.
17+
- Combines plots into a grid for each patient chunk.
18+
- **Output**:
19+
- Saves plots in both PDF and HTML formats.
20+
- Exports VAF statistics as a tab-delimited text file.
21+
22+
## Requirements
23+
24+
### R Packages
25+
26+
The script requires the following R packages:
27+
28+
- `ggplot2`
29+
- `gridExtra`
30+
- `tidyr`
31+
- `dplyr`
32+
- `sqldf`
33+
- `RSQLite`
34+
- `readr`
35+
- `argparse`
36+
- `plotly`
37+
- `htmlwidgets`
38+
- `purrr`
39+
40+
Install the required packages using the following command:
41+
42+
```R
43+
install.packages(c("ggplot2", "gridExtra", "tidyr", "dplyr", "sqldf", "RSQLite", "readr", "argparse", "plotly", "htmlwidgets", "purrr"))
44+
```
45+
46+
## Usage
47+
48+
### Command-Line Arguments
49+
50+
The script accepts the following arguments:
51+
52+
| Argument | Type | Description | Default Value |
53+
|-------------------|------------|-----------------------------------------------------------------------------|---------------|
54+
| `-o, --resultsdir` | `character` | Output directory where plots and statistics will be saved. | None |
55+
| `-v, --variants` | `character` | File path to the variant data (MAF file). | None |
56+
| `-c, --clinical` | `character` | File path to the clinical data file. | None |
57+
| `-y, --yaxis` | `character` | Y-axis metric for VAF plots (`mean`, `max`, or `relative`). | `mean` |
58+
| `-n, --num_patients` | `integer` | Number of patients to include in each plot. | `10` |
59+
60+
### Example Command
61+
62+
```bash
63+
Rscript vaf_overview_plot.R -o /path/to/output -v /path/to/variants.maf -c /path/to/clinical.tsv -y mean -n 10
64+
```
65+
66+
### Input File Requirements
67+
68+
#### Clinical Data File
69+
70+
The clinical data file must be a tab-delimited file containing the following columns:
71+
72+
- `cmoSampleName`
73+
- `cmoPatientId`
74+
- `PatientId`
75+
- `collection_date`
76+
- `collection_in_days`
77+
- `timepoint`
78+
- `treatment_length`
79+
- `treatmentName`
80+
- `reason_for_tx_stop`
81+
82+
#### Variant Data File
83+
84+
The variant data file must be a tab-delimited file containing the following columns:
85+
86+
- `Hugo_Symbol`
87+
- `HGVSp_Short`
88+
- `Tumor_Sample_Barcode`
89+
- `t_alt_freq`
90+
- `covered` (optional)
91+
92+
## Outputs
93+
94+
1. **Plots**:
95+
- PDF files: One file per patient chunk (e.g., `VAF_overview_chunk_1.pdf`).
96+
- HTML files: Interactive plots for each patient chunk (e.g., `VAF_overview_chunk_1.html`).
97+
98+
2. **Statistics**:
99+
- A tab-delimited text file (`vaf_statistics.txt`) containing VAF statistics for all patients.
100+
101+
## Script Workflow
102+
103+
1. **Input Parsing**:
104+
- Reads the clinical and variant data files.
105+
- Validates the presence of required columns.
106+
107+
2. **Data Processing**:
108+
- Merges clinical and variant data.
109+
- Filters and categorizes variants based on assay type.
110+
- Calculates VAF statistics (mean, max, relative VAF).
111+
112+
3. **Visualization**:
113+
- Splits data into chunks based on the number of patients specified.
114+
- Generates the following plots for each chunk:
115+
- Initial VAF
116+
- VAF trends over time
117+
- Treatment duration
118+
- Reasons for stopping treatment
119+
- Combines the plots into a grid and saves them as PDF and HTML files.
120+
121+
4. **Output**:
122+
- Saves the combined plots and VAF statistics.
123+
124+
## Error Handling
125+
126+
The script includes error handling for the following scenarios:
127+
128+
- Missing required columns in the input files.
129+
- Empty data frames after filtering.
130+
- Invalid Y-axis metric.
131+
- Number of patients per plot exceeding the total number of unique patients.
132+
133+
## Example Outputs
134+
135+
### PDF Plot
136+
137+
The PDF plot contains the following panels for each patient:
138+
139+
1. **Initial VAF**: Bar plot showing the initial VAF.
140+
2. **VAF Trends**: Line plot showing VAF trends over time.
141+
3. **Treatment Duration**: Bar plot showing the treatment duration in days.
142+
4. **Reason for Stopping Treatment**: Tile plot showing the reason for stopping treatment.
143+
144+
### HTML Plot
145+
146+
The HTML plot is an interactive version of the PDF plot, allowing users to explore the data dynamically.
147+
148+
### VAF Statistics
149+
150+
The `vaf_statistics.txt` file contains the following columns:
151+
152+
- `cmoSampleName`
153+
- `cmoPatientId`
154+
- `collection_in_days`
155+
- `PatientId`
156+
- `treatment_length`
157+
- `reason_for_tx_stop`
158+
- `AverageVAF`
159+
- `MinVAF`
160+
- `SDVAF`
161+
- `MaxVAF`
162+
163+
## Contact
164+
165+
For questions or issues, please contact:
166+
167+
- **Author**: Carmelina Charalambous, Alexander Ham
168+
- **Date**: 11/30/2023

0 commit comments

Comments
 (0)