The Programmatic Spreadsheet

The Programmatic Spreadsheet (TPSS for short) is a Java library for the manipulation of two-dimensional tabular data. It allows users to create objects called Spreadsheets, put data into cells of these spreadsheets (or fill it from the contents of a file), and use functions to transform these spreadsheets into others. TPSS also defines Charts, which are abstract graphical renditions of the content of a spreadsheet. Currently, charts can be turned into images using extensions for either Gnuplot or GRAL.

The most important feature of TPSS is explainability. Functions that transform a spreadsheet keep track of the relationship between each output cell and the input cells that have been involved in the generation of the value it contains. As a result, a user can "query" a cell (or even part of a value in a cell) and automatically obtain the complete lineage information that links it back to the corresponding parts of the input. Charts can also be queried in the same way; for instance, it is possible to designate a chart element (a point, an axis, an element of the legend) and retrace the elements from the input spreadsheet from which it originates. This functionality is available end-to-end without any extra code required from the user.

The Programmatic Spreadsheet's API is thoroughly documented, and the library comes with a number of code examples illustrating its features.

Quick Examples

Using TPSS

To start using TPSS, you need to download:

• The latest version of Petit Poucet, both petitpoucet-core.jar and petitpoucet-functions.jar
• The library tpss-core.jar to create and manipulate spreadsheets
• To create charts, tpss-charts.jar, accompanied by the extension corresponding to the plotting library you wish to use (e.g. tpss-charts-gnuplot.jar or tpss-charts-gral.jar)

Building TPSS

The Programmatic Spreadsheet comes with build scripts that can download dependencies, compile and test its source code, generate the API documentation and produce the JAR files of its various components. Its code can be compiled in any platform using Ant, and a Java Development Kit (JDK) version 8 or higher.

The root of its source code is the Source folder; the repository is divided into a number sub-projects corresponding to the various parts of the library. Each sub-project comes with its own AntRun build script for Apache Ant (please see the AntRun Readme file for instructions on compiling). When compiled, each sub-project generates a distinct JAR file.

The Source folder contains a "super-project" Ant build script, whose job is to call each sub-project build script in sequence for a given task. Since some sub-projects depend on the JAR file generated by compiling another sub-folder, the script takes care of compiling them in the proper order and to copy the required JAR files to other folders along the way. Using the super-project Ant script is the recommended way of building and testing TPSS.

To build from the sources, first download the code or clone the repository using Git:

git@github.com:liflab/programmatic-spreadsheet.git

In the Source folder of the repository, simply type:

ant

This will take care of downloading dependencies, compiling each sub-project, running its unit tests, and generating the JAR file. These files are located in the Source folder.

Other tasks can be listed by typing:

ant -p

Projects that use The Programmatic Spreadsheet

• LabPal, a framework for running computer experiments

About the author

AntRun was written by Sylvain Hallé, Full Professor at Université du Québec à Chicoutimi, Canada.