diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..6002bc433e65ceb66db9ba86a24338b9a752db9f
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,77 @@
+tsplot
+------
+
+The `tsplot.py` script is a wrapper around matplotlib for displaying a collection of
+time series plots.
+
+## Input data
+
+`tsplot` reads timeseries in JSON format, according to the following conventions.
+
+```
+{
+    "units": <units>
+    "name":  <name>
+    <other key-value metadata>
+    "data": {
+        "time": [ <time values> ]
+        <trace name>: [ <trace values> ]
+    }
+}
+```
+
+The `data` object must contain numeric arrays, with at least one with the key `time`;
+other members of `data` correspond to traces sampled at the corresponding time values.
+
+The other members of the top level object are regarded as metadata, with some keys
+treated specially:
+ * `units` are used to distinguish different axes for plotting, and the labels for those
+   axes. It's value is either a string, where the specified unit is taken as applying to
+   all included traces, or an object representing a mapping of trace names to their
+   corresponding unit string.
+ * `name` is taken as the title of the corresponding plot, if it is unambiguous.
+
+## Operation
+
+The basic usage is simply:
+```
+tsplot data.json ...
+```
+which will produce an interactive plot of the timeseries provided by the provided
+files, with one trace per subplot.
+
+### Grouping
+
+Traces can be gathered on to the same subplot by grouping by metadata with the
+`-g` or `--group` option. To collect all traces with the same value of the key
+'id' and the same units:
+```
+tsplot -g units,id data.json ...
+```
+A subplot can comprise data with to two differint units, and will be plotted
+with two differing vertical axes.
+
+### Restricting data
+
+The `-t` or `--trange` option exlcudes any points that have a time range outside
+that specified. Ranges are given by two numbers separated by a comma, but one or
+the other can be omitted to indicate that there is no bound on that side. For
+example:
+```
+tsplot -t ,100 data.json ...
+```
+will display all points with a time value less than or equal to 100.
+
+Extreme values for data can be automatically excluded and marked on the plot
+with the `-x` or `--exclude` option, taking a parameter _N_. All values in a
+timeseries that lie outside the interval [ _m_ - _Nr_, _m_ + _Nr_ ] are omitted,
+where _m_ is the median of the finite values in the timeseries, and _r_ is
+the 90% interquantile gap, that is, the difference between the 5% and 95% quantile
+of the timeseries data.
+
+### Output to file
+
+Use the `-o` or `--output` option to save the plot as an image, instead of
+displaying it interactively.
+
+
diff --git a/scripts/tsplot.py b/scripts/tsplot
similarity index 99%
rename from scripts/tsplot.py
rename to scripts/tsplot
index 8324f3441ea7446ec04e10a0353b0d8e12832846..81a5da78c06a24d71f727431ef237a18f2a13b0b 100755
--- a/scripts/tsplot.py
+++ b/scripts/tsplot
@@ -17,7 +17,6 @@ if LooseVersion(M.__version__)<LooseVersion("1.5.0"):
     logging.critical("require matplotlib version ≥ 1.5.0")
     sys.exit(1)
 
-
 # Read timeseries data from multiple files, plot each in one planel, with common
 # time axis, and optionally sharing a vertical axis as governed by the configuration.
 
@@ -39,7 +38,7 @@ def parse_clargs():
     P.add_argument('-g', '--group', metavar='KEY,...', dest='groupby',
                    type=lambda s: s.split(','), 
                    help='plot series with same KEYs on the same axes')
-    P.add_argument('-o', '--out', metavar='FILE', dest='outfile',
+    P.add_argument('-o', '--output', metavar='FILE', dest='outfile',
                    help='save plot to file FILE')
     P.add_argument('-x', '--exclude', metavar='NUM', dest='exclude',
                    type=float,