Python API¶
Although the CLI can cope with most demands of Gecos users, there are some aspects, where the CLI is not flexible enough. This includes for example custom optimization processes or finetuned color spaces. This page explains the API of Gecos’ underlying Python code.
Colors¶
Gecos uses scikitimage to convert between L*a*b* and RGB space. However, the scikitimage function requires a specific shape for the array of colors. The following functions wrap the scikitimage functionality, generalizing it for any shape.

gecos.
rgb_to_lab
(rgb)[source]¶ Convert one or multiple RGB color(s) to Lab color(s).
 Parameters
 rgbarraylike, shape=(…, 3)
The color to be converted. The only restriction on the array shape is that the length of the last dimension must be 3. RGB values are in range (0,1).
 Returns
 labndarray
The converted color.

gecos.
lab_to_rgb
(lab)[source]¶ Convert one or multiple Lab color(s) to RGB color(s).
 Parameters
 labarraylike, shape=(…, 3)
The color to be converted. The only restriction on the array shape is that the length of the last dimension must be 3.
 Returns
 rgbndarray
The converted color. RGB values are in range (0,1).
In order to create a color scheme, the boundaries of the L*a*b*
color space must be known.
For this purpose a ColorSpace
object is used.

class
gecos.
ColorSpace
(file_name=None)[source]¶ Create a color space, that spans the complete RGB gamut of the Lab color space. The Lab components are discretized into integer values.
A color space describes the boundaries of the color scheme to be generated. It uses the Lab color space. In addition to the inherent limit to colors, that can also be displayed in RGB space, further parts of the space can be removed by calling
remove()
. Parameters
 file_namestr, optional
The path of a custom file to load the precalculated RGB convertible space from.
 Attributes
 shapetuple of int
The shape of the space, i.e. the amount of Lab values in each dimension.
 labndarray, shape=(100, 256, 256, 3), dtype=int
The complete discretized Lab color space in the ab range of
128
to127
. spaceshape=(100, 256, 256), dtype=bool
The allowed part of the lab attribute, i.e. the part that is convertible into RGB and was not manually removed.

remove
(self, mask)[source]¶ Remove a portion of the color space.
 Parameters
 spacendarray, shape=(100, 256, 256), dtype=bool
The space is removed where this mask is true.
Examples
Remove space below a defined lightness:
>>> L_MIN = 50 >>> space = ColorSpace() >>> lab = space.lab >>> l = lab[..., 0] >>> space.remove(l < L_MIN)
Optimization¶
A score function defines the objective of the color scheme generation. It assigns a score to a given color conformation. The color conformation is the entirety of the color component values for each symbol, also called coordinates. A more favorable color conformation gets a lower score than less favorable one.

class
gecos.
ScoreFunction
(n_symbols)[source]¶ Abstract base class for a score function. A score function calculates a score from a color conformation (coordinates).
The score is calculated by calling the object with the coordinates as single argument. Hence, classes inheriting from this base class mut override the
__call__()
method. Parameters
 n_symbolsint
The amount of symbols in the system. Equivalent to the length of the alphabet the color scheme is generated for. This value is used to check the shape of the coordinates when calling the score function.
The decision, whether a color conformation is favorable, is subject to the
actual implementation of the ScoreFunction
.
The mathematical details for the default score function are covered
here.

class
gecos.
DefaultScoreFunction
(matrix, contrast=700, distance_formula='CIEDE2000')[source]¶ Create an instance of the default score function Gecos uses.
The score function contains two terms: A sum of harmonic potentials between each pair of symbols, based on a substitution matrix, and contrast score that favors schemes with a high contrast.
 Parameters
 matrixbiotite.sequence.align.SubstitutionMatrix
A distance matrix is calculated from this score matrix. The equilibrium positions scale linearly with the values in the distance matrix.
 contrastint, optional
A weight for the contrast score.
 distance_formula{‘CIE76’, ‘CIEDE94’, ‘CIEDE2000’}, optional
The formula to use for calculation of perceptual color difference. While
'CIEDE2000'
is the most accurate formula for the perceptual difference,'CIE76'
features the fastest calculation.
The ColorOptimizer
performs the actual optimization of the color
conformation.
This means, that it tries to adjust the coordinates, so that the value of the
score function gets minimal.

