NIR-Predictor – Manual


NIR-Predictor – Manual

Predicting Spectra

It’s easy to use with NIR-Predictor,
just drag & drop your data for getting the prediction results.

It supports an automatic file format detection.
So you don’t need to specify the instrument type and settings! See the list of supported formats and NIR Vendors: NIR-Predictor supported Spectral Data File Formats

Use the included data to checkout how it feels:

  1. Open the demo Spectra folder by using the Menu > Open Demo Spectra or press F8.
    There are files with spectra from different Vendors.

  2. Drag & drop a spectra file onto the NIR-Predictor window (or press Ctrl+O as for ’Open some files).

  3. The spectra will be

    • loaded
    • pre-processed
    • predicted and
    • reported

Note:
All the steps are fully automatic.
All calibrations that are compatible with the spectra, will produce prediction results in one go.
To select specific calibrations choose the Application. Where the ” ” empty means use all the calibrations.
To define a Application read more in chapter “Applications”

Hint:
To get access to Statistics of Predictions and Reports use the Menu > Show more/less (Ctrl+M) or you can simply resize the window. Here you can also re-do the Analyze step manually with changed inputs (e.g. Result Ordering).


Creating your own Calibrations

How it works – step by step

  1. You have measured your samples with you NIR-Instrument Software.
    And got the Lab-values of these samples.

    samples
    -> measured NIR-spectra
    -> Lab-references analytics

  2. Now you need to combine these data.

    NIR-spectra + Lab-references
    -> PropertiesBySamples

    Note: If you combined these data already in your NIR software used,
    and you can export it as a JCAMP-DX file then use
    Menu > Create Request File .req ... (F2)
    and read the “Help.html” and NIR-Predictor JCAMP.
    Else proceed as below.

    The NIR-Predictor provides tooling for that:

    Menu > Create Properties File... (F6)

    Select the folder with your NIR spectra measured for an application.
    NIR-Predictor creates a customized Properties file template for that data to enter the Lab values.

    Note: You don’t need to specify your instrument or vendor or an application. It’s all done automatically. And also the sample spectra are detected and grouped automatically!

  3. Use your favorite editor or spreadsheet program to enter and copy&paste
    the Lab-references Values into the columns “Prop1”, “Prop2” etc. and save the file.

  4. A final check of your entered data is done by NIR-Predictor,
    to make sure your data ist complete and all is fine.

    Menu > Create Calibration Request... (F7)

    Select the folder with the filled file.
    A CalibrationRequest.zip is created with the necessary data
    if enougth diverse Lab values are entered.

  5. Email the CalibrationRequest.zip file
    to info@CalibrationModel.com to develop the calibrations.

  6. When your calibrations are ready, you will receive an email with a link
    to the CalibrationModel WebShop where
    you can purchase and download the calibration files,
    that work with our free NIR-Predictor software without internet access.

    Note: Your sent NIR data is deleted after processing.
    We do not collect your NIR data!

Note: Further details can be found under “Create Properties File” and “Create Calibration Request”.


Applications

The Application concept allows to group multiple Calibrations together for a Application. By selecting an Application before prediction, only the Calibrations belonging to the Application will be used for Prediction. In the Demo Data this is used to have multiple spectrometer as Application. This can be used easily as e.g. as Application “Meat Products” containing Fat and Moisture Calibration.

To create an Application, create a folder with the Application’s name inside the Calibrations folder, and move/copy all the Calibrations files to this Application folder. To remove a Calibration from the Application, remove the Calibration file from the Application folder.

After creating an new Application folder, press menu Search and load Applications (F4) to update the NIR-Predictor dialog where the Application can be selected via the dropdown list. You don’t need to close the NIR-Predictor.

After moving Calibration files around, press menu Search and load Calibrations (F5) to update the NIR-Predictor dialog.

The use-all case

In the NIR-Predictor dialog where the Application can be selected via the dropdown list, the empty "" name means that all (yes all) valid Calibrations will be used for prediction.

Note: The Prediction Report will contain only results from spectral compatible Calibrations with the given spectra. That allows to automatically handle the multi vendor NIR instrument usage.


Prediction Result Report

Histograms of Prediction Values per Property

Shows the distribution of the predicted results per calibration. The histogram range contains the range of the calibrated property and includes the predicted results.

The histogram bar (bin) color is defined as follow:

  • blue : all predictions inside calibration range.
  • red : all predictions outside calibration range.
  • orange : some overlaps with calibration range.
    So not all spectra in a orange bin are outside calibration range.
Histograms

Note: Predicted values are always shown in Histogram table and Prediction Value List table, even if the spectrum does not fit into model (spectrum different to model, aka Residual Outlier) shown as Out = X.

