├── README-MJ.png ├── README-MJ2.png ├── README-box.png ├── README-group.png ├── README-hist.png ├── README-line.png ├── data ├── life_exp.rda ├── mj_life.rda └── life_country.rda ├── README-density.png ├── README-scatter.png ├── R ├── mj_life.R ├── life_exp.R ├── life_country.R ├── durSummary.R ├── timelineG.R ├── durCalc.R ├── timelineS.R └── durPlot.R ├── NAMESPACE ├── man ├── mj_life.Rd ├── life_exp.Rd ├── life_country.Rd ├── durSummary.Rd ├── timelineG.Rd ├── durCalc.Rd ├── durPlot.Rd └── timelineS.Rd ├── timelineS.Rproj ├── DESCRIPTION ├── README.md └── README.Rmd /README-MJ.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/README-MJ.png -------------------------------------------------------------------------------- /README-MJ2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/README-MJ2.png -------------------------------------------------------------------------------- /README-box.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/README-box.png -------------------------------------------------------------------------------- /README-group.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/README-group.png -------------------------------------------------------------------------------- /README-hist.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/README-hist.png -------------------------------------------------------------------------------- /README-line.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/README-line.png -------------------------------------------------------------------------------- /data/life_exp.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/data/life_exp.rda -------------------------------------------------------------------------------- /data/mj_life.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/data/mj_life.rda -------------------------------------------------------------------------------- /README-density.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/README-density.png -------------------------------------------------------------------------------- /README-scatter.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/README-scatter.png -------------------------------------------------------------------------------- /data/life_country.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/daheelee/timelineS/HEAD/data/life_country.rda -------------------------------------------------------------------------------- /R/mj_life.R: -------------------------------------------------------------------------------- 1 | #' @title Data for timelineS function example in timelineS package 2 | #' @description Events and dates of Michael Jackson's life 3 | #' @name mj_life 4 | #' @docType data 5 | #' @format dataframe of events(character) and dates(date) 6 | NULL 7 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | export(durCalc) 4 | export(durPlot) 5 | export(durSummary) 6 | export(timelineG) 7 | export(timelineS) 8 | import(dplyr) 9 | import(ggplot2) 10 | import(graphics) 11 | import(magrittr) 12 | -------------------------------------------------------------------------------- /R/life_exp.R: -------------------------------------------------------------------------------- 1 | #' @title Data for examples in timelineS package 2 | #' @description Dates of birth and death, country, gender and names 3 | #' @name life_exp 4 | #' @docType data 5 | #' @format dataframe of name(character), country(character), gender(character), and dates(date) 6 | #' @keywords durSummary, durPlot, durCalc 7 | NULL 8 | -------------------------------------------------------------------------------- /R/life_country.R: -------------------------------------------------------------------------------- 1 | #' @title Data for timelineGroup function example in timelineS package 2 | #' @description Dates of birth and death, gender and phases 3 | #' @name life_country 4 | #' @docType data 5 | #' @format dataframe of name(character), country(character), gender(character), phase(character) and dates(date) 6 | #' @keywords timelineGroup 7 | NULL 8 | -------------------------------------------------------------------------------- /man/mj_life.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/mj_life.R 3 | \docType{data} 4 | \name{mj_life} 5 | \alias{mj_life} 6 | \title{Data for timelineS function example in timelineS package} 7 | \format{dataframe of events(character) and dates(date)} 8 | \description{ 9 | Events and dates of Michael Jackson's life 10 | } 11 | 12 | -------------------------------------------------------------------------------- /man/life_exp.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/life_exp.R 3 | \docType{data} 4 | \name{life_exp} 5 | \alias{life_exp} 6 | \title{Data for examples in timelineS package} 7 | \format{dataframe of name(character), country(character), gender(character), and dates(date)} 8 | \description{ 9 | Dates of birth and death, country, gender and names 10 | } 11 | \keyword{durCalc} 12 | \keyword{durPlot,} 13 | \keyword{durSummary,} 14 | 15 | -------------------------------------------------------------------------------- /man/life_country.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/life_country.R 3 | \docType{data} 4 | \name{life_country} 5 | \alias{life_country} 6 | \title{Data for timelineGroup function example in timelineS package} 7 | \format{dataframe of name(character), country(character), gender(character), phase(character) and dates(date)} 8 | \description{ 9 | Dates of birth and death, gender and phases 10 | } 11 | \keyword{timelineGroup} 12 | 13 | -------------------------------------------------------------------------------- /timelineS.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: XeLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | 18 | BuildType: Package 19 | PackageUseDevtools: Yes 20 | PackageInstallArgs: --no-multiarch --with-keep.source 21 | PackageCheckArgs: --as-cran 22 | PackageRoxygenize: rd,collate,namespace,vignette 23 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: timelineS 2 | Type: Package 3 | Title: Timeline and Time Duration-Related Tools 4 | Version: 0.1.1 5 | Date: 2016-08-21 6 | Author: Dahee Lee [aut, cre], Dustin Tingley [aut] 7 | Maintainer: Dahee Lee 8 | Description: An easy tool for plotting annotated timelines, grouped timelines, and exploratory graphics (boxplot/histogram/density plot/scatter plot/line plot). Filter, summarize date data by duration and convert to calendar units. 9 | URL: https://github.com/daheelee/timelineS 10 | BugReports: https://github.com/daheelee/timelineS/issues 11 | License: GPL-2 12 | LazyData: TRUE 13 | Imports: 14 | base, 15 | graphics, 16 | magrittr, 17 | dplyr, 18 | lubridate, 19 | ggplot2, 20 | stats 21 | Depends: 22 | R (>= 3.1.0) 23 | RoxygenNote: 5.0.1 24 | 25 | -------------------------------------------------------------------------------- /man/durSummary.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/durSummary.R 3 | \name{durSummary} 4 | \alias{durSummary} 5 | \title{Summary for Date Duration Data} 6 | \usage{ 7 | durSummary(df, start, end, group = NA, timeunit = "days") 8 | } 9 | \arguments{ 10 | \item{df}{Data frame containing start and end dates.} 11 | 12 | \item{start}{Column in df for start dates.} 13 | 14 | \item{end}{Column in df for end dates.} 15 | 16 | \item{group}{Column in df for groups. Default NA.} 17 | 18 | \item{timeunit}{Unit of time to be used in plots. \code{"day(s)"}, \code{"week(s)"}, \code{"month(s)"}, \code{"quarter(s)"}, \code{"semiannual"}, \code{"halfyear"},or \code{"year(s)"}.} 19 | } 20 | \description{ 21 | Returns summary statistics for date duration data (for each group if \code{group} is provided) 22 | } 23 | \details{ 24 | 1 year = 365.25 days, 1 month = 30.42 days, 1 year = 52.14 weeks 25 | } 26 | \examples{ 27 | durSummary(life_exp, start = "Birth", end = "Death", group = "Country", timeunit = "years") 28 | } 29 | \author{ 30 | Dahee Lee 31 | } 32 | \seealso{ 33 | \code{\link{durPlot}}, \code{\link{durCalc}} 34 | } 35 | 36 | -------------------------------------------------------------------------------- /man/timelineG.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/timelineG.R 3 | \name{timelineG} 4 | \alias{timelineG} 5 | \title{Faceted Timelines for Grouped Data} 6 | \usage{ 7 | timelineG(df, start, end, names, phase = NA, group1 = NA, group2 = NA, 8 | width = 2, color = "grey", theme = NULL, other = NULL) 9 | } 10 | \arguments{ 11 | \item{df}{Data frame containing start dates, end dates, groups, phases, and names for each timeline.} 12 | 13 | \item{start}{Column in df for start dates.} 14 | 15 | \item{end}{Column in df for end dates.} 16 | 17 | \item{names}{Column in df for names of each timeline} 18 | 19 | \item{phase}{Column in df for phases.} 20 | 21 | \item{group1}{Column in df for groups to be used as the rows of the tabular display. Default is NA.} 22 | 23 | \item{group2}{Column in df for groups to be used as the columns of the tabular display. Default is NA.} 24 | 25 | \item{width}{Width of each timeline. Default is 2.} 26 | 27 | \item{color}{Color of timelines, only used when \code{phase} is not provided.} 28 | 29 | \item{theme}{Add theme elements if needed.} 30 | 31 | \item{other}{Add other elements if needed.} 32 | } 33 | \description{ 34 | Plots faceted timelines for grouped data. 35 | } 36 | \examples{ 37 | ### Plot timelines row-grouped by "Country" 38 | timelineG(df = life_country, start = "Start", end = "End", names = "Name", 39 | phase = "Phase", group1 = "Country") 40 | 41 | ### Plot timelines row-grouped by "Country" and column-grouped by "Gender" 42 | timelineG(df = life_country, start = "Start", end = "End", names = "Name", 43 | phase = "Phase", group1 = "Country", group2 = "Gender") 44 | 45 | ### Plot timelines, no group 46 | timelineG(df = life_country, start = "Start", end = "End", names = "Name",color = "grey") 47 | 48 | } 49 | \author{ 50 | Dahee Lee 51 | } 52 | \seealso{ 53 | \code{\link{timelineS}} 54 | } 55 | 56 | -------------------------------------------------------------------------------- /man/durCalc.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/durCalc.R 3 | \name{durCalc} 4 | \alias{durCalc} 5 | \title{Filter Dataset by Date Duration} 6 | \usage{ 7 | durCalc(df = NULL, start, end, timeunit = "day", filterlength = NA, 8 | filterlonger = TRUE, year = 365.25, month = 30.42) 9 | } 10 | \arguments{ 11 | \item{df}{Data frame containing start and end dates.} 12 | 13 | \item{start}{Column in df for start dates or a date to use as start date.} 14 | 15 | \item{end}{Column in df for end dates or a date to use as a end date.} 16 | 17 | \item{timeunit}{Unit of time to be used in plots. \code{"day(s)"}, \code{"week(s)"}, \code{"month(s)"}, \code{"quarter(s)"}, \code{"semiannual"}, \code{"halfyear"},or \code{"year(s)"}.} 18 | 19 | \item{filterlength}{A time length to use as filter.} 20 | 21 | \item{filterlonger}{If TRUE, the function gives rows with longer durations than specified in filterlength. If FALSE, gives rows with shorter durations.} 22 | 23 | \item{year}{Number of days to use as a year. Default is 365.25.} 24 | 25 | \item{month}{Number of days to use as a month. Default is 30.42.} 26 | } 27 | \value{ 28 | A subset of original data frame with additional columns in specified time units and calendar units. 29 | } 30 | \description{ 31 | Calculates the duration between two dates, use it as a filter to select rows that satisfy the length criteria. 32 | Returns the dataset with additional columns regarding the length of durations in different units. 33 | } 34 | \details{ 35 | Additional columns returned with the filtered rows are: length of duration in days, in specified time unit, and in calendar units, and 36 | how much longer/shorter the durations are compared to filter length in calendar units. 37 | 38 | If no \code{filterlength} is provided, then returns all rows with length of duration in days and calendar units. 39 | 40 | You can use dates for \code{start} and \code{end} and provide no \code{df} to get the length of duration between the dates in calendar units. See example. 41 | } 42 | \examples{ 43 | ### Filter people who lived longer than 85 years 44 | durCalc(life_exp, start = "Birth", end = "Death", timeunit = "years", filterlength = 85) 45 | 46 | ### How old each person would be as of January 1, 2000 if they were alive 47 | durCalc(life_exp, start = "Birth", end = as.Date("2000-1-1"), timeunit = "years") 48 | 49 | ### Use as unit-converter between two dates 50 | durCalc(start = as.Date("2010-12-1"), end = as.Date("2015-4-26"), timeunit = "weeks") 51 | } 52 | \author{ 53 | Dahee Lee 54 | } 55 | \seealso{ 56 | \code{\link{durPlot}}, \code{\link{durSummary}} 57 | } 58 | 59 | -------------------------------------------------------------------------------- /R/durSummary.R: -------------------------------------------------------------------------------- 1 | #' @title Summary for Date Duration Data 2 | #' @description Returns summary statistics for date duration data (for each group if \code{group} is provided) 3 | #' @usage 4 | #' durSummary(df, start, end, group = NA, timeunit = "days") 5 | #' @param df Data frame containing start and end dates. 6 | #' @param start Column in df for start dates. 7 | #' @param end Column in df for end dates. 8 | #' @param group Column in df for groups. Default NA. 9 | #' @param timeunit Unit of time to be used in plots. \code{"day(s)"}, \code{"week(s)"}, \code{"month(s)"}, \code{"quarter(s)"}, \code{"semiannual"}, \code{"halfyear"},or \code{"year(s)"}. 10 | #' @details 1 year = 365.25 days, 1 month = 30.42 days, 1 year = 52.14 weeks 11 | #' @seealso \code{\link{durPlot}}, \code{\link{durCalc}} 12 | #' @examples 13 | #' durSummary(life_exp, start = "Birth", end = "Death", group = "Country", timeunit = "years") 14 | #' @author Dahee Lee 15 | #' @import magrittr dplyr 16 | #' @export 17 | #' 18 | durSummary <- function(df, start, end, group = NA, timeunit = "days"){ 19 | 20 | if(!is.data.frame(df)){ 21 | stop("'df' must be a data frame") 22 | } 23 | 24 | if(!(class(df[[start]]) == "Date") && (class(df[[end]]) == "Date")){ 25 | stop("'start' and 'end' must be dates") 26 | } 27 | 28 | # Remove NA rows 29 | df <- df[rowSums(is.na(df[,c(start,end)])) == 0,] 30 | 31 | # Make duration data 32 | df$duration <- as.numeric(df[[end]] - df[[start]]) 33 | 34 | # Change Time unit 35 | df$duration <- if(timeunit %in% c("year","years")){ 36 | df$duration / 365.25 37 | } else if (timeunit %in% c("semiannual", "halfyear")){ 38 | df$duration / 365.25 * 2 39 | } else if (timeunit %in% c("quarter", "quarters")){ 40 | df$duration / 365.25 * 4 41 | } else if (timeunit %in% c("month", "months")){ 42 | df$duration / 30.42 43 | } else if (timeunit %in% c("week", "weeks")){ 44 | df$duration / 52.14 45 | } else if (timeunit %in% c("day", "days")){ 46 | df$duration 47 | } else { 48 | warning("invalid 'timeunit': default 'days' used") 49 | df$duration } 50 | 51 | 52 | # Print Summary 53 | df <- if (is.na(group)){df} else (df %>% group_by_(as.name(group))) 54 | summary <- df %>% 55 | summarize_(min = ~min(duration, na.rm = T), 56 | Qt1 = ~quantile(duration, probs = 0.25, na.rm = T), 57 | median = ~median(duration, na.rm = T), 58 | mean = ~mean(duration, na.rm = T), 59 | Qt3 = ~quantile(duration, probs = 0.75, na.rm = T), 60 | max = ~max(duration, na.rm = T), 61 | sd = ~sd(duration, na.rm = T)) 62 | if(is.na(group)){ 63 | summary <- round(summary[,(ncol(summary) - 6):ncol(summary)], 2) 64 | } else { 65 | summary <- cbind(summary[,1:(ncol(summary) - 7)],round(summary[,(ncol(summary) - 6):ncol(summary)], 2)) 66 | } 67 | return(summary) 68 | } 69 | -------------------------------------------------------------------------------- /man/durPlot.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/durPlot.R 3 | \name{durPlot} 4 | \alias{durPlot} 5 | \title{Graphs and Summary for Date Durations} 6 | \usage{ 7 | durPlot(df, start, end, group = NA, timeunit = "days", plot_type = "all", 8 | facet = FALSE, facet.nrow = NULL, theme = NULL, other = NULL, 9 | fill_color = "black", line_color = "black", groupcolor = TRUE, 10 | point_size = 2, alpha = NA, binwidth = 0.5, show_legend = TRUE, 11 | title=FALSE, title_boxplot = "Boxplot", title_histogram = "Histogram", 12 | title_density = "Density Plot", title_scatter = "Scatter Plot", 13 | title_line = "Line Plot") 14 | } 15 | \arguments{ 16 | \item{df}{Data frame containing start dates, end dates and groups.} 17 | 18 | \item{start}{Column in df for start dates.} 19 | 20 | \item{end}{Column in df for end dates.} 21 | 22 | \item{group}{Column in df for groups. Default is NA.} 23 | 24 | \item{timeunit}{Unit of time to be used in plots. \code{"day(s)"}, \code{"week(s)"}, \code{"month(s)"}, \code{"quarter(s)"}, \code{"semiannual"}, \code{"halfyear"},or \code{"year(s)"}.} 25 | 26 | \item{plot_type}{One of \code{"all", "boxplot", "histogram", "density", "scatter", "line"}. Default is \code{"all"}.} 27 | 28 | \item{facet}{If TRUE, wraps plots in group facets} 29 | 30 | \item{facet.nrow}{Number of rows for facet wrap} 31 | 32 | \item{theme}{Add theme elements if needed.} 33 | 34 | \item{other}{Add other elements if needed.} 35 | 36 | \item{fill_color}{Fill color} 37 | 38 | \item{line_color}{Line color} 39 | 40 | \item{groupcolor}{If FALSE, fill_color and line_color used for all groups. Default is TRUE.} 41 | 42 | \item{point_size}{Point size for scatterplot} 43 | 44 | \item{alpha}{Color transparency [0,1]} 45 | 46 | \item{binwidth}{Binwidth for histogram; default 0.5.} 47 | 48 | \item{show_legend}{Default is TRUE} 49 | 50 | \item{title}{If TRUE, puts main titles for each plot} 51 | 52 | \item{title_boxplot}{Title for boxplot title} 53 | 54 | \item{title_histogram}{Title for histogram} 55 | 56 | \item{title_density}{Title for density plot} 57 | 58 | \item{title_scatter}{Title for scatter plot} 59 | 60 | \item{title_line}{Title for line plot} 61 | } 62 | \description{ 63 | Plots boxplot, histogram, density plot, scatter plot, line plot and prints summary statistics for date duration data. 64 | } 65 | \details{ 66 | The function also returns summary statistics for the specified date duration. 67 | } 68 | \examples{ 69 | durPlot(life_exp, start = "Birth", end = "Death", group = "Country", 70 | timeunit = "years", facet = TRUE, binwidth = 3, alpha = 0.7, title = TRUE) 71 | 72 | durPlot(life_exp, start = "Birth", end = "Death", group = "Country", 73 | timeunit = "years",alpha = 0.5, title = TRUE) 74 | } 75 | \author{ 76 | Dahee Lee 77 | } 78 | \seealso{ 79 | \code{\link{timelineS}}, \code{\link{timelineG}}, \code{\link{durSummary}}, \code{\link{durCalc}} 80 | } 81 | 82 | -------------------------------------------------------------------------------- /R/timelineG.R: -------------------------------------------------------------------------------- 1 | #' @title Faceted Timelines for Grouped Data 2 | #' @description Plots faceted timelines for grouped data. 3 | #' @usage 4 | #' timelineG(df, start, end, names, phase = NA, group1 = NA, group2 = NA, 5 | #' width = 2, color = "grey", theme = NULL, other = NULL) 6 | #' @param df Data frame containing start dates, end dates, groups, phases, and names for each timeline. 7 | #' @param start Column in df for start dates. 8 | #' @param end Column in df for end dates. 9 | #' @param names Column in df for names of each timeline 10 | #' @param phase Column in df for phases. 11 | #' @param group1 Column in df for groups to be used as the rows of the tabular display. Default is NA. 12 | #' @param group2 Column in df for groups to be used as the columns of the tabular display. Default is NA. 13 | #' @param width Width of each timeline. Default is 2. 14 | #' @param color Color of timelines, only used when \code{phase} is not provided. 15 | #' @param theme Add theme elements if needed. 16 | #' @param other Add other elements if needed. 17 | #' @seealso \code{\link{timelineS}} 18 | #' @examples 19 | #' ### Plot timelines row-grouped by "Country" 20 | #' timelineG(df = life_country, start = "Start", end = "End", names = "Name", 21 | #' phase = "Phase", group1 = "Country") 22 | #' 23 | #' ### Plot timelines row-grouped by "Country" and column-grouped by "Gender" 24 | #' timelineG(df = life_country, start = "Start", end = "End", names = "Name", 25 | #' phase = "Phase", group1 = "Country", group2 = "Gender") 26 | #' 27 | #' ### Plot timelines, no group 28 | #' timelineG(df = life_country, start = "Start", end = "End", names = "Name",color = "grey") 29 | #' 30 | #' @author Dahee Lee 31 | #' @import ggplot2 graphics 32 | #' @export 33 | #' 34 | 35 | timelineG <- function(df, start, end, names, phase = NA, group1 = NA, group2 = NA, 36 | width = 2, color = "grey", theme = NULL, other = NULL){ 37 | 38 | if(!is.data.frame(df)){ 39 | stop("'df' must be a data frame") 40 | } 41 | 42 | if(!(class(df[[start]]) == "Date") && (class(df[[end]]) == "Date")){ 43 | stop("'start' and 'end' must be dates") 44 | } 45 | 46 | facets <- if (is.na(group1) & is.na(group2)){ 47 | paste(names, "~.") 48 | } else if (is.na(group2)){ 49 | paste(group1, "~.") 50 | } else { 51 | paste(group1, "~", group2) 52 | } 53 | 54 | a <- if(is.na(phase)){ 55 | ggplot(df, aes_string(x = start, y = names)) + 56 | geom_segment(aes_string(x = start, xend = end, y = names, yend = names), size = width, color = color) 57 | } else { 58 | ggplot(df, aes_string(x = start, y = names, color = phase)) + 59 | geom_segment(aes_string(x = start, xend = end, y = names, yend = names), size = width) 60 | } 61 | 62 | a <- if (is.na(group1) & is.na(group2)){ 63 | a 64 | } else { 65 | a + facet_grid(facets, scales = "free_y", space = "free_y", drop = TRUE) 66 | } 67 | 68 | a <- a + theme + other 69 | plot(a) 70 | } 71 | -------------------------------------------------------------------------------- /man/timelineS.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/timelineS.R 3 | \name{timelineS} 4 | \alias{timelineS} 5 | \title{Timeline with Event Labels} 6 | \usage{ 7 | timelineS(df, main = NA, xlab = NA, buffer.days = 600, 8 | line.width = 5, line.color = "gray44", 9 | scale = "year", scale.format = "\%Y", scale.font = 2, scale.orient = 1, 10 | scale.above = FALSE, scale.cex = 1, scale.tickwidth = 2, 11 | labels = paste(df[[1]], df[[2]]), label.direction = "downup", 12 | label.length = c(0.5,0.5,0.8,0.8), label.position = c(1,3), 13 | label.color = "gray44", label.cex = 0.8, label.font = 1, label.angle = 0, 14 | pch = 20, point.cex = 1, point.color = "gray44") 15 | } 16 | \arguments{ 17 | \item{df}{Data frame for events and dates. First column for event names and second column for dates in \code{Date} class.} 18 | 19 | \item{main}{Title of the plot.} 20 | 21 | \item{xlab}{X axis label.} 22 | 23 | \item{buffer.days}{Additional days to add before and after the event dates on the timeline. Default is 600 days.} 24 | 25 | \item{line.width}{Timeline width; default 5} 26 | 27 | \item{line.color}{Timeline color.} 28 | 29 | \item{scale}{Scale on timeline. One of \code{"year","quarter", "month", "week" or "day"}. See \code{\link{seq.Date}}.} 30 | 31 | \item{scale.format}{Scale format; default \code{"\%Y"}.} 32 | 33 | \item{scale.font}{Integer specifying font of scale. Default is 2. (1:plain, 2:bold, 3:italic, 4:bold italic, 5:symbol).} 34 | 35 | \item{scale.orient}{Orientation of scale; default 1(upright)} 36 | 37 | \item{scale.above}{If \code{TRUE}, the scale shows above the line.} 38 | 39 | \item{scale.cex}{Scale font size relative to cex.} 40 | 41 | \item{scale.tickwidth}{Width of scale tick; default 2.} 42 | 43 | \item{labels}{Event labels. Events and corresponding dates as default.} 44 | 45 | \item{label.direction}{Direction of labels from timeline. \code{"downup","updown","up", or "down"}, default is \code{"downup"}. See details.} 46 | 47 | \item{label.length}{Distance of event label from the timeline. Could be a single value or a vector of lengths. 48 | Default is c(0.5, 0.5, 0.8, 0.8). See details.} 49 | 50 | \item{label.position}{Integer specifying label positions; default c(1,3). See details.} 51 | 52 | \item{label.color}{Label color(s).} 53 | 54 | \item{label.cex}{Font size(s) of event labels; default 0.8.} 55 | 56 | \item{label.font}{Integer specifying label font; default 1.} 57 | 58 | \item{label.angle}{Angle of text in the label.} 59 | 60 | \item{pch}{End point symbol(s).} 61 | 62 | \item{point.cex}{End points size(s).} 63 | 64 | \item{point.color}{End points color(s).} 65 | } 66 | \description{ 67 | Plots a horizontal timeline with event descriptions at corresponding dates. 68 | } 69 | \details{ 70 | \code{label.direction} indicates the direction of event labels from timeline. \code{"downup"} and \code{"updown"} plots 71 | alternating labels; \code{"up"} puts all the labels above and \code{"down"} below the timeline. 72 | 73 | \code{label.length} could be a single number or a numeric vector. For label directions \code{"downup"} and \code{"updown"}, use between 0 and 0.9, and for 74 | \code{"up"} and \code{"down"}, use between 0 and 1.6. 75 | For example, \code{label.length = 0.5} produces all the labels at equal lengths, and \code{label.length = c(0.5,0.5,0.8,0.8)} 76 | repeats the sequence of lengths. 77 | 78 | The positions for \code{label.position} are 1: below 2: left 3: above 4: right. 79 | } 80 | \examples{ 81 | ### Default down-up labels 82 | timelineS(mj_life, main = "Life of Michael Jackson") 83 | 84 | ### Labels above timeline and other change in aesthetics 85 | timelineS(mj_life, main = "Life of Michael Jackson", 86 | label.direction = "up", label.length = c(0.2,0.8,0.4,1.2), label.position = 3, 87 | line.color = "blue", label.color = "blue", point.color = "blue", pch = "-") 88 | 89 | } 90 | \author{ 91 | Dahee Lee 92 | } 93 | \seealso{ 94 | \code{\link{axis.Date}}, \code{\link{timelineG}}, \code{\link{durCalc}}, \code{\link{durPlot}} 95 | } 96 | 97 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | timelineS 3 | ========= 4 | 5 | > An easy tool for visualizing, annotating, and stratifying time series data. 6 | 7 | [![CRAN Status Badge](http://www.r-pkg.org/badges/version/timelineS)](http://cran.r-project.org/package=timelineS) [![CRAN Downloads](http://cranlogs.r-pkg.org/badges/timelineS)](https://cran.r-project.org/package=timelineS) [![CRAN Total downloads](http://cranlogs.r-pkg.org/badges/grand-total/timelineS)](http://cran.r-project.org/package=timelineS) 8 | 9 | This package contains five functions as below. 10 | 11 | - `timelineS`: Plots a horizontal timeline with event descriptions at corresponding dates. 12 | - `timelineG`: Plots faceted timelines for grouped data. 13 | - `durPlot`: Plots boxplot, histogram, density plot, scatter plot, line plot and prints summary statistics for date duration data. 14 | - `durCalc`: Calculates the duration between two dates, use it as a filter to select rows that satisfy the length criteria. Returns the dataset with additional columns regarding the length of durations in different units. 15 | - `durSummary`: Returns summary statistics for date duration data. 16 | 17 | Install 18 | ------- 19 | 20 | - from [CRAN](https://cran.r-project.org/package=timelineS): 21 | 22 | ``` r 23 | install.packages("timelineS") 24 | ``` 25 | 26 | - latest version on [GitHub](https://github.com/daheelee/timelineS): 27 | 28 | ``` r 29 | devtools::install_github("daheelee/timelineS") 30 | ``` 31 | 32 | Usage example 33 | ------------- 34 | 35 | ### timelineS 36 | 37 | `timelineS` plots an annotated timeline. 38 | 39 | ``` r 40 | timelineS(mj_life, main = "Life of Michael Jackson") 41 | ``` 42 | 43 | ![](README-MJ.png) 44 | 45 | You can also change the aesthetics. 46 | 47 | ``` r 48 | timelineS(mj_life, main = "Life of Michael Jackson", 49 | label.direction = "up", label.length = c(0.2,0.8,0.4,1.2), label.position = 3, 50 | line.color = "blue", label.color = "blue", point.color = "blue", pch = "-") 51 | ``` 52 | 53 | ![](README-MJ2.png) 54 | 55 | ### timelineG 56 | 57 | `timelineG` creates stacked timelines, faceted by groups. 58 | 59 | ``` r 60 | timelineG(df=life_country, start="Start", end="End", names="Name", 61 | phase="Phase", group1="Country", group2="Gender") 62 | ``` 63 | 64 | ![](README-group.png) 65 | 66 | ### durPlot 67 | 68 | `durPlot` function gives five different plots by default. You can set `facet=TRUE` to get faceted plots. 69 | 70 | ``` r 71 | durPlot(life_exp, start="Birth", end="Death", group="Country", timeunit="years", facet=TRUE, binwidth=3, alpha=0.7, title=TRUE) 72 | ``` 73 | 74 | ![](README-box.png) ![](README-hist.png) ![](README-density.png) ![](README-scatter.png) ![](README-line.png) 75 | 76 | `durPlot` also gives a summary of the duration lengths with the plots. 77 | 78 | ### durSummary 79 | 80 | `durSummary` is a simpler function if you only want the summary. 81 | 82 | ``` r 83 | durSummary(life_exp, start="Birth", end="Death", group="Country", timeunit="years") 84 | ``` 85 | 86 | ``` r 87 | Country min Qt1 median mean Qt3 max sd 88 | 1 Australia 67.19 72.16 76.26 75.72 78.98 85.71 5.30 89 | 2 China 67.41 70.09 76.06 76.44 83.38 87.56 7.14 90 | 3 France 64.02 68.16 74.48 74.89 79.10 89.37 7.59 91 | 4 Japan 69.35 75.14 77.76 77.63 80.57 85.33 4.82 92 | 5 US 62.73 72.04 76.21 75.35 79.00 85.45 5.49 93 | ``` 94 | 95 | ### durCalc 96 | 97 | `durCalc` filters a data frame using duration lengths. Let's say we have a dataset that has dates of birth and death of people. We can filter out people(rows) who lived longer than 85 years. You can also do `filterlonger=FALSE` to select rows that are shorter than some time length. 98 | 99 | ``` r 100 | durCalc(life_exp, start="Birth", end="Death", timeunit="years", filterlength=85) 101 | ``` 102 | 103 | The output has a few extra duration information in specified `timeunit` and also in calendar units. 104 | 105 | ``` r 106 | Name Country Gender Birth Death days diff_years diff_length longer_by 107 | 8 Susan Australia Female 1920-05-26 2006-02-10 31306 85.71 85years 8months 16days 8months 16days 108 | 19 Mai Japan Female 1923-10-12 2009-02-07 31165 85.33 85years 3months 27days 3months 27days 109 | 24 Leo France Male 1920-06-28 2009-11-09 32641 89.37 89years 4months 12days 4years 4months 12days 110 | 48 Gloria US Female 1926-03-01 2011-08-14 31212 85.45 85years 5months 14days 5months 14days 111 | 60 Ming China Female 1920-09-06 2008-03-31 31983 87.56 87years 6months 24days 2years 6months 24days 112 | ``` 113 | 114 | If you want to know how old each person would be as of January 1, 2000, you can do: 115 | 116 | ``` r 117 | durCalc(life_exp, start="Birth", end=as.Date("2000-1-1"), timeunit="years") 118 | ``` 119 | 120 | ``` r 121 | Name Country Gender Birth Death days diff_length 122 | 1 Edward Australia Male 1927-11-17 1999-12-16 26343 72years 1month 15days 123 | 2 James Australia Male 1925-11-20 1993-01-27 27070 74years 1month 11days 124 | 3 Mark Australia Male 1926-06-11 2003-12-26 26867 73years 6months 21days 125 | 4 Fred Australia Male 1927-01-22 2002-07-19 26642 72years 11months 9days 126 | 5 Phil Australia Male 1923-06-20 2003-01-15 27954 76years 6months 12days 127 | ... 128 | ``` 129 | 130 | Or you can simply use this as a unit-converter between two dates. 131 | 132 | ``` r 133 | durCalc(start=as.Date("2010-12-1"), end=as.Date("2015-4-26"), timeunit="weeks") 134 | ``` 135 | 136 | ``` r 137 | days diff_weeks diff_length 138 | 1 1607 229.57 4years 4months 24days 139 | ``` 140 | 141 | Release History 142 | --------------- 143 | 144 | - 0.1.0 145 | - First upload 146 | 147 | Meta 148 | ---- 149 | 150 | Dahee Lee – 151 | 152 | Distributed under the GPL-2 license. 153 | 154 | [https://github.com/daheelee/timelineS](https://github.com/daheelee/) 155 | -------------------------------------------------------------------------------- /R/durCalc.R: -------------------------------------------------------------------------------- 1 | #' @title Filter Dataset by Date Duration 2 | #' @description Calculates the duration between two dates, use it as a filter to select rows that satisfy the length criteria. 3 | #' Returns the dataset with additional columns regarding the length of durations in different units. 4 | #' @usage 5 | #' durCalc(df = NULL, start, end, timeunit = "day", filterlength = NA, 6 | #' filterlonger = TRUE, year = 365.25, month = 30.42) 7 | #' @param df Data frame containing start and end dates. 8 | #' @param start Column in df for start dates or a date to use as start date. 9 | #' @param end Column in df for end dates or a date to use as a end date. 10 | #' @param timeunit Unit of time to be used in plots. \code{"day(s)"}, \code{"week(s)"}, \code{"month(s)"}, \code{"quarter(s)"}, \code{"semiannual"}, \code{"halfyear"},or \code{"year(s)"}. 11 | #' @param filterlength A time length to use as filter. 12 | #' @param filterlonger If TRUE, the function gives rows with longer durations than specified in filterlength. If FALSE, gives rows with shorter durations. 13 | #' @param year Number of days to use as a year. Default is 365.25. 14 | #' @param month Number of days to use as a month. Default is 30.42. 15 | #' @details 16 | #' Additional columns returned with the filtered rows are: length of duration in days, in specified time unit, and in calendar units, and 17 | #' how much longer/shorter the durations are compared to filter length in calendar units. 18 | #' 19 | #' If no \code{filterlength} is provided, then returns all rows with length of duration in days and calendar units. 20 | #' 21 | #' You can use dates for \code{start} and \code{end} and provide no \code{df} to get the length of duration between the dates in calendar units. See example. 22 | #' @return A subset of original data frame with additional columns in specified time units and calendar units. 23 | #' @seealso \code{\link{durPlot}}, \code{\link{durSummary}} 24 | #' @examples 25 | #' ### Filter people who lived longer than 85 years 26 | #' durCalc(life_exp, start = "Birth", end = "Death", timeunit = "years", filterlength = 85) 27 | #' 28 | #' ### How old each person would be as of January 1, 2000 if they were alive 29 | #' durCalc(life_exp, start = "Birth", end = as.Date("2000-1-1"), timeunit = "years") 30 | #' 31 | #' ### Use as unit-converter between two dates 32 | #' durCalc(start = as.Date("2010-12-1"), end = as.Date("2015-4-26"), timeunit = "weeks") 33 | #' @author Dahee Lee 34 | #' @export 35 | 36 | durCalc <- function(df = NULL, start, end, timeunit = "day", 37 | filterlength = NA, filterlonger = TRUE, year = 365.25, month = 30.42){ 38 | 39 | if(is.null(start)){stop("'start' needed")} 40 | if(is.null(end)){stop("'end' needed")} 41 | 42 | # Make duration data for calculation 43 | if (!is.null(df)){ 44 | if (class(end) == "Date" & class(start) == "character"){ 45 | df$days <- as.numeric(end - df[[start]]) 46 | } else if (class(start) == "Date" & class(end) == "character"){ 47 | df$days <- as.numeric(df[[end]] - start) 48 | } else if (class(start) == "character" & class(end) == "character") { 49 | df$days <- as.numeric(df[[end]] - df[[start]]) 50 | } else { 51 | stop("'start and 'end' have to be dates or column names in 'df'") 52 | } 53 | 54 | # Remove missing rows 55 | df <- df[!is.na(df$days),] 56 | 57 | } else { 58 | 59 | if (class(start) == "Date" & class(end) == "Date"){ 60 | days <- as.numeric(end-start) 61 | } else { 62 | stop("'start and 'end' have to be dates") 63 | } 64 | 65 | } 66 | 67 | # Change Time unit 68 | unit <- if(timeunit %in% c("year","years")){ 69 | 1 / year 70 | } else if (timeunit %in% c("semiannual", "halfyear")){ 71 | 2 / year 72 | } else if (timeunit %in% c("quarter", "quarters")){ 73 | 4 / year 74 | } else if (timeunit %in% c("month", "months")){ 75 | 1 / month 76 | } else if (timeunit %in% c("week", "weeks")){ 77 | 1 / 7 78 | } else if (timeunit %in% c("day", "days")){ 79 | 1 80 | } else { 81 | warning("invalid 'timeunit': default 'days' used") 82 | 1 } 83 | 84 | # Make diff_timeunit column 85 | if (!is.null(df)){ 86 | if(!is.na(filterlength)){ 87 | df$diff_timeunit <- df$days*unit 88 | } 89 | } else { 90 | diff_timeunit <- days*unit 91 | } 92 | 93 | # Duration in calendar terms 94 | calc_diffdays <- function(days){ 95 | 96 | # Year 97 | Yr <- floor(days / year) 98 | outputYr <- paste0(Yr, ifelse(Yr > 1, "years ", "year ")) 99 | remaining_days <- days %% year 100 | 101 | # Month 102 | M <- floor(remaining_days / month) 103 | outputM <- paste0(M, ifelse(M > 1, "months ", "month ")) 104 | 105 | # Day 106 | D <- remaining_days %% month 107 | 108 | # Paste Y-M-D 109 | outputStr <- paste0(if(Yr >= 1){outputYr}, if(M >= 1){outputM}, round(D,0), ifelse(D > 1, "days", "day")) 110 | 111 | return(outputStr) 112 | } 113 | 114 | # Select 115 | if(!is.null(df)){ 116 | 117 | if (is.na(filterlength)){ 118 | df$diff_length <- sapply(df$days, calc_diffdays) 119 | 120 | } else { 121 | 122 | if (filterlonger == TRUE){ 123 | df <- df[df$diff_timeunit > filterlength, ] 124 | df$diff_timeunit <- round(df$days * unit,2) 125 | df$late_days <- df$days - filterlength / unit 126 | df$diff_length <- sapply(df$days, calc_diffdays) 127 | df$longer_by <- sapply(df$late_days, calc_diffdays) 128 | names(df)[names(df) == "diff_timeunit"] <- paste0("diff_", timeunit) 129 | df$late_days <- NULL 130 | 131 | } else { 132 | 133 | df <- df[df$diff_timeunit < filterlength, ] 134 | df$diff_timeunit <- round(df$days * unit, 2) 135 | df$early_days <- filterlength / unit - df$days 136 | df$diff_length <- sapply(df$days, calc_diffdays) 137 | df$shorter_by <- sapply(df$early_days, calc_diffdays) 138 | names(df)[names(df) == "diff_timeunit"] <- paste0("diff_", timeunit) 139 | df$early_days <- NULL 140 | } 141 | } 142 | 143 | } else { 144 | 145 | diff_timeunit <- round(days * unit,2) 146 | diff_length <- calc_diffdays(days) 147 | df <- data.frame(days, diff_timeunit, diff_length) 148 | names(df)[names(df) == "diff_timeunit"] <- paste0("diff_", timeunit) 149 | } 150 | 151 | # Print result 152 | if (nrow(df) == 0){ 153 | print("No data meeting criteria") 154 | } else {return(df)} 155 | } 156 | -------------------------------------------------------------------------------- /README.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | output: github_document 3 | --- 4 | 5 | ```{r, echo = FALSE} 6 | knitr::opts_chunk$set( 7 | collapse = TRUE, 8 | comment = "#>", 9 | fig.path = "README-" 10 | ) 11 | ``` 12 | # timelineS 13 | > An easy tool for visualizing, annotating, and stratifying time series data. 14 | 15 | [![CRAN Status Badge](http://www.r-pkg.org/badges/version/timelineS)](http://cran.r-project.org/package=timelineS) 16 | [![CRAN Downloads](http://cranlogs.r-pkg.org/badges/timelineS)](https://cran.r-project.org/package=timelineS) 17 | [![CRAN Total downloads](http://cranlogs.r-pkg.org/badges/grand-total/timelineS)](http://cran.r-project.org/package=timelineS) 18 | 19 | This package contains five functions as below. 20 | 21 | * `timelineS`: Plots a horizontal timeline with event descriptions at corresponding dates.\ 22 | * `timelineG`: Plots faceted timelines for grouped data.\ 23 | * `durPlot`: Plots boxplot, histogram, density plot, scatter plot, line plot and prints summary statistics for date duration data.\ 24 | * `durCalc`: Calculates the duration between two dates, use it as a filter to select rows that satisfy the length criteria. Returns the dataset with additional columns regarding the length of durations in different units.\ 25 | * `durSummary`: Returns summary statistics for date duration data. 26 | 27 | ## Install 28 | - from [CRAN](https://cran.r-project.org/package=timelineS): 29 | 30 | ```{r, eval=FALSE} 31 | install.packages("timelineS") 32 | ``` 33 | 34 | - latest version on [GitHub](https://github.com/daheelee/timelineS): 35 | 36 | ```{r, eval=FALSE} 37 | devtools::install_github("daheelee/timelineS") 38 | ``` 39 | 40 | ## Usage example 41 | 42 | ###timelineS 43 | `timelineS` plots an annotated timeline. 44 | ```{r, eval=FALSE} 45 | timelineS(mj_life, main = "Life of Michael Jackson") 46 | ``` 47 | ![](README-MJ.png) 48 | 49 | You can also change the aesthetics. 50 | ```{r, eval=FALSE} 51 | timelineS(mj_life, main = "Life of Michael Jackson", 52 | label.direction = "up", label.length = c(0.2,0.8,0.4,1.2), label.position = 3, 53 | line.color = "blue", label.color = "blue", point.color = "blue", pch = "-") 54 | ``` 55 | ![](README-MJ2.png) 56 | 57 | ###timelineG 58 | `timelineG` creates stacked timelines, faceted by groups. 59 | ```{r, eval=FALSE} 60 | timelineG(df=life_country, start="Start", end="End", names="Name", 61 | phase="Phase", group1="Country", group2="Gender") 62 | ``` 63 | ![](README-group.png) 64 | 65 | ###durPlot 66 | `durPlot` function gives five different plots by default. You can set `facet=TRUE` to get faceted plots. 67 | ```{r, eval=FALSE} 68 | durPlot(life_exp, start="Birth", end="Death", group="Country", timeunit="years", facet=TRUE, binwidth=3, alpha=0.7, title=TRUE) 69 | ``` 70 | ![](README-box.png) 71 | ![](README-hist.png) 72 | ![](README-density.png) 73 | ![](README-scatter.png) 74 | ![](README-line.png) 75 | 76 | `durPlot` also gives a summary of the duration lengths with the plots. 77 | 78 | ###durSummary 79 | `durSummary` is a simpler function if you only want the summary. 80 | ```{r, eval=FALSE} 81 | durSummary(life_exp, start="Birth", end="Death", group="Country", timeunit="years") 82 | ``` 83 | 84 | ```{r, eval=FALSE} 85 | Country min Qt1 median mean Qt3 max sd 86 | 1 Australia 67.19 72.16 76.26 75.72 78.98 85.71 5.30 87 | 2 China 67.41 70.09 76.06 76.44 83.38 87.56 7.14 88 | 3 France 64.02 68.16 74.48 74.89 79.10 89.37 7.59 89 | 4 Japan 69.35 75.14 77.76 77.63 80.57 85.33 4.82 90 | 5 US 62.73 72.04 76.21 75.35 79.00 85.45 5.49 91 | ``` 92 | 93 | ###durCalc 94 | `durCalc` filters a data frame using duration lengths. Let's say we have a dataset that has dates of birth and death of people. 95 | We can filter out people(rows) who lived longer than 85 years. You can also do `filterlonger=FALSE` to select rows that are shorter than some time length. 96 | ```{r, eval=FALSE} 97 | durCalc(life_exp, start="Birth", end="Death", timeunit="years", filterlength=85) 98 | ``` 99 | The output has a few extra duration information in specified `timeunit` and also in calendar units. 100 | ```{r, eval=FALSE} 101 | Name Country Gender Birth Death days diff_years diff_length longer_by 102 | 8 Susan Australia Female 1920-05-26 2006-02-10 31306 85.71 85years 8months 16days 8months 16days 103 | 19 Mai Japan Female 1923-10-12 2009-02-07 31165 85.33 85years 3months 27days 3months 27days 104 | 24 Leo France Male 1920-06-28 2009-11-09 32641 89.37 89years 4months 12days 4years 4months 12days 105 | 48 Gloria US Female 1926-03-01 2011-08-14 31212 85.45 85years 5months 14days 5months 14days 106 | 60 Ming China Female 1920-09-06 2008-03-31 31983 87.56 87years 6months 24days 2years 6months 24days 107 | ``` 108 | If you want to know how old each person would be as of January 1, 2000, you can do: 109 | ```{r, eval=FALSE} 110 | durCalc(life_exp, start="Birth", end=as.Date("2000-1-1"), timeunit="years") 111 | ``` 112 | 113 | ```{r, eval=FALSE} 114 | Name Country Gender Birth Death days diff_length 115 | 1 Edward Australia Male 1927-11-17 1999-12-16 26343 72years 1month 15days 116 | 2 James Australia Male 1925-11-20 1993-01-27 27070 74years 1month 11days 117 | 3 Mark Australia Male 1926-06-11 2003-12-26 26867 73years 6months 21days 118 | 4 Fred Australia Male 1927-01-22 2002-07-19 26642 72years 11months 9days 119 | 5 Phil Australia Male 1923-06-20 2003-01-15 27954 76years 6months 12days 120 | ... 121 | ``` 122 | Or you can simply use this as a unit-converter between two dates. 123 | ```{r, eval=FALSE} 124 | durCalc(start=as.Date("2010-12-1"), end=as.Date("2015-4-26"), timeunit="weeks") 125 | ``` 126 | ```{r, eval=FALSE} 127 | days diff_weeks diff_length 128 | 1 1607 229.57 4years 4months 24days 129 | ``` 130 | ## Release History 131 | 132 | * 0.1.0 133 | * First upload 134 | 135 | 136 | ## Meta 137 | 138 | Dahee Lee – dhlee99@gmail.com 139 | 140 | Distributed under the GPL-2 license. 141 | 142 | [https://github.com/daheelee/timelineS](https://github.com/daheelee/) 143 | 144 | [npm-image]: https://img.shields.io/npm/v/datadog-metrics.svg?style=flat-square 145 | [npm-url]: https://npmjs.org/package/datadog-metrics 146 | [npm-downloads]: https://img.shields.io/npm/dm/datadog-metrics.svg?style=flat-square 147 | [travis-image]: https://img.shields.io/travis/dbader/node-datadog-metrics/master.svg?style=flat-square 148 | [travis-url]: https://travis-ci.org/dbader/node-datadog-metrics 149 | 150 | -------------------------------------------------------------------------------- /R/timelineS.R: -------------------------------------------------------------------------------- 1 | #' @title Timeline with Event Labels 2 | #' @description Plots a horizontal timeline with event descriptions at corresponding dates. 3 | #' @usage 4 | #' timelineS(df, main = NA, xlab = NA, buffer.days = 600, 5 | #' line.width = 5, line.color = "gray44", 6 | #' scale = "year", scale.format = "\%Y", scale.font = 2, scale.orient = 1, 7 | #' scale.above = FALSE, scale.cex = 1, scale.tickwidth = 2, 8 | #' labels = paste(df[[1]], df[[2]]), label.direction = "downup", 9 | #' label.length = c(0.5,0.5,0.8,0.8), label.position = c(1,3), 10 | #' label.color = "gray44", label.cex = 0.8, label.font = 1, label.angle = 0, 11 | #' pch = 20, point.cex = 1, point.color = "gray44") 12 | #' @param df Data frame for events and dates. First column for event names and second column for dates in \code{Date} class. 13 | #' @param main Title of the plot. 14 | #' @param xlab X axis label. 15 | #' @param buffer.days Additional days to add before and after the event dates on the timeline. Default is 600 days. 16 | #' @param line.width Timeline width; default 5 17 | #' @param line.color Timeline color. 18 | #' @param scale Scale on timeline. One of \code{"year","quarter", "month", "week" or "day"}. See \code{\link{seq.Date}}. 19 | #' @param scale.format Scale format; default \code{"\%Y"}. 20 | #' @param scale.font Integer specifying font of scale. Default is 2. (1:plain, 2:bold, 3:italic, 4:bold italic, 5:symbol). 21 | #' @param scale.orient Orientation of scale; default 1(upright) 22 | #' @param scale.above If \code{TRUE}, the scale shows above the line. 23 | #' @param scale.cex Scale font size relative to cex. 24 | #' @param scale.tickwidth Width of scale tick; default 2. 25 | #' @param labels Event labels. Events and corresponding dates as default. 26 | #' @param label.direction Direction of labels from timeline. \code{"downup","updown","up", or "down"}, default is \code{"downup"}. See details. 27 | #' @param label.length Distance of event label from the timeline. Could be a single value or a vector of lengths. 28 | #' Default is c(0.5, 0.5, 0.8, 0.8). See details. 29 | #' @param label.position Integer specifying label positions; default c(1,3). See details. 30 | #' @param label.color Label color(s). 31 | #' @param label.cex Font size(s) of event labels; default 0.8. 32 | #' @param label.font Integer specifying label font; default 1. 33 | #' @param label.angle Angle of text in the label. 34 | #' @param pch End point symbol(s). 35 | #' @param point.cex End points size(s). 36 | #' @param point.color End points color(s). 37 | #' @details 38 | #' \code{label.direction} indicates the direction of event labels from timeline. \code{"downup"} and \code{"updown"} plots 39 | #' alternating labels; \code{"up"} puts all the labels above and \code{"down"} below the timeline. 40 | #' 41 | #' \code{label.length} could be a single number or a numeric vector. For label directions \code{"downup"} and \code{"updown"}, use between 0 and 0.9, and for 42 | #' \code{"up"} and \code{"down"}, use between 0 and 1.6. 43 | #' For example, \code{label.length = 0.5} produces all the labels at equal lengths, and \code{label.length = c(0.5,0.5,0.8,0.8)} 44 | #' repeats the sequence of lengths. 45 | #' 46 | #' The positions for \code{label.position} are 1: below 2: left 3: above 4: right. 47 | #' @examples 48 | #' ### Default down-up labels 49 | #' timelineS(mj_life, main = "Life of Michael Jackson") 50 | #' 51 | #' ### Labels above timeline and other change in aesthetics 52 | #' timelineS(mj_life, main = "Life of Michael Jackson", 53 | #' label.direction = "up", label.length = c(0.2,0.8,0.4,1.2), label.position = 3, 54 | #' line.color = "blue", label.color = "blue", point.color = "blue", pch = "-") 55 | #' 56 | #' @author Dahee Lee 57 | #' @seealso \code{\link{axis.Date}}, \code{\link{timelineG}}, \code{\link{durCalc}}, \code{\link{durPlot}} 58 | #' @import graphics 59 | #' @export 60 | 61 | timelineS <- function(df, main = NA, xlab = NA, buffer.days = 600, 62 | line.width = 5, line.color = "gray44", 63 | scale = "year", scale.format = "%Y", scale.font = 2, scale.orient = 1, 64 | scale.above = FALSE, scale.cex = 1, scale.tickwidth = 2, 65 | labels = paste(df[[1]], df[[2]]), label.direction = "downup", 66 | label.length = c(0.5,0.5,0.8,0.8), label.position = c(1,3), 67 | label.color = "gray44", label.cex = 0.8, label.font = 1, label.angle = 0, 68 | pch = 20, point.cex = 1, point.color = "gray44") 69 | { 70 | 71 | if(!is.data.frame(df)){ 72 | stop("'df' must be a data frame") 73 | } 74 | 75 | # Remove NA rows 76 | df <- df[rowSums(is.na(df)) == 0,] 77 | event.names <- df[[1]] 78 | event.dates <- df[[2]] 79 | 80 | # Change direction and where to put the timeline 81 | if (label.direction == "downup"){ 82 | d = c(-1, 1) 83 | h = 0 84 | } else if (label.direction == "updown"){ 85 | d = c(1, -1) 86 | h = 0 87 | } else if (label.direction == "up"){ 88 | d = 1 89 | h = -0.7 90 | } else if (label.direction == "down"){ 91 | d = -1 92 | h = 0.7 93 | } else { 94 | d = c(-1, 1) 95 | h = 0 96 | print("incorrect label.direction, plot used default") 97 | } 98 | 99 | # Make line, points and segments 100 | range.events <- range(min(event.dates) - buffer.days, max(event.dates) + buffer.days) 101 | r1 <- range.events[1] 102 | r2 <- range.events[2] 103 | plot(NA, ylim = c(-1,1), xlim = range.events, ann = FALSE, axes = FALSE) 104 | title(main = main, xlab = xlab) 105 | points <- rep_len(d * label.length, length.out = nrow(df)) 106 | events <- rep_len(label.position, length.out = nrow(df)) 107 | segments(event.dates, h, event.dates, points + h, col = label.color) 108 | 109 | # Add Scale 110 | axis.Date( 111 | ifelse(scale.above == TRUE, 3, 1), 112 | at = seq(as.Date(paste0(lubridate::year(r1), "-", lubridate::month(r1), "-", 1)), 113 | as.Date(paste0(lubridate::year(r2), "-", lubridate::month(r2)+1,"-", 1)), by=scale), 114 | format = scale.format, 115 | cex.axis = scale.cex, 116 | pos = h, 117 | lwd.tick = scale.tickwidth, 118 | col = line.color, 119 | font = scale.font, 120 | las = scale.orient) 121 | 122 | abline(h = h, lwd = line.width, col = line.color) 123 | 124 | # Add Event Labels 125 | points(x = event.dates, y = points+h, pch = pch, cex = point.cex, col = point.color) 126 | text(x = event.dates, y = points+h, labels = labels, cex = label.cex, pos = events, font = label.font, srt = label.angle) 127 | } 128 | 129 | 130 | -------------------------------------------------------------------------------- /R/durPlot.R: -------------------------------------------------------------------------------- 1 | #' @title Graphs and Summary for Date Durations 2 | #' @description Plots boxplot, histogram, density plot, scatter plot, line plot and prints summary statistics for date duration data. 3 | #' @usage 4 | #' durPlot(df, start, end, group = NA, timeunit = "days", plot_type = "all", 5 | #' facet = FALSE, facet.nrow = NULL, theme = NULL, other = NULL, 6 | #' fill_color = "black", line_color = "black", groupcolor = TRUE, 7 | #' point_size = 2, alpha = NA, binwidth = 0.5, show_legend = TRUE, 8 | #' title=FALSE, title_boxplot = "Boxplot", title_histogram = "Histogram", 9 | #' title_density = "Density Plot", title_scatter = "Scatter Plot", 10 | #' title_line = "Line Plot") 11 | #' @param df Data frame containing start dates, end dates and groups. 12 | #' @param start Column in df for start dates. 13 | #' @param end Column in df for end dates. 14 | #' @param group Column in df for groups. Default is NA. 15 | #' @param timeunit Unit of time to be used in plots. \code{"day(s)"}, \code{"week(s)"}, \code{"month(s)"}, \code{"quarter(s)"}, \code{"semiannual"}, \code{"halfyear"},or \code{"year(s)"}. 16 | #' @param plot_type One of \code{"all", "boxplot", "histogram", "density", "scatter", "line"}. Default is \code{"all"}. 17 | #' @param facet If TRUE, wraps plots in group facets 18 | #' @param facet.nrow Number of rows for facet wrap 19 | #' @param theme Add theme elements if needed. 20 | #' @param other Add other elements if needed. 21 | #' @param fill_color Fill color 22 | #' @param line_color Line color 23 | #' @param groupcolor If FALSE, fill_color and line_color used for all groups. Default is TRUE. 24 | #' @param point_size Point size for scatterplot 25 | #' @param alpha Color transparency [0,1] 26 | #' @param binwidth Binwidth for histogram; default 0.5. 27 | #' @param show_legend Default is TRUE 28 | #' @param title If TRUE, puts main titles for each plot 29 | #' @param title_boxplot Title for boxplot title 30 | #' @param title_histogram Title for histogram 31 | #' @param title_density Title for density plot 32 | #' @param title_scatter Title for scatter plot 33 | #' @param title_line Title for line plot 34 | #' @details The function also returns summary statistics for the specified date duration. 35 | #' @seealso \code{\link{timelineS}}, \code{\link{timelineG}}, \code{\link{durSummary}}, \code{\link{durCalc}} 36 | #' @examples 37 | #' durPlot(life_exp, start = "Birth", end = "Death", group = "Country", 38 | #' timeunit = "years", facet = TRUE, binwidth = 3, alpha = 0.7, title = TRUE) 39 | #' 40 | #' durPlot(life_exp, start = "Birth", end = "Death", group = "Country", 41 | #' timeunit = "years",alpha = 0.5, title = TRUE) 42 | #' @author Dahee Lee 43 | #' @import ggplot2 magrittr dplyr 44 | #' @export 45 | 46 | durPlot <- function(df, start, end, group = NA, timeunit = "days", plot_type = "all", 47 | facet = FALSE, facet.nrow = NULL, theme = NULL, other = NULL, 48 | fill_color = "black", line_color = "black", groupcolor = TRUE, 49 | point_size = 2, alpha = NA, binwidth = 0.5, show_legend = TRUE, 50 | title=FALSE, title_boxplot = "Boxplot", title_histogram = "Histogram", 51 | title_density = "Density Plot", title_scatter = "Scatter Plot", 52 | title_line = "Line Plot"){ 53 | 54 | if(!is.data.frame(df)){ 55 | stop("'df' must be a data frame") 56 | } 57 | 58 | if(!(class(df[[start]]) == "Date") && (class(df[[end]]) == "Date")){ 59 | stop("'start' and 'end' must be dates") 60 | } 61 | 62 | # Remove NA rows 63 | df <- df[rowSums(is.na(df[,c(start,end)])) == 0,] 64 | 65 | # Make duration data 66 | df$duration <- as.numeric(df[[end]]-df[[start]]) 67 | 68 | # Change Time unit 69 | df$duration <- if(timeunit %in% c("year","years")){ 70 | df$duration / 365.25 71 | } else if (timeunit %in% c("semiannual", "halfyear")){ 72 | df$duration / 365.25*2 73 | } else if (timeunit %in% c("quarter", "quarters")){ 74 | df$duration / 365.25*4 75 | } else if (timeunit %in% c("month", "months")){ 76 | df$duration / 30.42 77 | } else if (timeunit %in% c("week", "weeks")){ 78 | df$duration / 52.14 79 | } else if (timeunit %in% c("day", "days")){ 80 | df$duration 81 | } else { 82 | warning("invalid 'timeunit': default 'days' used") 83 | df$duration } 84 | 85 | # No Group 86 | if (is.na(group)){ 87 | 88 | b <-ggplot(df, aes_string(x = factor(""), y = "duration")) + geom_boxplot(alpha = alpha, fill = fill_color, color = line_color) + xlab("") 89 | h <-ggplot(df, aes_string(x = "duration")) + geom_histogram(alpha = alpha, fill = fill_color, color = line_color, binwidth = binwidth) 90 | d <-ggplot(df, aes_string(x = "duration")) + geom_density(alpha = alpha, fill = fill_color, color = line_color) 91 | s <-ggplot(df, aes_string(x = start, y = "duration")) + geom_point(alpha = alpha, fill = fill_color, color = line_color, size = point_size) 92 | l <-ggplot(df, aes_string(x = start, y = "duration")) + geom_line(alpha = alpha, color = line_color) 93 | 94 | # Group 95 | } else { 96 | 97 | b <- ggplot(df, aes_string(x = group, y = "duration")) 98 | h <- ggplot(df, aes_string(x = "duration")) 99 | d <- ggplot(df, aes_string(x = "duration")) 100 | s <- ggplot(df, aes_string(x = start, y = "duration", group = group)) 101 | sf <- ggplot(df, aes_string(x = start, y = "duration")) + geom_point(data = df[, !(colnames(df) %in% group)], color = "grey85", size = point_size) 102 | l <- ggplot(df, aes_string(x = start, y = "duration")) 103 | 104 | # Group color 105 | if(groupcolor){ 106 | 107 | b <- b + geom_boxplot(aes_string(fill = group, color = group), alpha = alpha, show.legend = show_legend, outlier.size = point_size) 108 | h <- h + geom_histogram(aes_string(fill = group, color = group), alpha = alpha, show.legend = show_legend, binwidth = binwidth) 109 | d <- d + geom_density(aes_string(fill = group, color = group), alpha = alpha, show.legend = show_legend) 110 | s <- s + geom_point(aes_string(fill = group, color = group), alpha = alpha, show.legend = show_legend, size = point_size) 111 | sf<- sf + geom_point(aes_string(fill = group, color = group), alpha = alpha, show.legend = show_legend, size = point_size) 112 | l <- l + geom_line(aes_string(color = group), alpha = alpha, show.legend = show_legend) 113 | 114 | } else { 115 | 116 | b <- b + geom_boxplot(fill = fill_color, color = line_color, alpha = alpha, show.legend = show_legend, outlier.size = point_size) 117 | h <- h + geom_histogram(fill = fill_color, color = line_color, alpha = alpha, show.legend = show_legend, binwidth = binwidth) 118 | d <- d + geom_density(fill = fill_color, color = line_color, alpha = alpha, show.legend = show_legend) 119 | s <- s + geom_point(fill = fill_color, color = line_color, alpha = alpha, show.legend = show_legend, size = point_size) 120 | sf<- sf + geom_point(fill = fill_color, color = line_color, alpha = alpha, show.legend = show_legend, size = point_size) 121 | l <- l + geom_line(color = line_color, alpha = alpha, show.legend = show_legend) 122 | } 123 | } 124 | 125 | # Facet 126 | if(is.na(group)){ 127 | facet = FALSE 128 | } 129 | 130 | if(facet){ 131 | b <- b 132 | h <- h + facet_wrap(stats::as.formula(paste("~",group)), nrow = facet.nrow) 133 | d <- d + facet_wrap(stats::as.formula(paste("~",group)), nrow = facet.nrow) 134 | s <- sf + facet_wrap(stats::as.formula(paste("~",group)), nrow = facet.nrow) 135 | l <- l + facet_wrap(stats::as.formula(paste("~",group)), nrow = facet.nrow) 136 | } 137 | 138 | # Plot Titles 139 | if(title){ 140 | b <- b + ggtitle(title_boxplot) 141 | h <- h + ggtitle(title_histogram) 142 | d <- d + ggtitle(title_density) 143 | s <- s + ggtitle(title_scatter) 144 | l <- l + ggtitle(title_line) 145 | } 146 | 147 | # Add theme and other 148 | b <- b + theme + other 149 | h <- h + theme + other 150 | d <- d + theme + other 151 | s <- s + theme + other 152 | l <- l + theme + other 153 | 154 | if (plot_type == "boxplot"){ 155 | print(b) 156 | } else if (plot_type == "histogram"){ 157 | print(h) 158 | } else if (plot_type == "density"){ 159 | print(d) 160 | } else if (plot_type == "scatter"){ 161 | print(s) 162 | } else if (plot_type == "line"){ 163 | print(l) 164 | } else if (plot_type == "all"){ 165 | print(b) 166 | print(h) 167 | print(d) 168 | print(s) 169 | print(l) 170 | } 171 | 172 | # Print Summary 173 | df <- if (is.na(group)){df} else (df %>% group_by_(as.name(group))) 174 | summary <- df %>% 175 | summarize_(min = ~min(duration, na.rm = T), 176 | Qt1 = ~quantile(duration, probs = 0.25, na.rm = T), 177 | median = ~median(duration, na.rm = T), 178 | mean = ~mean(duration, na.rm = T), 179 | Qt3 = ~quantile(duration, probs = 0.75, na.rm = T), 180 | max = ~max(duration, na.rm = T), 181 | sd = ~sd(duration, na.rm = T)) 182 | if(is.na(group)){ 183 | summary <- round(summary[,(ncol(summary)-6):ncol(summary)], 2) 184 | } else { 185 | summary <- cbind(summary[,1:(ncol(summary)-7)],round(summary[,(ncol(summary)-6):ncol(summary)], 2)) 186 | } 187 | return(summary) 188 | } 189 | 190 | 191 | --------------------------------------------------------------------------------