Topsoil

Ocotcat Topsoil Repository

Introduction

Topsoil is a desktop application and Java library that creates interactive data visualizations for geochronological data. ”Topsoil” is an anagram of “Isoplot”, the name of an enormously successful Microsoft Excel Add-In with similar capabilities developed by Kenneth Ludwig, which now works only in older versions of Excel.

Using Topsoil, a user is able to manually enter data, or import from delimited data formats, such as .csv, .tsv, and .txt. This data is stored in the form of tables, which can be organized and edited by the user. The table is used to create a plot which is freely explorable, and with several built-in plot features that can be toggled on or off. Which plot features are available is dependent on the isotope system of the given table; that is, whether the data is from a Uranium-Lead or Uranium-Thorium analysis. More isotope systems will become available to the user in the future.

Plots can be saved in .svg format, so the image can be scaled up or down without any sacrifice in resolution. Tables can be exported to .csv, .tsv, or .txt. In addition, the user may choose to save the working state of their project in a .topsoil file, which will store a user’s open tables and plots.

If you’re interested in learning more about Topsoil, contact Dr. Jim Bowring at [email protected].

This material is based upon work supported by the National Science Foundation under Grant Numbers 0930223 and 1443037. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Information

Citation

To cite Topsoil, please provide a footnote or acknowledgement as follows:

J.F. Bowring, PI CIRDLES.org Open Source Development Team. Topsoil - A community driven replacement for ISOPLOT. Apache License, Version 2.0. https://github.com/CIRDLES/topsoil.

License

System Requirements

Topsoil will run on Windows (x86 and x64), Linux (x86 and x64), and macOS (x64 only). The system must have the most recent version of Java installed.

Procedures

How to Use Topsoil

Before doing anything, you will need to install the most recent version of Java.

  1. Download the most recent version of Java here.
  2. Run the installer and follow the on-screen instructions. Once the Java installation is complete, proceed.
Using a JAR file:
  1. Download the Topsoil JAR file from the GitHub repository’s releases page.
  2. Open Topsoil by double-clicking/running the JAR file.
Compiling a JAR from the source code:
  1. Download a copy of the source code from GitHub
  2. In the main directory “Topsoil”, open up a command prompt or terminal and run the command ./gradlew build. This will download all of the necessary dependencies as well as collect all of the resource files.
  3. Run the command ./gradlew jarWithDependencies. This will generate a jar file in the directory Topsoil/app/libs called topsoil-v[version number].jar

If you’re using an integrated development environment (IDE), the project import process will depend on which one you have. Topsoil uses Gradle as a build tool. The main class of Topsoil is located in Topsoil/app/src/main/java/org/cirdles/topsoil/app/ and is called MainWindow.java.

A Simple Tutorial

The following is a very basic walkthrough of some of Topsoil’s features. For more detailed information on importing data into Topsoil, see How to Import Data.

  1. Open Topsoil. An about page will pop up, simply click anywhere off of the page to dismiss it.

  2. From the menu bar, select Data Table > Open Example Data Table > Uranium-Lead. This will populate Topsoil with some sample data from a Uranium-Lead analysis.

  3. Underneath the table is a section labeled “Plot Manager”, containing several options for manipulating a plot, which we have yet to generate! Click the button “Generate Plot”.

  4. A separate window should have appeared, with the plot inside of it. From “Plot Manager”, click the check box “Unct. Ellipses”. There should now be uncertainty ellipses surrounding the data points on the plot. You can change the color of these ellipses at any time using the color picker next to the check box.

  5. Now turn on the check box that reads “Wetherill Concordia Line”.

  6. Click-and-drag and zoom inside of the plot until you get to a position you like. If you get too far away from the original view, click the “Re-center” button above the plot to re-center the view to the data.

  7. Click the button “Save as SVG”, and save the file as something like “testPlot.svg”.

  8. Back in the main window, from the menu bar, select Project > Save Project As. This option lets you save your current working state as a .topsoil file, so when you open this file again, your tables and plots will be automatically loaded.

  9. Save the project as something like “test.topsoil”.

How to Import Data

When importing your data into Topsoil, you have a few options. The most important thing to remember is the way that Topsoil organizes its data. The data must be in five columns, with each column representing X axis values, Y axis values, X uncertainty values, Y uncertainty values, and rho (correlation coefficient) values, in that order. For example, for a Uranium-Lead analysis, data may be arranged like this:

Whenever you import data, a helper will appear where you will be able to pick which of your data columns correspond to the layout above.

