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 fine-tuned color spaces. This page explains the API of Gecos’ underlying Python code.

Colors

Gecos uses scikit-image to convert between L*a*b* and RGB space. However, the scikit-image function requires a specific shape for the array of colors. The following functions wrap the scikit-image functionality, generalizing it for any shape.

gecos.rgb_to_lab(rgb)

Convert one or multiple RGB color(s) to Lab color(s).

Parameters

rgbarray-like, 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)

Convert one or multiple Lab color(s) to RGB color(s).

Parameters

labarray-like, 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)

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 to 127.

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(mask)

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)

get_rgb_space()

Convert the Lab colors of the space in RGB colors.

Returns

rgbndarray, shape=(100,256,256,3), dtype=float

The RGB colors. Colors that cannot be displayed in RGB or were manually removed from the space are NaN.

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)

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.

abstract __call__()

Calculate the score for the given coordinates.

Parameters

coordndarray, shape=(n,3), dtype=float

The coordinates.

Returns

scorefloat

The score assigned to coord.

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')

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)

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 non-NaN values are interpreted as constraints. Constrained values will be fixed during the optimization.

optimize()

Perform a simulated annealing optimization on the current coordinate to minimize the score returned by the score function.

This is basically a Metropolis-Monte-Carlo optimization where the inverse temperature and step size is varied according to exponential annealing schedule over the course of the optimization.

Parameters

n_stepsint

The number of simulated annealing steps.

beta_start, beta_endfloat

The inverse temperature in the first and last step of the optimization, respectively. Higher values allow less increase of score, i.e. result in a steering into the local minimum. Must be positive.

stepsize_start, stepsize_endfloat

The step size in the first and last step of the optimization, respectively. it is the radius in which the coordinates are randomly altered at in each optimization step. Must be positive.

Notes

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.

set_coordinates()

Set the the coordinates of the current color conformation. Potential color constraints are applied on these. This coordinate changes will be tracked in the trajectory.

Parameters

coordndarray, shape=(n,3), dtype=float

The new coordinates.

get_result()

Get the result of the optimization.

Returns

resultColorOptimizer.Result

The result.

After optimizing the color conformation using ColorOptimizer.optimize(), the result of the optimization is obtained via ColorOptimizer.get_result().

class ColorOptimizer.Result(alphabet, trajectory, scores)

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='')

Write a color scheme in the Biotite compatible JSON format into a file.

Parameters

filefile-like 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.