nutmeg-reader

Reader for the Nutmeg Waveform Format in Java. Parsers for both ASCII and Binary waveforms are provided.

Installation

Clone this repository:

$ git clone https://github.com/electronics-and-drives/nutmeg-reader.git

cd nutmeg-reader into the directory.

Makefile

Simple installation with make:

$ make java     # for java with maven
$ make python   # for python with pip (will automatically install java)
$ make all      # all of the above

Java Specific

If you're only interested in java you can install it just with maven:

$ mvn install

The repository will be installed to the directory

$ make mvn-path

$ mvn -q -Dexec.executable=echo \
         -Dexec.args='${settings.localRepository}' \
         --non-recursive exec:exec 2>/dev/null

You can retrieve the path to the JAR with the makefile

$ make jar-path

or by using the command

{
  mvn help:evaluate -Dexpression=settings.localRepository | grep -v "^\[" ;
  echo "/" ;
  cat pom.xml | grep -oPm1 "(?<=<groupId>)[^<]+" | sed  's/\./\//g' ;
  echo "/" ;
  cat pom.xml | grep -oPm1 "(?<=<artifactId>)[^<]+" ;
  echo "/" ;
  cat pom.xml | grep -oPm1 "(?<=<version>)[^<]+" ;
  echo "/";
  cat pom.xml | grep --color=never -oPm1 "(?<=<artifactId>)[^<]+";
  echo "-"; 
  cat pom.xml | grep -oPm1 "(?<=<version>)[^<]+";
  echo "-";
  cat pom.xml | grep -oPm1 "(?<=<descriptorRef>)[^<]+";
  echo ".jar"
} | tr -d '\n'

Python

The python package depends on the java installation. After installing the java package, you can install the python package with pip:

$ cd ./src/main/python
$ pip install . --use-feature=in-tree-build

Setup

Java

Add the dependency to your project

<dependency>
  <groupId>edlab.eda</groupId>
  <artifactId>reader.nutmeg</artifactId>
  <version>1.0.6</version>
</dependency>

Import the corresponding package to your code

import edlab.eda.reader.nutmeg.*;

MATLAB / Octave

There are two variants how the JAR can be loaded in MATLAB / Octave. The first possibility is to run the command

javaaddpath('<PATH_TO_JAR>');

The second possibility is to add the path to the JAR to the file javaclasspath.txt and place this file in the working directory of MATLAB (this is the directory where MATLAB is started).

Additionally, the corresponding scripts must be added the the search-path of MATLAB

addpath('<PATH_TO_REPOSITORY>/src/main/matlab/');

Additional information can be found in the MATLAB and Octave Manuals

MATLAB
- Java Class Path
- Search Path
Octave
- How to make Java classes available to Octave?
- Manipulating the Load Path

Python

The nutmeg_reader module depends on the java package and looks for it in the default maven install directory given by the command above or make jar-path. If the jar is in some other location, make sure CLASSPATH points to it before importing the python module.

from nutmeg_reader import NutReader, read_nutmeg

API

Java

The JavaDoc is stored on the Github-Pages (branch gh-pages).

MATLAB / Octave

Execute the commands

help readNutascii

and

help readNutbin

to get information how to call the functions in MATLAB / Octave.

Python

After importing the module, help for the classes can be found via the docstrings. For example, to get help for the NutReader class or the read_nutmeg function see:

>>> from nutmeg_reader import NutReader, read_nutmeg

>>> help(NutReader)

>>> help(read_nutmeg)

Example

Java

The below shown example shows how a waveform file can be accessed with NutReader.

// Create a new reader
NutReader reader = NutReader
    .getNutasciiReader("./src/test/java/resources/rc/nutascii.raw");

// Read and parse the nutascii
reader.read().parse();

// Get all plots from the reader
List<NutmegPlot> plots = reader.getPlots();

// Get nutmeg plot from list
NutmegPlot nutmegPlot = plots.get(0);

// Get name of plot
nutmegPlot.getPlotname();

// Get number of points from plot
nutmegPlot.getNoOfPoints();

// Get number of variables from plot
nutmegPlot.getNoOfVariables();

// Get set of all waves from plot
Set<String> waves = nutmegPlot.getWaves();

// Check if wave with name "I" is part of plot
nutmegPlot.containsWave("I");

// Get unit of wave with name "I"
nutmegPlot.getUnit("I");

if (nutmegPlot instanceof NutmegRealPlot) {

  // Cast plot to real plot
  NutmegRealPlot nutmegRealPlot = (NutmegRealPlot) nutmegPlot;

  // Get wave of wave with name "I"
  double[] wave = nutmegRealPlot.getWave("I");
}

MATLAB

file = './src/test/resources/rc/nutascii.raw'

plots = readNutascii(file);

plot(plots(4).waveData(:,4),plots(4).waveData(:,5),'LineWidth',2);

xlabel(plots(4).waveNames{4} + ' (' + plots(4).waveUnits{4} + ')');
ylabel(plots(4).waveNames{5} + ' (' + plots(4).waveUnits{5} + ')');
title(plots(4).name);

Octave

file = './src/test/resources/rc/nutascii.raw'

plots = readNutascii(file);

plot(plots(4).waveData(:,4),plots(4).waveData(:,5),'LineWidth',2);

xlabel([plots(4).waveNames{4} ' (' plots(4).waveUnits{4} ')']);
ylabel([plots(4).waveNames{5} ' (' plots(4).waveUnits{5} ')']);
title(plots(4).name);

Python

See the readme in the python module for further examples.

from nutmeg_reader import NutReader

nut_file    = '../../../test/resources/rc2/nutascii.raw'
nut_reader  = NutReader.getNutasciiReader(nut_file)

reader.read().parse();

plots       = reader.getPlots().toArray()
tran_plot   = plots[3]

tran_data   = pd.DataFrame({ w: tran_plot.getWave(w) 
                             for w in tran_plot.getWaves().toArray() })

fig, axs = plt.subplots(1,1, figsize=(8,8))
axs.plot(tran_data['time'], tran_data['O'])
axs.set_title(tran_plot.getPlotname())
axs.set_xlabel(f'time ({tran_plot.getUnit("time")})')
axs.set_ylabel(f'O ({tran_plot.getUnit("O")})')
plt.show()

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.