Creating custom calibrations using oc-cal

In this set of notes we describe how to create custom calibrations for the Open Colorimeter using the command line program oc-cal. This program is part of the open-colorimeter-utils package which is available on PyPi (The Python Package Index). To use oc-cal you will need a working version of Python and we suggest using a version of Python >= 3.10.5.

Installation

You can install the open-colorimeter-utils package using the Package Installer for Python "pip". The basic installation command is as follows

pip install open-colorimeter-utils

Note, as with any python package, we recommend installing using into Python virtual environment when possible. For a brief introduction to Python virtual environments see the following.

Usage

Once you have the open-colorimeter-utils package installed you will be able to run the oc-cal program. To get help run

oc-cal --help

This should display the following information describing how to use the program

Usage: oc-cal [OPTIONS] [INPUT_FILES]...

  Generates an Open Colorimeter calibration .json file from the .toml input files

  .toml file format 
  -----------------
  name = "TestName"          # Name of the test
  led = 630                  # Led wavelength
  units = "ppm"              # Measurement units
  fit_type = "polynomial"    # Fit type, polynomial or linear
  fit_order = 2              # Order of the fit
  values = [                 # Array of measurements
      [c0, c1, .... , cn],   # Measurements in units
      [a1, a1, .... , an]    # Corresponding absorbances
      ]

Options:
  -o, --output-file FILENAME  output file
  --help                      Show this message and exit.

To use oc-cal you simply pass it a list of .toml files containing your calibration data. The oc-cal program will then generate a calibration.json file which you can download to your colorimeter.

For example, suppose you have created two files called "caldata1.toml" and "caldata2.toml" containing calibration from two sets of measurements. Then to generate a calibrations.json file for you Open Colorimeter you would run

oc-cal caldata1.toml caldata2.toml

The calibrations.json file will be created in your current directory. To specify another location or a different name you can use the -o option

oc-cal -o some_other_name.json caldata1.toml caldata2.toml

In addition, when run, the oc-cal program will generate a plot showing the fit for set of measurements.

Calibration .toml files

The calibration data used by oc-cal is specified in files using the toml format - which stands for Tom's Obvious minimal langauge. The toml format is very simple and is a commonly used configuration file format. Further documentation of toml can be found here.

An example of the format of the .toml calibrations used by oc-cal is shown below.

name = "Ammonia API"
led = 630
units = "ppm" 
fit_type = "polynomial"
fit_order = 2
values = [
    [0.00, 1.60, 3.20, 4.80, 6.40, 8.00], # concentration
    [0.00, 0.55, 1.10, 1.53, 1.87, 2.00]  # absorbance
    ]

There are six key/value pairs in the calibration file

name: a string specifying the name of the test
led: an integer specifying the led wavelength used in nm
units: a string specifying the units of the measurement, e.g. ppm.
fit_type: the fit type for the calibration, either "linear" or "polynomial"
fit_order: the order of the polynomial fit, must =1 for linear
values: array of data values for measurement and corresponding absorbance

Source Repository

The source code for oc-cal can be found in the open-colorimeter-utils repository on github here.

Open Colorimeter Product Guide

Documentation site for the Open Colorimeter, Multi-Channel Colorimeter, UV Open Colorimeter & Open Colorimeter Plus

Product Guide Home Page