Note: Old browsers like Microsoft Internet Explorer 11 don’t support the grafics for Histogram charts. Use an current browser like Firefox or Chrome or Edge.

Note: If your browser opens the report too slow, try to deactivate some browser plugins, because they can filter what you look at and some add-ons are really slow.

Result Ordering

To change the ordering, a drop-down-box is located below the Analyze button. If there is an analysis from the current session, and the Result Ordering is changed, the data is re-Analyzed and reported with the new Result Ordering setting. That allows to compare the different orderings. The Result Ordering is listed in the Prediction Report above the Prediction Value List and stored in the settings.

The order/sorting of the prediction results of the spectra can be defined:

  • GivenOrder (default) the given order of the spectra from file select dialog or drag&drop

*) sorted : ascending sort

  • Date_Name sorted by Date (if any) and then by Name
  • Name_Date sorted by Name and then by Date
  • Date_NamesWithNumbers sorted by Date (if any) and then by Name with number logic
  • NamesWithNumbers_Date sorted by Name with number logic (e.g. “ABC1” is before “ABC002” ) and then by Date

*) as above but sorted Rev : reverse sort = descending sort

  • Rev_Date_Name
  • Rev_Name_Date
  • Rev_Date_NamesWithNumbers
  • Rev_NamesWithNumbers_Date

E.g. with reverse sort by Rev_Date_Name, the newest spectra appear on top.

Depending on how many calibrations are used the result table is getting broader. To print the report (e.g. to Adobe PDF, FreePDF or Microsoft XPS), sometimes the landscape format is shorter in number of pages or in portrait a scale of 80% fits nicely. Or try another internet browser (Mozilla Firefox, Google Chrome, Microsoft Edge, …) to print the report and set the browser as your default browser so it will be opened by default.

Archiving Reports

Each report is contained in one file only, including the grafics. To save storage space the report file folder can be compressed to a zip file (.zip, .7z).


Enter lab values to NIR spectra

Entering the laboratory reference values for NIR calibrations

We have developed specialized tools into NIR-Predictor to combine the NIR and Lab data is a sample-based safe manner.

The main target is to improve Data Quality during the step of combining of the Lab data and the NIR data, because to model a good reliable calibration the data that build the base needs to be of high quality.

It also simplifies to enter the lab values manually to the corresponding NIR data, because of automatically grouping repeated NIR measurements of the same sample, so the lab values can be entered sample based and not by spectrum.

It helps to avoid false reference data, because of the broken relation of NIR spectra and reference values, data entry on the wrong position in the table.

And Helps to detect errors of duplicated or multiple copies of spectra files, and checks for inconsistencies in Date-Time and Sample-Naming. It also checks for missing values.

That all increases the Data Quality for the next step of Calibration Development, and makes data entry a less time consuming and less risky work.

How it works

  1. Menu > Create Properties File... (F6) select the folder with your NIR spectra measured for an application. NIR-Predictor creates a Properties file template for that data : PropertiesBySamples.csv.txt

  2. Use your favorite editor or spreadsheet program to enter and copy&paste the Lab Values into the columns and save the file.

  3. Menu > Create Calibration Request... (F7) select the folder with the filled file for a last check and a Calibration Request file is created with the needed data as a single zip file.

  4. Email the Calibration Request file to info@CalibrationModel.com to develop the calibrations.

Ok that is it, the NIR-Predictor guides you through the steps needed. And if you need to know more details, the Chapter “Create Properties File” is for you.

Create Properties File

Note:

  • If you have (exported) JCAMP-DX files containing the Lab-Values, you don’t need to do this step.
    You can send the JCAMP file with your Request (.req) file directly to the calibration service at info@CalibrationModel.com.
  • If your JCAMP-DX files does NOT contain Lab-Values, this is a way to go.

For calibrating the spectra to the lab-values you need to assign the lab-values to the spectra. The easiest way is to have a table where each spectrum (row) is linked to multiple lab-values (columns). This function Create Properties File build such a table for the selected spectra folder automatically!

This table is stored in the file PropertiesBySamples.csv.txt. This can be created for any spectra folder you like. The file extension is .csv.txt to make it easy to edit in a text editor and also in a spreadsheet (excel). The columns are standard TAB separated.

The file header line contains :

Sample Replicates Names Prop1 Prop2 Prop3 DateFirst DateLast Hashes

Where Name and Date describes the spectrum.

Prop1, Prop2, Prop3 are the place to enter the Lab Reference Concentrations properties corresponding to each spectrum. It can be extended to Prop4, Prop5, … etc. Of course you can enter real word names like “Fat (%)” instead of “Prop1”. It’s recommended to put the measurement unit beside the name.

