Getting started with Limpet
Limpet is an Open Source application supporting the analysis of bulk measured data, including time series.
It provides the analyst with a set of operations and calculations that are sensitive to the selected datasets: it will allow two length datasets to be added, but not a length and a temperature dataset. Similarly, it knows that a length dataset (in metres) divided by an elapsed time dataset (in seconds) will provide a results data set in metres/second.
Note: this document was first produced in Nov 2015. At this point, Limpet is still an early beta. The functionality implemented so far works, and produces accurate calculated data. But, it is still lacks essential functionality and user documentation.
You can download Limpet from the releases page https://github.com/debrief/limpet/releases.
If you’re running MS Windows, and are unsure whether you have Java installed on your machine, please download an *Easy* version of the software. They’re a bit larger, but they include a Java runtime:
Or, you can request a version on CD from the project maintainer: email@example.com
Once you’ve obtained a copy of Limpet, just unzip it into a folder on your hard drive.
Start Limpet by double-clicking on the limpet.exe application executable. Limpet will open, and show a welcome page. The welcome page will expand to include more Getting Started guidance, including an overview of the capabilities provided and the general user flow.
For the purposes of this tutorial, you can skip the Welcome page by clicking on the “X” highlighted below.
You should now see the Limpet workbench view (shown below).
You need to create a Project to store your data. Limpet can help you with this, it will also include some sample data to play with. To do this, click on the Create Sample project button at the left of the toolbar:
You will now see the sample data in the Navigator view:
You can expand the sample data to see its contents:
Files ending in .lap are Limpet Analysis Projects - files that contain datasets, calculations, and the connections between datasets that allow for live updates.
The americas.lap is currently empty. Double-click on it to open it. A blank pane will open in the centre of limpet.
We’ll now load some sample data. We’ve found some sample data from the 2013 America’s Cup that we can use.
Right-click on nzl.csv, and select Open With > Text editor. Let’s have a look at the contents.
You’ll see that this is fairly standard comma separated variable content. We’ve made just one change. We’d slightly modified the column headers to include the units (where relevant). This is a good practice in general, but it’s really useful for Limpet, to help it understand how to manipulate the data.
Now that we’ve seen the data, please close the nzl.csv file, and drag the two .csv files from the americas_cup folder into the blank americas.lap editor window. Limpet will parse the files, and organise the data into two folders:
Notice that the time column isn’t shown - Limpet has treated the 5 columns as 3 time series datasets, with the last two columns combined into a time series of locations (a track).
Let’s learn about the data. If you select one of the datasets, you’ll see some Descriptive Statistics shown in the Analysis View pane.
This view gives some metadata describing the data, then some overall statistics - including mean and standard deviation.
Further to the descriptive statistics we can perform some Exploratory Analysis of the data. You can use the XY Plot and Data Frequency plot to explore the data in more detail. The Wind Speed data is quite interesting:
The XY Plot shows us the general range of wind speeds experienced. But, the Data Frequency plot clearly shows that for the majority of time the speed was in the 16-19 m/s range.
Let’s start off with generating some data from the location datasets. Use the control key to select the two Location datasets (nzl-Location and usa-Location). Then right-click on one of them. You’ll be presented with a menu of operations.
From the Spatial menu, select Generate calculated course. Limpet will invite you to provide a prefix to be used in the generated datasets. Then repeat the steps in order to Generate calculated speed. You will now see the new datasets.
Let’s pause for a minute to look at those icons. For all of the datasets you can see a clock marker, this indicates that the dataset is a time series. For usa-location there is also a right-arrow. This indicates that the dataset is used in the generation of another: it has dependents. For the four new datasets there is a left arrow. This indicates that the dataset has been generated from one or more others: it has precedents. If you expand the usa-location dataset you can see an audit trail of its dependents:
We can use the properties editor to perform a little tidying now. Select one dataset at a time, and edit the name in the Properties view, to give the following names:
We can also do some tidying. Drag the two NZL datasets up into the nzl.csv folder, and the two USA datasets into the USA folder:
Ok, let’s now consider some arithmetic operations, while we consider the upwind performance of the New Zealand yacht.
Let’s subtract the yacht’s course from the windspeed, to determine the course relative to wind. Control-click on nzl-course and nzl-Wind Direction (it’s in the nzl.csv group). Next, right-click on one of them, and select Arithmetic / Subtract nzl-course from nzl-Wind Direction. We now have a dataset of nzl-course from nzl-Wind Direction. Have a look at this dataset in the XY Plot view. It ranges from -100 to 250 degrees.
Let’s make it absolute. So, right-click on this dataset and select Arithmetic / Math - Abs. We now have an absolute series.
Rename this new dataset as nzl-Abs course to wind.
Lastly, let’s explore the rarely used (and possibly nonsensical) knots per degree to wind performance metric. We need to convert the nzl-speed from m/sec to knots. So, right-click on it, and select Conversions / Convert to kn. This will give us a converted dataset, rename it to nzl-speed (knots).
Lastly, ctrl-click to select nzl-Abs course to wind and nzl-speed (knots), then right-click and select Arithmetic / Divide nzl-speed (knots) by nzl-Abs course to wind (in its strange output units).
What’s that? You also want to find out at what frequency USA would receive the NZL acoustic noise source, adjusted? Of course you do.
Start by defining the NZL radiated frequency. Right-click on the nzl.csv file, and select Create / Create single frequency value. Give it a name, Radiated frequency and a value, 212.3.
We also need to provide the speed of sound for the medium that the noise is travelling through. This isn’t specific to either vessel, so we’ll define it at the top level. Ensure nothing is selected (use ctrl-click to deselect if necessary) Then right-click in the space below the two track folders, and select Create / Create single speed (m/s) value. Then provide a name: Sound Speed and a value: 1030.
Now we’re ready. Select the two tracks and the sound speed value, right-click, and select Spatial / Doppler between tracks (from nzl.csv). Limpet only offered to calculate the doppler from nzl because that’s the only track that has a frequency. Clearly if we provided frequencies for both, we’d be offered both directions.
This will produce a new doppler shift dataset. Drag it into the usa.csv folder, since it’s the frequency that would be received at that platform.
Let’s have a play with the input data. We’re going to see how changing the sound speed affects the calculated doppler. Start by selecting the doppler dataset, so it is shown in the XY Plot View. Next, click on the two yellow arrows in the XY Plot View toolbar to deselect the Link with selection mode. Now, the XY Plot View is locked onto the doppler dataset.
Now select the sound speed dataset. It will be shown in the Properties view:
If you change the Value from 1030 to 730, you will see the calculated doppler values change. They will retain the same shape, but the y-axis values will compress.
But, we can do better than that. Let’s tell Limpet about the range of possible values a sound speed can take. Edit the Metadata / Range property to specify the min/max values by giving it a value of 600:1200
With this knowledge, Limpet can let you continuously change the sound speed. The Range Slider view should now be enabled. Just drag the slider, and the calculated doppler will change dynamically.