The plot_time_series is a simple utility for plotting a time series graph using R. This is handy for e.g. plotting KPI values over time or any other time series data.
To use this script, you need to install R and then get the getopt
package.
To install the getopt
package, fire up R (type R in your terminal) and type in:
install.packages('getopt', repos='http://cran.us.r-project.org')
If your R binary is somewhere other than /usr/bin
you'll also need to edit the first line of plot_time_series
to
point it at the correct location. Do which R
to find where R lives on your system.
You can use plot_time_series anywhere you can use R, but the tests are *nix flavored.
NAME
plot_time_series
SYNOPSIS
Usage: ../plot_time_series [-[-verbose|v]] [-[-help|h]] [-[-show_gridlines|g]] [-[-plot_out_of_range|R]] [-[-trim_to_week|T]] [-[-csv_filename|c] <character>] [-[-special_points_filename|S] [<character>]] [-[-special_points_color|C] [<character>]] [-[-output_filename|f] <character>] [-[-input_date_format|d] <character>] [-[-title|t] <character>] [-[-y_title|y] <character>] [-[-y_unit|s] <character>] [-[-y_prefix|P] <character>] [-[-y_range|Y] [<character>]] [-[-x_range|X] [<character>]] [-[-x_spacing|x] [<character>]] [-[-y_line|L] [<character>]] [-[-label_cex|B] [<double>]] [-[-smoothness|m] [<double>]] [-[-width|w] [<integer>]] [-[-height|u] [<integer>]] [-[-point_color|p] [<character>]] [-[-sunday_point_color|z] [<character>]] [-[-axis_color|a] [<character>]]
DESCRIPTION
The plot_time_series is a simple utility for plotting a time series graph using R.
This is useful for e.g. plotting KPI values over time.
The graph is drawn as a scatterplot with a LOESS fit line of variable smoothness.
OPTIONS
The options are as follows:
--verbose Get a little chatty?
--width The width of the graph in pixels
--height The height of the graph in pixels
--csv_filename A CSV containing input data with columns date,value (example below)
--output_filename The file that the graph is written to
--special_points_filename A file containing special points e.g. milestones or targets
--special_points_color The color of the special points
--title The title shown above the graph
--y_title The title shown on the y axis of the graph
--y_unit A string appended to the y axis values e.g. MM
--y_prefix A string prepended to the y axis values e.g. $
--y_range Manually set Y axis limits e.g. 10:1000
--x_range Manually set X axis limits e.g. 04/27/2012:05/20/2013
--x_spacing How the x-axis is spaced e.g. day, 3 days, week, month, 2 weeks, 2 months
--y_line Add a horizontal labeled line at a Y value e.g. "10,000:Target for 2012"
--point_color The color to draw points in
--sunday_point_color The color to draw sunday points in
--input_date_format The format of the date in the datafile, default is "%m/%d/%Y"
--axis_color The color to use for the axis
--smoothness How much to smooth the LOESS fit line. Float between 0 and 1
--plot_out_of_range Plot out of range points and use them in the interpolation?
--trim_to_week Trim the X axis to whole weeks? (x grid goes Sunday to Sunday)
--show_gridlines Show gridlines?
--label_cex Graph label scaling relative to default, used for y_line and special_points
EXAMPLES
$ plot_time_series --width=800 --height=400 --x_spacing=month --csv_filename=test_data/unbranded_organic_registrations.csv
--output_filename=output/unbranded_organic_registrations.png --title="Unbranded Organic Registrations: %s to %s"
--y_title="Number Registrations"
EXAMPLE INPUT FILE
date,value
03/06/2012,6347.04
03/07/2012,9990.23
03/08/2012,6773.41
COLOR
Available colors documented at: http://www.stat.columbia.edu/~tzheng/files/Rcolor.pdf
DOCUMENTATION
Read the full documentation at: https://github.com/doofdoofsf/plotTimeSeries/blob/master/README.md
There is a test directory with some lovely testy stuff in it:
test/test_data - a directory with some test csv files in it
test/output - a directory that the test script dumps images into
test/run_test - a bash script that runs the tests
test/tests.txt - the test definitions
Go and run the tests and make sure everything passes:
$ cd test
$ ./run_test
tests.txt
* running test "registrations thumb" ... passed
* running test "registrations graph" ... passed
* running test "revenue thumb" ... passed
* running test "revenue graph" ... passed
* running test "revenue graph with target line" ... passed
* running test "revenue graph with targets" ... passed
* running test "registrations thumb with x/y bounds" ... passed
** All tests passed
Example graphs are shown below. These are produced from the data in the test
directory
../plot_time_series --width=500 --height=400 --x_spacing=month
--csv_filename=test_data/acme_registrations.csv --point_color=gray80 --sunday_point_color=gray80
--smoothness=0.8
../plot_time_series --width=1200 --height=700 --x_spacing=week
--csv_filename=test_data/acme_registrations.csv --show_gridlines --smoothness=0.3 --title="Acme
Registrations: %s to %s" --y_title="Number Registrations"
../plot_time_series --width=500 --height=400 --x_spacing="2 months"
--csv_filename=test_data/acme_revenue.csv --point_color=gray80 --sunday_point_color=gray80
--smoothness=0.8 --y_line="35000:Target" --y_prefix="$" --label_cex=1.1
../plot_time_series --width=1200 --height=700 --x_spacing=week
--csv_filename=test_data/acme_revenue.csv --show_gridlines --title="Acme Revenue: %s to %s"
--y_prefix="$"
../plot_time_series --width=1200 --height=700 --x_spacing=week
--csv_filename=test_data/acme_revenue.csv --title="Acme Revenue: %s to %s" --y_line="25000:Target
for 2012:gold3!36000:Target for 2013:gold2!42000:Target for 2014:gold1" --y_prefix="$"
../plot_time_series --width=1200 --height=700 --x_spacing=week
--csv_filename=test_data/acme_revenue.csv --show_gridlines --title="Acme Revenue: %s to %s"
--special_points_filename=test_data/acme_revenue_targets.csv --special_points_color=cornflowerblue
--point_color=gray80 --sunday_point_color=gray80 --y_prefix="$"
../plot_time_series --width=500 --height=400 --x_spacing=month
--csv_filename=test_data/acme_registrations.csv --title="April to September" --point_color=gray80
--sunday_point_color=cornflowerblue --smoothness=0.2 --x_range=04/01/2012:09/01/2012
--y_range=50:250