Replicates is the number of replicated or repeated spectra of a sample that is grouped together in the Sample based property file. Sample name and the DateFirst / DateLast between the sample spectra are measured.

Date format is ISO-8601. Missing Dates are 0002-02-02T00:00:00.0000000.

If the file PropertiesBySamples.csv.txt already exist in the selected folder, the user will be notified (it will not be overwritten, because the file may contain user entered Lab-values). The Lab Reference Concentrations values are initialized to 0 (zero) and needed to be changed.

Note: 0 is not interpreted as missing value! If you have a 0 concentration value, put in 0 or 0.0 .

The entry of properties is as easy as possible, because it’s organized by Sample (and not by Spectra), so it’s like your Lab-Value Table that is sample based. The sample rows are sorted in a special way by Sample name. Sorting by Date or alphabetically by Sample can done easily in a spreadsheet program.

Note: when coping lab values to the samples make sure they correspond, so that there are no gaps and the sorting is the same.

The Spectra (rows) are initially sorted by name (and date) to have the replicates/repeats together. You can sort for your convenience in a spreadsheet program.

Enter the Lab Reference Concentrations to the spectra/sample.

Enter the Lab-Values in spreadsheet (e.g. Excel) or a text editor (e.g. Notepad++). If done, use the next menu Create Calibration Request.

Hints: Data handling:

  • The NIR-Predictor creates the PropertiesBySamples.csv.txt once, after that the user is responsible for its content. That means NIR-Predictor does not change this file anymore.

  • You can remove entire rows (spectra) in the property file. You don’t need to remove the spectra files. The NIR-Predictor is aware of the relation, the PropertiesBySamples.csv.txt defines what will be calibrated.

  • How to add more spectra files?

    The additional spectra can be handled in a separate folder, create the property file and copy the spectra to the other folder and copy/merge the property files together in your editor or spreadsheet.

    Or

    Copy the spectra into the folder, rename the PropertiesBySamples.csv.txt to e.g. “PropertiesBySamples-Part1.csv.txt” and use Create Properties File to create a new PropertiesBySamples.csv.txt with all the spectra. You can copy/merge the content of the Properties files together in your editor or spreadsheet.

  • What happens with possible duplicate rows? It does no harm to the Calibration because we do an exact checking and data cleaning in the calibration process.

  • What happens to duplicate spectra names? The spectra names are not relevant for the calibration process. The spectra names are helpful to assign the lab-values to the corresponding spectrum entry. That’s why the table is initially sorted by name. The spectra names can be edited by the user.


Create Calibration Request

The menu function Create Calibration Request packs a created Properties file (see “Create Properties File”) and it’s linked spectra files in a compressed ZIP file for sending to the CalibrationModel.com Service.

Please note that the number of measured quantitative samples need to be at least 60 . That means you need at least 60 different spectra (not counting the replicate/repeated measurements).

It shows additional property information about the data you have entered, like – the property type (Quantitative) – it’s range (min – max) and – the number of unique values and – if the Lab-values are enough diverse to get calibrated.

First select the folder with the PropertiesBySamples.csv.txt and measured spectra files of samples you have Lab-values. The data is checked and you get notified what is missing or might be wrong. If something needs to be changed, edit the PropertiesBySamples.csv.txt and do Create Calibration Request again. Your last selected folder is remembered, so you can press return in the folder selection dialog.

Hint: The keyboard shortcuts for redoing it after you edited some entries is : F7 Return – that allows you to get the property information quickly.

Hint: If you open the PropertiesBySamples.csv.txt in a spreadsheet program, you can create Histogram plots of the entered Lab-values, to see in which range are to less samples measurements.

When all is fine

When all is fine the “CalibrationRequest.zip” file is created for that data.

The ZIP file contains:

  • your PropertiesBySamples.csv.txt
  • your personal REQuest file for your computer system, that looks like
    e.g. “337dcdc06b2d6dfb0b5c4bba578642312edf2ae84d909281624d7e26283e8b07 WIN-GB0PB48GSK4.req”
  • the spectra data files

Note: If the CalibrationRequest.zip file is already created and you change the PropertiesBySamples.csv.txt make sure to delete the old CalibrationRequest.zip file first! In the dialog it states if it was successfully created or NOT because it already exist. So you are always on the safe side.

Note: CalibrationRequest.zip file name contains the property names to know what would be calibrated and at the end an identification number for referencing the file. E.g. “CalibrationRequest ‘Prop1’ – ‘Prop2’ h31T3wOH.zip”


Program Settings

  • The users program settings are stored in UserSettings.json
  • The program counters are stored in GlobalCounters.json

Further References