• NIR-Predictor – Manual
• Predicting Spectra
• Creating your own Calibrations
• Configure the Calibrations for prediction usage
• Applications
  • The use-all case
• Prediction Result Report
  • Histograms of Prediction Values per Property
  • Spectra Plot Thumbnail on the Prediction Report
  • Outlier Detection
  • Result Ordering
  • Print to PDF
  • Archiving Reports
• Enter lab values to NIR spectra
  • Entering the laboratory reference values for NIR calibrations
  • Create Properties File
• Create Calibration Request
  • When all is fine
• Program Settings
• Further References

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

0. 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

1. 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!

2. 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.

3. 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.

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

5. 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”.

Configure the Calibrations for prediction usage

Configuration:

1. in NIR-Predictor : Menu > Open Calibrations (F9)

2. an explorer window is opened where the calibrations are located

3. create a folder for your application, choose a name

4. copy the calibration file(s) (*.cm) into that folder

5. in NIR-Predictor : Menu > Search and load Applications (F4)

Usage:

6. in NIR-Predictor : open the Application drop down list, and select your application by name

7. if all is fine, the calibration file is valid and not expired, it shows : Calibration “1 valid calibation”

8. the NIR-Predictor is now ready to predict

9. to switch the application, goto 6.

Applications

The Application concept allows to group multiple Calibrations together for an 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.

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.

Spectra Plot Thumbnail on the Prediction Report

Visualizes the min,median,max spectrum of the spectra dropped as files on the NIR-Predictor. This gives a minimal and good spectral overview of the predicted property results.

• Spectra Plot color legend: min,median,max spectrum by predicted property or if no calibration is available by spectral intensity.

• The min,median,max is determined from the predicted properties or if not available from the intensity of the spectra.

• Beside the histogram of the predicted properties, where the distribution can be seen, the spectra shown are the ones from min,median,max predicted property.

• This gives a minimal and good spectral overview of the predicted property results.

• The “Spectral Range” and number of datapoints is shown in the Prediction Report Header below the listed spectra files.

• To zoom the spectra plot a little, zoom the report in the browser (hold ctrl + mouse wheel, or pinch on touch screen).

• The spectra plots and histograms are stored with the report and can be archived.

Note

• Note that the spectra are shown in the raw values that are loaded, they are not shown pre-processed as the calibration model uses them to make the prediction.

• Note that the median property spectrum is the median from the predicted property pobulation and not the “median” of the calibration property range.

• Note that in the multi calibration prediction case, the spectra are selected for each property based on the related predicted property values and so the spectra plots shows typical different spectra.

Outlier Detection

To safeguard the prediction results, outliers are automatically checked for each individual prediction. This is based on limits that are determined when creating the calibration with the base data. Thus, a strange spectral measurement can be detected and signaled as an outlier even without base data only by means of the calibration and the NIR predictor. A prediction result with outlier warning is to be distrusted. How the various outlier tests are interpreted and how to avoid them in practice is described here.

The spectrum is an outlier to the model, if the spectrum is not similar with the spectra and lab-values the model is built with.

This legend is shown on each NIR-Predictor prediction report below the results:

Outlier (Out) Symbol Description

• “X” : spectrum does not fit into model (spectrum different to model)
• “O” : spectrum is wide outside model center (spectrum similar to model but far away)
• “=” : prediction is outside upper or lower range of model (property outside model range)
• “-” : spectrum is incompatible to calibration

Note: A prediction result with outlier warning is to be distrusted.

There are 3 outlier cases (X, O, =) and the incompatible data case “-”.

• The bad case is “X”
• the medium case is “O”
• and the soft case is “=”.

The technical names in literature correspond to:

• “X” : Spectral Residual Outlier
• “O” : Leverage Outlier
• “=” : Property Range Outlier

These 3 outlier cases can appear in combinations, like “XO=” or “XO” or “O=” or “X=”. The more outlier marker are shown the more likely the spectrum is an Outlier.

The default setting in NIR-Predictor Menu > “Report with Simplified Outlier Symbols”

• is ON, that will show only the worst case instead of all combinations to have a simplified minimal information.
  
• if OFF, that will show the combinations (e.g. “XO=” or “XO” or “O=” or “X=”), which is more informative for analyzing problem cases.

Some hints to avoid these Outliers:

• “X” : spectrum does not fit into model (spectrum different to model)
  Check if the spectrum is noise only, or has no proper signal. That can happen when measured past the sample or measured into the air or at a different substance. If you have multiple NIR instruments of the same type, use spectra measured with different instruments for the calibration.

• “O” : spectrum is wide outside model center (spectrum similar to model but far away) Sample temperature has an effect on NIR spectra shape, use spectra measured at different (typical use) temperatures (sample temperature, instrument temperature).

• “=” : prediction is outside upper or lower range of model (property outside model range)
  Use more spectra for the calibration in the Lab value region where your special interest is. If the predicted value is only a little bit out of the calibration range, it can be Ok. Add these spectra to the calibration spectra (with the Lab values), to extend the prediction range of the calibration.

• “-” : spectrum is incompatible to calibration
  The spectra (from the NIR instrument) has a different wavelength range or a different resolution than the spectra used for calibration. Check Instrument settings (wavelength range, resolution)

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.

Print to PDF

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

• Data File Formats : NIR-Predictor supported Spectral Data File Formats

• Release Notes : NIR-Predictor – Release Notes History

• Frequently Asked Questions: NIR-Predictor – FAQ