Tufte Sparklines Photoshop Script
A sparkline is a small line graph designed to be used in-line within text to illustrate a time series; the concept was developed by data presentation guru Edward Tufte. Here’s an example:
University of California 403(b) pension fund cumulative return Jan 1990-April 2004 (original data)
| Equities |  |
267% |
| Bonds |  |
154% |
The idea is to show, using minimal space, how a value varies over time. One advantage of sparklines’ compactness is that several can be used together to allow at-a-glance comparison between a set of time series. At Tufte’s web site there is a longer description of sparklines, with further examples, from a sample chapter of Tufte’s book, Beautiful Evidence. Sparklines are tangentially related to photography - they are used alongside images as a graphical design element in qualitative and quantitative analysis.
Sparklines can be hard to produce. Most graphing packages are designed to produce large graphs or charts, and it can be very hard to generate the wide-but-thin lines for incorporation in documents. This was the motivation for writing a Photoshop script that would automate the production of sparklines. It works by reading a data series from a text file and plotting a sparkline image as a Photoshop path, and then stroking it with the pencil tool. This produces a bitmap image which can then be cut-and-pasted into the target document. The user retains control of the color and line style of the sparkline by setting the Photoshop foreground color and pencil tool settings before running the script.
Mac support and PS CS2 testing
Some Mac users had reported problems with the Sparkline script not being able to open text data files. Thanks to the help of two kindly Mac contributors, I found and fixed the problem. In addition, the script has been tested on Photoshop CS2. All the changes are incorporated in Version 2 of the script below.
Installing the sparkline script
The code of the sparkline script for Adobe Photoshop CS/CS2/CS3 is included below. While it will run on Mac or PC Photoshop, it does not work on any earlier versions. You can also right click (Mac: Option click) here to download the script. Select “Save as…” from the menu that pops up, and save it somewhere where you can find it on your computer.
The script works on textual data files, where the first line is the name of the quantity being charted, and the remainder of the lines are the data values. To start you off, here’s a sample data file for wind speed. Using Microsoft Excel, it’s easy to create data files in this format: put the legend in cell A1, then the data values in cells A2, A3 and so on, and then do File->Save As… and select “Text file” for the output format.
To install the script, first locate Adobe Photoshop’s main directory on your computer. On my (Windows) computer, it’s in C:\Program Files\Adobe\Photoshop CS
On the PC, save the script as Sparklinev2.js in the directory <Photoshop dir>\Presets\Scripts
On the Mac, save the script as Sparklinev2.js in the directory <Photoshop dir>/Presets/Scripts
Start Photoshop (or re-start it, if it was already running). You should now see the Sparkline script on the File->Scripts menu:
Using the script
First of all, select the foreground color and Pencil tool settings that you want to use for the Sparkline. To select a foreground color, double click on the foreground color swatch in the palette menu. To select the pencil tool, right-click (Mac: option-click) on the palette menu as shown:
Then, set the pencil defaults to whatever you’d prefer using the tool menu just below the Photoshop menu bar:
Click File->Scripts->Sparkline (as shown in the screen shot above) to start the script. You will be promoted to locate the file containing the sparkline data:
Click “Open”; the script will open the file and then prompt you for the height of the sparkline, in pixels. The default height is 50 pixels, which is 50 points (0.7″) high on a typical 72dpi computer screen, and 12 points high when printed on paper at 300dpi (you can change the default height by editing the script).
The script will then ask if you want to automatically scale the sparkline to the document height. If you select Yes, then the script uses the minimum and maximum values present in the data file to scale the Y axis such that the minimum value is plotted at the bottom of the document, and the maximum value is plotted at the top, like this (a border has been added to make it easier to see the effect):
If you select No, then the script will prompt you for the Y intercept (the data value that will be plotted at the bottom of the document) and the maximum Y value (which will be plotted at the top of the document). For example, using a Y intercept of 0 and a max Y value of 50, the same data would be plotted as follows (again, border added for clarity):
Finally, the script asks for the X axis pixel spacing between points. The default setting of 1 plots each point of the sparkline immediately adjacent (one pixel away) from the previous point. To make the sparkline shorter, use a value less than 1. To make it longer, use a value greater than one. For example:
X axis pixel spacing of 0.3: 
X axis pixel spacing of 0.5: 
Advanced topics: Use of time travel
Because the script creates a regular Photoshop document complete with history, you can use the Photoshop history palette to “go back in time” and change the way that the path is stroked. For example, to use a Brush stroke rather than a Pencil stroke, you’d go back in the document history to the point where the path has been saved, but before it has been stroked. Then stroke it with the Brush, rather than the Pencil.
First of all, open both the History and Paths palettes. Then, use the History palette to go back to the document state before the stroke occurred:
Then, right click (Mac: option-click) on the Sparkline path in the channels palette. Select “Stroke path…” from the pop-up menu.
The following dialog will appear, and you can elect to stroke the path using the Brush, or indeed any of the other Photoshop tools:
Script source code
// Sparklines for Photoshop
// (c) Copyright 2004, 2005 Mathew Lodge / www.lodgephoto.com
// Last updated: 4 May 2005 (v2)
// For debugging only
//$.level = 1; debugger;
// Plug in your own values here
var defaultXSpacing = 1.0; // Default x axis pixel spacing between points on the sparkline
var defaultHeight = 50; // Default height of image, in pixels -- 1 inch = 72 pixels
// Width will be dependent on the size of the data set
// Save current units settings
var startRulerUnits = app.preferences.rulerUnits;
var startDisplayDialogs = app.displayDialogs;
var startTypeUnits = app.preferences.typeUnits;
// Switch to pixel units and turn off dialogs
app.preferences.rulerUnits = Units.PIXELS;
app.preferences.typeUnits = TypeUnits.PIXELS;
app.displayDialogs = DialogModes.ERROR;
try {
if (runningOnMac())
var dataFile = File.openDialog("Select data file");
else // Windows
var dataFile = File.openDialog("Select data file", "Text files:*.txt;*.TXT,All files:*");
// Read the data file
var data_set = readDataFile(File(dataFile.fsName));
var legend = data_set[0]; // Assumption: first line of file contains legend
// Find the min and max of the data set
var lowest, highest;
lowest = highest = Number(data_set[1]);
for (var i = 2; i<data_set.length; i++) {
datum = Number(data_set[i]);
if (datum < lowest)
lowest = datum;
if (datum > highest)
highest = datum;
}
var height = Number(prompt(legend+”: Pixel height of sparkline?”, defaultHeight));
var scaleLine = confirm(legend+”: Automatically fit (scale) sparkline to document height?”);
var yIntercept = lowest;
if (!scaleLine) {
yIntercept = Number(prompt(legend+”: Y intercept (min value) of sparkline?”, lowest));
highest = Number(prompt(legend+”: Max y value of sparkline?”, highest));
}
var xSpacing = Number(prompt(legend+”: X axis pixel spacing between points?”, defaultXSpacing));
var scale = height/(highest-yIntercept); // Y axis scale
var width = (data_set.length * xSpacing);
// Create the sparkline Photoshop document and bring it to the front
sparklineDoc = app.documents.add(width, height, 72,
“Sparkline for “+legend,
NewDocumentMode.RGB,
DocumentFill.WHITE,
1.0);
app.activeDocument = sparklineDoc;
// Create the point array for the sparkline
var pointArray = new Array();
var currX = 0;
var currY;
for (var i = 1; i < data_set.length; i++) {
currY = height - ((Number(data_set[i])-yIntercept) * scale);
addPointToArray(pointArray, currX, currY);
currX = currX + xSpacing;
}
var sparklineSubPath = new SubPathInfo();
sparklineSubPath.operation = ShapeOperation.SHAPEXOR;
sparklineSubPath.closed = false;
sparklineSubPath.entireSubPath = pointArray;
var sparklinePath = sparklineDoc.pathItems.add(”Sparkline”, Array(sparklineSubPath));
// Stroke the path so it becomes visible, then deselect the path
sparklinePath.strokePath(ToolType.PENCIL);
sparklinePath.deselect();
}
catch(e)
{
alert(e);
}
app.preferences.rulerUnits = startRulerUnits;
app.preferences.typeUnits = startTypeUnits;
app.displayDialogs = startDisplayDialogs;
function readDataFile(dataFile)
// Reads a text file (typically output from Excel)
// Assumes that there is one number per line
// Blank lines are ignored
{
var line; // Line read from file
var data_series = new Array; // The data series to be returned
var result = dataFile.open(”r”, “TEXT”, “”);
if (!result)
throw dataFile.error;
var index = 0;
var line;
while (!dataFile.eof) {
line = dataFile.readln();
if (line.search(/\S/) != -1) // if line is not blank
data_series[index++] = line;
}
return data_series;
}
function runningOnMac() {
return (File.fs.search(/mac/i) == 0);
}
function addPointToArray(parray, x, y) {
var idx = parray.length;
parray[idx] = new PathPointInfo;
parray[idx].kind = PointKind.SMOOTHPOINT;
parray[idx].anchor = Array(x, y);
parray[idx].leftDirection = parray[idx].anchor;
parray[idx].rightDirection = parray[idx].anchor;
}
Tags: photoshop, programming, scripting, sparklines