class
gecos.
ColorOptimizer
(alphabet, score_function, space, constraints=None)[source]¶ Create an optimizer that tries to find an optimal color conformation within a given color space based on a score function.
The optimizer tries to minimize the return value of the score function by adjusting the Lab values (coordinates) for each symbol in a given alphabet.
The optimizer uses the random number generator from NumPy. Therefore, call
numpy.random.seed()
to set the seed for the optimizer Parameters
 alphabetbiotite.sequence.Alphabet
The alphabet to calculate the color conformation for.
 score_functionScoreFunction or callable
The score function which should be minimized. When calling the object, its only parameter must be an array of coordinates with shape (n, 3), where n is the length of the alphabet. Its return value must be a single float  the score.
 spaceColorSpace
The color space that defines the allowed space for the coordinates.
 constraintsndarray, shape=(n,3), dtype=float, optional
An array whose nonNaN values are interpreted as constraints. Constrained values will be fixed during the optimization.

optimize
(self, n_steps, beta_start, rate_beta, stepsize_start, stepsize_end)[source]¶ Perform a Simulated Annealing optimization on the current coordinate to minimize the score returned by the score function.
This is basically a MonteCarlo optimization where the temperature is varied according to a so called annealing schedule over the course of the optimization. The algorithm is a heuristic thats motivated by the physical process of annealing. If we, e.g., cool steel than a slow cooling can yield a superior quality, whereas for a fast cooling the steel can become brittle. The same happens here within the search space for the given minimization task.
 Parameters
 n_stepsint
The number of SimulatedAnnealing steps.
 beta_startfloat
The inverse start temperature, where the start temperature would be \(T_{start} = 1/(k_b \cdot \beta_{start})\) with \(k_b\) being the boltzmann constant.
 rate_beta: float
The rate controlls how fast the inverse temperature is increased within the annealing schedule. Here the exponential schedule is chosen so we have \(\beta (t) = \beta_0 \cdot \exp(rate \cdot t)\).
 stepsize_startfloat
The radius in which the coordinates are randomly altered at the beginning of the simulated anneling algorithm. Like the inverse temperature the step size follows an exponential schedule, enabling the algorithm to do large perturbartions at the beginning of the algorithm run and increasingly smaller ones afterwards.
 stepsize_endfloat
The radius in which the coordinates are randomly altered at the end of the simulated annealing algorithm run.
After optimizing the color conformation using
ColorOptimizer.optimize()
, the result of the optimization
is obtained via ColorOptimizer.get_result()
.

class
ColorOptimizer.
Result
[source]¶ The result of an optimization. Contains the final color scheme information as well as the course of the coordinates and the score during the optimization.
 Parameters
 alphabetbiotite.sequence.Alphabet
The alphabet the optimizer used.
 trajectoryndarray, shape=(m,n,3), dtype=float
The course of the coordinates during the simulation.
 scoresndarray, shape=(m,), dtype=float
The course of the score during the simulation.
 Attributes
 alphabetbiotite.sequence.Alphabet
The alphabet the optimizer used.
 trajectoryndarray, shape=(m,n,3), dtype=float
The course of coordinates during the simulation.
 lab_colorsndarray, shape=(n,3), dtype=float
The final Lab color conformation, i.e. the last element of trajectory.
 rgb_colorsndarray, shape=(n,3), dtype=float
The final color conformation converted into RGB colors.
 scoresndarray, shape=(m,), dtype=float
The course of the score during the simulation.
 scorefloat
The final score, i.e. the last element of scores.
Color scheme output¶
The color scheme from the ColorOptimizer.Result
can be written into
the Biotite compatible JSON format via write_color_scheme()
.

gecos.
write_color_scheme
(file, result, name='')[source]¶ Write a color scheme in the Biotite compatible JSON format into a file.
 Parameters
 filefilelike object
The file to write the scheme into.
 resultOptimizer.Result
The result from the optimization. Contains the color scheme.
 namestr, optional
Name of the scheme. Will be written to the value of the
"name"
key.