Provides an implementation of the standard display transformations used in flow cytometry. The design goals of this implementation, aside from the essential computational one, are first to make these transformations comprehensible to the end users, i.e., scientists and secondly to ease the burden to implementers. To achieve the later, all transforms are implemented so that the {@link edu.stanford.facs.transform.Transform#scale(double) scale} method maps an appropriate range of data values onto a standard unit display interval [0,1] and the {@link edu.stanford.facs.transform.Transform#inverse(double) inverse} mapping is always implemented. Note that range checking is the responsibility of the calling program and this implementation will map data values outside the range without complaint and in a sensible way but with results falling outside the unit interval and possibly with reduced precision.
To make the transforms comprehensible they are all defined in terms of a consistent parameterization
that is closely related to the user experience.
All transforms are parameterized by the top of scale value T, which is always
mapped to scale position 1.
In addition, the logarithmic and log like transforms are parameterized
by M, the number of decades of data range mapped onto the unit display interval
by the {@link edu.stanford.facs.transform.Logarithmic} transform.
The log like scales are also parameterized by W and A, which are commensurate
with decades on the scale although they do not represent ten fold changes in data value.
W controls the degree of linearization for the the {@link edu.stanford.facs.transform.Logicle}
and {@link edu.stanford.facs.transform.Hyperlog} transforms.
The parameter A specifies an an additional range of negative data values that are
to be brought on scale.
For the {@link edu.stanford.facs.transform.Logicle} and {@link edu.stanford.facs.transform.Hyperlog}
transforms this is in addition to what is already brought on scale by W and should
generally not be needed.
The {@link edu.stanford.facs.transform.Logicle}, {@link edu.stanford.facs.transform.Hyperlog} and
{@link edu.stanford.facs.transform.Arcsinh} transforms with A = 0
will all behave like the {@link edu.stanford.facs.transform.Logarithmic Logarithmic(T,M)} transform with the same values
of T and M for large data values.
This choice of parameters also leads to a sensible fall back strategy when software does not implement a particular transform. For example if the logicle transform is not available a hyperlog transform with the same parameters should be a reasonable alternative and vice versa. In cases where neither is available {@link edu.stanford.facs.transform.Arcsinh#Arcsinh(double, double, double) Arcsinh(T, M, W + A)} although almost never really satisfactory, will at least map roughly the same data range onto the unit display interval. Finally it should be noted that {@link edu.stanford.facs.transform.Arcsinh#Arcsinh(double, double, double) Arcsinh(T, M, A)} is completely equivalent to {@link edu.stanford.facs.transform.Logicle#Logicle(double, double, double, double) Logicle(T, 0, M, A)} so it is not strictly necessary to implement the arcsinh transform as a separate class. One is provided here primarily to fix the relevant formulas.
One practical drawback to using the log like functions is that standard graphics packages do not contain suitable axis drawing routines. Fully addressing this is beyond the scope of this implementations but it does provide some help in chosing suitable points on the axis to label. Each transform has a {@link edu.stanford.facs.transform.Transform#axisLabels()} method, which returns an array of data values such that a graphical representations of the data values located at the scale possition for each value the will produce a decent default display.
Since the logicle and hyperlog functions cannot be represented in closed form using the standard functions of analysis they are actually defined in terms of their respective inverse functions. Inverse functions for the logarithm and arcsinh are provided for comparison.
| Transform | Inverse function |
|---|---|
| Logarithmic | f -1(x) = a e b x |
| Logicle | f -1(x) = a e b x - c e -d x + f |
| Hyperlog | f -1(x) = a e b x + c x - f |
| Arcsinh | f -1(x) = a sinh (b x - c) |
This is a reference implementation, generally accurate to double precision in the standard display interval. It is reasonably fast but highly optimized routines with lower precision that are still perfectly adequate for use in flow cytometry may be several times faster.
The Logicle methods was originally described in the publication:
A new "Logicle" display method avoids deceptive effects of logarithmic scaling for low signals and compensated dataavailable online as PDF or HTML . Further refinements and this standard parameterization were presented in the publication
David R. Parks, Mario Roederer, Wayne A. Moore,
Cytometry Part A, Volume 69A, Issue 6, Pages 541-551
Update for the logicle data scale including operational code implementationsavailable online as PDF or HTML.
Wayne A. Moore, David R. Parks
Cytometry Part A Volume 81A, Issue 4, pages 273–277, April 2012
The Hyperlog methods was originally described in the publication:
Hyperlog—A flexible log-like transform for negative, zero, and positive valued dataavailable online as PDF or HTML .
C. Bruce Bagwell
Cytometry Part A, Volume 64A, Issue 1, pages 34–42
The method is included in the Gating-ML proposed standard of the International Society for the Advancement of Cytometry. The specifications for Gating-ML are available here.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The Logicle method is patented under United States Patent 6,954,722. However, Stanford University does not enforce the patent for non-profit academic purposes or for commercial use in the field of flow cytometry.
@author Wayne A. Moore @version 1.0