Usage

Values

Excitation Efficiency
The excitation efficiency measures how effectively the excitation light is exciting the dye as a percentage of its maximum absorption. It is calculated by multiplying the light source spectra by the excitation filters and dichroics, and then the absorption spectra of the dye.
Emission Efficiency
Represents how much of the dye emission is actually captured on the images. It is the area of the transmission spectrum divided by the area of the dye emission spectrum.
Brightness
This is a value relative to Alexa-488 times 10. It takes into account the dye excitation efficiency and quantum yield but is sensitive to environment and so must be used with caution and critical thinking. For example, DAPI is not a very bright dye but there's usually a high amount of DNA to bind to and its fluorescence increases after it binds.

It is possible to create URLs for specific setups or components by specifying it on URL fragment identifier. For example, adding #dye=GFP to the URL will initialise SPEKcheck with the GFP dye. Similarly, the fragment #setup=DV Elite Quad DAPI will load a setup with the same name.

The query component of the URL can also be used to filter the list of setups available for selection. For example, adding the #setup=OMXv3 to the URL will initialise SPEKcheck with only the setups matching that name. The value for setup query can be any javascript regular expression. For example:

?setup=OMXv3
Any setup with the text OMXv3
?setup=OMXv3|2
Any setup with the text OMXv3 or OMXv2
?setup=^OMXv\d
Any setup whose name starts (^) with the text OMXv, followed by a digit (\d).
?setup=^OMX.*DAPI$
Any setup whose name starts (^) with the text OMX, followed by any text (.*), but with DAPI at the end ($).

Installation

SPEKcheck is a fully client-side web application. It runs on a web browser such as Firefox, either locally or served through a web server. In addition, it can be included as part of another web page.

Requirements

SPEKcheck requires support for HTML5 and ECMAScript 2015. Effectively, this means that SPEKcheck will not run in Internet Explorer, very old versions of other web browsers, and web browsers with javascript disabled.

Local installation

  1. Download latest version of SPEKcheck
  2. Extract all files from the archive wherever
  3. Open the index.html file on a web browser such as Firefox

Installation on web server

SPEKcheck runs fully client-side and can be served as a static site. To serve your own instance of SPEKcheck, simply extract all files into whatever location the web server is configured to use.

If you are setting a new instance of SPEKcheck on your own web server, you are probably also looking to configure the available setups and components. All configuration is done by editing the files in the data directory. Data files for each component should be place into the directories detectors, dyes, excitation, and filters and their names, minus the .csv extension, listed on the corresponding json file. The setups.json file describes the predefined setups (see Section File Formats).

Included on another webpage

The SPEKcheck application can be included as part of another webpage. The main use of case of this usage is to include SPEKcheck on a page for a specific microscope. For example, a microscope facility which has a page for each of their microscopes can include SPEKcheck with only the setup and components associated with the system.

SPEKcheck is dependent on bootstrap, jQuery, and Chart.js and so those need to be referenced. SPEKcheck will inject itself into any HTML element.

Code to insert SPEKcheck as part of another page 
<script>
  document.addEventListener('DOMContentLoaded',
                            () => main(document.querySelector('#spekcheck')));
</script>

File Format

Microscope setups and new components can be defined in specific files within the data directory structure. These are defined below.

Setups file

In SPEKcheck, a microscope setup is defined by a series of components: an excitation source, a stack of filters on the excitation path, a dye, another stack of filters on the emission path, and a detector.

Setups are defined in JSON format. All components must be defined although their values may be null or, in the case of emission and excitation paths, empty arrays. The names of each components must match the name used on the collections and is case sensitive. In the case of filters, they must be paired with their mode which must have a value of "r" or "t" for reflection or transmission respectively. The dichroic filters are part of both excitation and emission paths. As such, they should appear in both in the description, with opposing modes.

An example setup definition. 
{
  "detector": "Detector Name",
  "dye": "Dye Name",
  "excitation": null,
  "ex_path": [
    {"filter": "Dichroic Name", "mode": "t"}
  ],
  "em_path": [
    {"filter": "Dichroic Name", "mode", "r"},
    {"filter": "Filter 2 Name", "mode", "t"}
  ]
}

The file data/setups.json will define all the setups available for selection. This file must defined a JSON Array which will be used to construct a Map object. Each element in the Array must be a two-element array, the first element a String with the setup name, and the second element, a JSON object with the setup description. Because a Map is used, the order used to define each setup on this file will be used on the SPEKcheck menus. This allows to order and group setups by any function other than alphabetical.

A data/setups.json file example. 
[
  [
    "Setup 1 Name",
    {
      "detector": "Detector Name",
      "dye": "Dye Name",
      "excitation": null,
      "ex_path": [
        {"filter": "Dichroic Name", "mode": "t"}
      ],
      "em_path": [
        {"filter": "Dichroic Name", "mode", "r"},
        {"filter": "Filter 2 Name", "mode", "t"}
      ]
    }
  ],
  [
    "Setup 2 Name",
    {
      "detector": "Maybe Another Detector Name",
      "dye": null,
      "excitation": "Excitation Source Name",
      "ex_path": [
        {"filter": "Dichroic Name", "mode": "t"}
      ],
      "em_path": [
        {"filter": "Dichroic Name", "mode", "r"},
        {"filter": "Filter 3 Name", "mode", "t"}
      ]
    }
  ]
]

Data Files (CSV with text header)

The file format for each component is a plain text file: a multiline key/value header with comments, followed by the spectrum values in a CSV format.

The header of the data files has a series of key/value pairs and optional comments. Comments are lines starting with the # character. Only data files for dyes require a header, which must have the keys Extinction coefficient and Quantum Yield. While the keys must exist, their values are optional.

The CSV section of the file declares the spectra data. The first line of the CSV names the columns and the first column must always be wavelength. The wavelength values must be in nanometers. The other columns have the spectra values and must be in the [0 1] or [0 100] range. The columns names must be absorption and emission for dyes, intensity for excitation sources, reflection or transmission for filters, and qe for detectors.

Example Dye file
# Type: Dye
# Name: the name (actually ignored)
# This line is a comment and will be ignored
# The 'Extinction coefficient' and 'Quantum Yield' lines are still
# required, but their values can be empty if not known.
Extinction coefficient:
Quantum Yield:
wavelength,absorption,emission
250,0.494230986,0.000
251,0.489300013,0.000
252,0.489378005,0.000
253,0.490633011,0.000
...
Example Filter file
## Type: dichroic filter
# Name: this filter name
# Instead of transmission, this file could instead have reflection too.
wavelength,transmission
450.088864,0.004743
450.204180,0.005017
450.319497,0.004637
450.434813,0.004622
450.550130,0.005573
...
Example Excitation file
# Type: excitation source
# Name: 442-laser
wavelength,intensity
441,0
442,1.0
443,0
Example Detector file
## Type: detector
# Name: The Detector name
# The source of the file is a useful thing to keep as a comment.
wavelength,qe
410, 0.0093
420, 0.0175
430, 0.0273
...