NIR-Predictor – Frequently Asked Questions (FAQ)


NIR-Predictor – FAQ

Please also refer to the NIR-Predictor – Manual and check the Hints and Notes.


How to Configure / Load / Import / Activate / Setup / Use the Calibrations (*.cm) in NIR-Predictor?

Chapter “Configure the Calibrations for prediction usage” – NIR-Predictor – Manual


Do you have a calibration file for XY ?

We create custom calibrations out of your NIR + Lab measurements of XY.
We do not sell off-the-shelf calibrations.


I have downloaded the software but can’t see it?

Please note, that the download time will be very short, because of the small file size.
Check your browser’s download folder. The download is the file “NIR-PredictorVx.y.zip”


Why a .zip and no installer (Setup.exe) ?

Because a .zip deploy keeps it simple for all:

  • easy : no Administrator rights needed to install, delete it to uninstall
  • harmless : no system changes during setup
  • transparency : you see what you get

Is there a command line (CLI) version of NIR-Predictor ?

If you want to customize it in all details, our OEM API for NIR-instrument-software (White-Label) integration gives you full access. If you are an NIR-Vendor (or similar) please contact us via email info@CalibrationModel.com


The free NIR-Predictor does not create a model, what is wrong ?

As the name says, the NIR-Predictor just predicts NIR data with a model. To create a model you need to send your data to the CalibrationModel service, after development process you get an email with a link to the calibration where it can be purchased and downloaded.


Why does the creation of the PropertyFile.txt take so long with hundrets of spectra files?

It normally takes only 1-10 seconds not minutes.
Make sure that the spectra data files are stored locally on your main drive
and not on a cloud-drive or network storage or slow USB thumb drive or SD-Card.


Is there a way to use converted ASCII spectrum data to be used in NIR-Predictor?

Yes, this is the simplest ASCII CSV file format the NIR-Predictor supports.
And there are other formats supported.


Can you convert old calibration data from vendor A to be integrated to our new vendor B NIRS calibration data in our instrument?

No, we don’t do model or spectra conversion / transformation (aka model transfer).
We build optimized models with wavelength compatible data.


Does NIR-Predictor contain any malware, spyware or adware?

No, NIR-Predictor does not contain any malware, spyware or adware.


How to copy the prediction results from the table in the browser?

Copy selected columns from the table.
By holding down the Ctrl key, rectangular areas in the table can be selected with the mouse and copied to the clipboard with Ctrl+C and then copied to a spreadsheet program with Ctrl+V.


Will an expired calibration still work?

No. Until you extend the usage time.
The expired calibration file will be moved to the CalibrationExpired folder on the next start of NIR-Predictor or “Search and load Calibrations” menu function.

Selected Calibration files from the folder CalibrationExpired can be send to info@CalibrationModel.com with your Request file (.req) files for extending their usage time.

There is the possibility to get a perpetual usage, which means their is no expiration (valid until 2050).

That way you can get the time extended calibration back, that behaves exactly as the one before with extended usage time.


What does the calibration Expiration date mean exactly on the Prediction Report?

The Expiration date, it is the final day when the calibration will be valid (similar to credit cards).


What does the (number) in brackets after the [range] mean?

During the creation of a Calibration Request the NIR-Predictor shows a message containing
” ‘Prop1’ / “Quantitative [1.40 – 2.90] (154) ”
here 154 is the number of unique values in the property range.


How long does it take to create of the property file and calibration request file from 500 spectra files?

Use a local folder on your computer (not a network drive) for your spectra files then the property file and the calibration request file is created in around 1-3 seconds. (measured on a system with SSD drive, Intel i7, 2.4 GHz)


I tried to create the calibration request and got the error message: The number of Property Values of all spectra are different?

Use the generated PropertiesBySpectra (Note: Spectra not Sample) template file.
Do not reformat the generated template file, just fill in the Property values and save as Text CSV (*.csv) file (not as Excel file “.xlsx”).


Are you able to create the calibration if we only have 20 spectra?

To create a reliable quantitative calibration you need measured spectra of at least 48..60 (more is better) different samples with different Lab-values in the required measuring range!
The NIR-Predictor will check for that automatically.


Same sample measured multiple times (replicate measurements), how to enter the Lab-value only once in Property file?

Use the created PropertiesBySample template (not the PropertiesBySpectra).


Different samples with exact the same Lab-value, how to enter the Lab-Values?

Entering the Lab-values into the generated PropertiesBySpectra template the NIR-Predictor detects them as the same Sample and as a result we have too less different values to build a calibration. But in my case these are different samples with exact the same Lab-value, how to do?

You have to cheat a little bit to make NIR-Predictor do not detect same sample as measured multiple times. This is because most NIR users do replicate measurements on the same sample and NIR-Predictor looks for that. In PropertiesBySpectra modify the values a little bit to make them different, e.g.
0.18
0.18001
0.18002


Is the free NIR-Predictor software you provide for anyone to download and use?

Yes, if downloaded directly from our homepage by the user.
See also Software License Agreement


What is an Outlier?

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.

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.
See also manual chapter Outliers.


If something is wrong, please tell us

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


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:

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

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

  3. the NIR-Predictor is now ready to predict

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

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.

Spectra Plot

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.

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