In each tab, there is a set of labels denoting the proper organization of data. Beneath those labels are the column names, which Topsoil will try to determine based on what you provide it. If Topsoil detects one or more rows that do not consist of numerical values, it will use those as the column names. Up to two header rows will be read; the rest will be ignored.

Importing from a File – (.csv, .tsv, .txt):
  1. Navigate to Table » Import Data Table. Select “From File”.

  2. A file chooser will appear that will allow you to select the proper file from your computer.

  3. (If the delimiter request window doesn’t appear, skip to 4.) If you are importing a .txt file, and Topsoil can’t automatically determine how your data values are separated, you’ll be presented with a dialog box. You can select from common data separators from the drop-down list, or, by selecting “Other”, you can specify your own. Once you’ve specified a separator to use, click “OK”.

  4. A helper window will appear containing a preview of your data. The column names and first five data rows are shown as they would be imported into Topsoil. Above that is a row of drop-down lists with the names of each of the five plotting variables that Topsoil uses. From this screen, you’re able to use the drop-down lists to select which of your data columns correspond to the which variables. By default, the first five will be selected. Important: Any columns that aren’t selected will NOT be imported into Topsoil, and that any variables that don’t have columns assigned to them will be filled with 0.0s. Support for extra columns will be added in the future.

  5. In the same window, there is a drop-down list towards the bottom for selecting the format of your uncertainty values. The values will be in the table and editable as the format you specify, but Topsoil will convert them into 1-sigma absolute format so that you can apply different formats to a plot. Select one and click “Finish”.

  6. You’re done! Topsoil will populate the table with the provided values. Please note that the default isotope system is Generic, which will not support any special plotting features provided for each type of isotope system. The isotope system can be changed freely from a drop-down list in the Plot Manger section, beneath the table.

Importing from the Clipboard:
  1. Navigate to Table » Import Data Table. Select “From Clipboard”.

  2. (If the delimiter request window doesn’t appear, skip to 3.)If you are importing a .txt file, and Topsoil can’t automatically determine how your data values are separated, you’ll be presented with a dialog box. You can select from common data separators from the drop-down list, or, by selecting “Other”, you can specify your own. Once you’ve specified a separator to use, click “OK”.

  3. A helper window will appear containing a preview of your data. The column names and first five data rows are shown as they would be imported into Topsoil. Above that is a row of drop-down lists with the names of each of the five plotting variables that Topsoil uses. From this screen, you’re able to use the drop-down lists to select which of your data columns correspond to the which variables. By default, the first five will be selected. Important: Any columns that aren’t selected will NOT be imported into Topsoil, and that any variables that don’t have columns assigned to them will be filled with 0.0s. Support for extra columns will be added in the future.

  4. In the same window, there is a drop-down list towards the bottom for selecting the format of your uncertainty values. The values will be in the table and editable as the format you specify, but Topsoil will convert them into 1-sigma absolute format so that you can apply different formats to a plot. Select one and click “Finish”.

  5. You’re done! Topsoil will populate the table with the provided values. Please note that the default isotope system is Generic, which will not support any special plotting features provided for each type of isotope system. The isotope system can be changed freely from a drop-down list in the Plot Manger section, beneath the table.

Known Issues

Here are some known issues that are present in the current release of Topsoil:

Plot Loads to White Screen
  • This is a problem that we have experienced extensively on Windows platforms, and are researching a fix for. In the short term, try generating the plot a few more times or toggling some of the plot settings. If this doesn’t work, then you’ll need to restart Topsoil.

  • If you are using a non-Windows machine and experience this problem, please contact us.

Irregular Panning or Zooming in a Plot
  • If you are dragging a plot it refuses to move, or if you are zooming in/out and the plot changes the center, it is most likely because you are reaching the bounds of the plot. The plot can’t go below (0, 0), so when zooming out, the plot will account for the limit being reached on one side, and the center may move. However, if you are dragging the plot and it won’t move in a specific direction, it is because of a known bug in the way that the bounds of the plot are set. Although the plot will stop moving when either axis reaches zero, Topsoil thinks that the position of the plot is somewhere below zero. If you drag away from zero enough, eventually the plot will move again. Zooming out temporarily will make that process go faster.
Freezing in the Evolution Matrix
  • The math required to re-draw the matrix every time it moves can take a while. We’re working on optimizing the math so that the plot runs smoother.

Glossary of Terms

Isotope System - An option based on the type of radiometric analysis produced the data in question. Currently, the only two supported dating schemes are Uranium-Lead (U-Pb) and Uranium-Thorium (U-Th).

Unct. - An abbreviation for "Uncertainty".

Evolution Matrix - A plotting feature for the U-Th isotope system with a set of isochrons and contours.