Copremo Documentation

cam_medium

Copremo : Python package for COlor PREdiction of MOlecules

 

Within the framework of the project Marches Copremo is a free software written in python possessing a GUI. It aims to simulate the absorption and transmittance spectra and ultimately quantify the color of a dye as perceived by the standard human eye. This color quantification is based on the absorption spectrum obtained by experiment or quantum computations.

The color is a perception related to three physiological parameters: the nature of the illuminated object, the light that illuminates the object and the sensor (the eye) that receives the message and communicates it to the brain by means of electrical pulse. The light is generated by an illuminant (e.g. D65 is the standard illuminant corresponding to daylight). It then interacts with the matter/object. The human eye decomposes the received light into three electrical signals to the brain which in turn only, creates the sensation of color.

When light hits an object, three scenarios are possible: it can be absorbed by the object and its energy is transformed into heat; it can go through the object; and it may be reflected by the object. Often these scenarios occur simultaneously. Any object that absorbs a portion of incident visible light (380 nm-800 nm) and reflects the rest is colored. For example, the pigment of green leaves is chlorophyll which absorbs low (blue) and high (red) wavelengths of the visible spectrum, therefore leaves reflect in the mid-wavelengths area (green). Similarly, carrots contain the β-carotene pigment that absorbs wavelengths between violet and green. They reflect what is left meaning the wavelengths ranging from red to green, giving them their characteristic orange color.

The active site of a dye is called a chromophore, it is in this site that electronic excitation occurs: the chromophore absorbs light energy inducing a change in the electronic state going from an electronic ground state to an excited electronic state. To predict the color, it is sufficient to measure or calculate the absorption spectrum of the compound. This spectrum is in fact the light that will be reflected by the object or absorbed by the solution. By taking the inverse of this absorption spectrum (transmittance), it determines the range of wavelengths detected by the eye and can determine the color of the object / the solution. Copremo aims to convert these absorption spectra into transmittance spectrum in order to deduce their color. Absorption spectra can be obtained in three ways:

  • From a measurement given by a spectrophotometer or by web data as a csv file;
  • From the excitation energies obtained using the Gaussian09 software and gathering in a log file;
  • From a computed absorption spectrum virbonically resolved obtained via the FCclasses software located in fort.18 file (data eV). This latter file will be converted to nm before use in Copremo (.fcuv extension).

Each color is characterized by a point in a colorimetric multi-dimensional reference space. There are several color spaces, eg RGB, XYZ, LAB and HTML. Copremo computes these values and provides a color image perceived by the human eye in the presence of daylight.

Copremo description

This package is a free software under the GNU GPL License (see below). Copremo can be used in two different ways:

  1. As software with a graphical interface (GUI) in order to predict the color of a compound from one of the three ways listed above (.csv file, .log and .fcuv).
  2. As a python package to use in your own programs / scripts.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Copremo. If not, see <http://www.gnu.org/licenses/>.

How to cite Copremo

if you use Copremo to get publisheable results, please cite: A.Blondel, Copremo, Université de Nantes, 2015.

Prerequisite

  • Python 2.X ou X > 7
  • Numpy
  • Matplotlib
  • pyhton-setuptools
  • python-pip

Copremo employs two librariesunder LGPL licence: Colorpy [3] et cclib [4].

  • colorpy [3] est furnished with Copremo
  • cclib [4] will be automatically installed with setuptools.

Copremo is working on Apple operating systems, on several Linux distribution (fedora, Ubuntu, opensuse) but on Windows 7 (not yet validated interface).

Download

* GitLab repository of Copremo

Installation

tar -xvz Copremo-1.3.tar.gz
python setup.py install

If you are notified that numpy or matplotlib cannot be loaded, it means that you simply forget to install them.
Uner a python-pip environement you can rapidly install them :

pip install numpy
pip install matplotlib

Re-do the previous installation step that should autoamtically install cclib [4] if not present and then install Copemo.

Launch the software

 python Copremo
./Copremo

Copremo GUI shows up.

How to predict color from a Gaussian computation

The five-step procedure described below has been used previously in Ref. [1] Considering the dye/pigment of your choice, follow the five steps to vizualize the color to the human eye your molecule:

  1. Calculate the transition energies with Gaussian09.
  2. Create the absorption spectrum by interpolating data from Gaussian09 the help of the class spectrum of the Copremo Package.
  3. Inverse the spectrum to get the transmittance spectrum.
  4. Estimate the color (XYZ, RGB or LAB values) associated to your molecule using the Color class of the Copremo package which uses the Colorpy library [3]
  5. Visualize the color code of the molecule in hexadecimal within the GUI Copremo.

The Copremo software has many other options which are explained below using different validation tests.

Validations

Objective 1:

  • Diluate your dye in a solution and visualize (take a picture) the color of your solution (A)
  • Perform a spectrophotometric measurement of your diluted compound (B) and extract the data (.csv format). Use Copremo to transform this csv file in order to generate within Corpremo approximation the hexdecimal color value. Compare this value with the color of A.
  • Realize a electronic transition calculation (cf follow the above protcol), generate the theoretical absorption spectrum (C). Compare the preceived color (A) with B and the predicted color (C) from a theoretical method.

Validation 1 :

Four dyes synthesized in the laboratory CEISAM were used for the validation of Copremo.

A.
These molecules were placed in a UV spectrometer/Visible Shimadzu UV-2501PC using dichloromethane as solvent and taking readings in the visible region of every 0.5 nm. The data were exported in ASCII format and then converted to .csv format.

.csv files and associated pictures (A) of this validation are in the directory ‘test / verif1’. The color of each dye predicted using the .csv file and Copremo interface are in ‘test/verif1/test_result/’. The generated png files were made with the the Color class (see below).

Validation tables

 

validation tables
Molecule Picture of the molecule (A) Copremo color prediction(B) Flurorescence
EA1022_chemdraw ea1022 ea1022.csvtransmittance_color Yes Red
bleu_chemdraw lebleu lebleu.csvtransmittance_color No
violet_chemdraw violet violet.csvtransmittance_color No
P1_chemdraw dilution*1 p1-1 p1-1.csvtransmittance_color No
P1_chemdrawdilution*2.2 p1-3 p1-3.csvtransmittance_color No
P1_chemdraw dilution*4 p1-4 p1-4.csvtransmittance_color No

Objective 2 :

  • Recover the experimental transmittance spectrum of Ref. [2] using WebPlotDigitizer for each molecule and create a .csv file that is readable by Copremo.
  • Compare the results of colors perceived by the human eye when the molecules are in solution (see Table 1 in Ref. [2]) to the Copremo predictions.

Validation 2 : Compare Copremo to a similar approach (see Ref. [2]) which has been valiated with four solutions test and water. This aims to validate Copremo colorimetric analysis method. We recovered the transmittance spectra of these colored solutions to estimate whether the perceived colors estimated by Copremo were comparable to the one of Ref. [3].

Useful .csv files of this validation test are in the ‘test/directory verif2’

Be cautious that .csv files contain normalized transmittance spectra. For Copremo, open this .csv file (Files → Open), an absorption spectrum apparears. There is then no need to invert it into a transmittance spectrum and no need to standardize it since it already done.

Copremo allows to find the colors from the experimental transmittance spectrum.

Validation tables

This table compares RGB values predicted by Ref. [2] and the color predicted by Copremo from the same experimental data (transmittance spectra).

validation tables
Molecule Couleur RGB approximé Ref 2 * Couleur RGB approximé Copremo
1M CoCl2 cocl2 1mcocl2.csvtransmittance_color
1M NiCl2 nicl2 nicl2.csvtransmittance_color
1M CuSO4 cuso4 lebleu.csvtransmittance_color
0.0005M KMnO4 kmno4 kmno4.csvtransmittance_color

* Colors are available on http://www.easyrgb.com/index.php?X=CALC#Result website obtained from the Ref.[2] value.

GUICopremo

copremo_guiThe graphical interface of Copremo is based on Copremo API

 

 

 

 

Initial and default values

The ini file (in ini folder) gathers the intitial parameters. The following parameters might be changed by the user:

 

Default parameters
Parameters Default values Comments
color_display absorbance absorbance or transmittance
normalized True Sprectrum normalization True ou Flase
concentration 1 Relative concentration (slider between 0 and 1)
space XYZ Chromoticity space (possible values: RGB, RGB24, Hexa, LAB, xyY)
energytype eV Unity of work of elargment nm/ev
scaling_energy -1. Scaling factor for energies < 0 unscaled
scaling_intensity -1. Initial value for intensities < 0 unscaled
fstart 0.5 Initial value to compute the spectrum (0.5 eV)
fend 5. Final point to compute the spectrum (0.5 eV)
fstep 0.01 Not for spectrum calculation
gamma 0.60 Full Width at Half Maximum (FWHM)
gmix 100 Gaussienne/lorentzienne mix: 100=100%G, 0=100%L

 

Input files

  • .csv : La première ligne du fichier csv n’est pas prise en compte. Ensuite deux colonnes de valeurs séparées par un « ; ». La première colonne correspond à la longueur d’onde en nm. La seconde correspond à l’intensité à cette longueur d’onde.
  • .log: Copremo permet d’utiliser comme entrée un fichier Gaussian09 et le traiter afin d’extraire les données permettant de réaliser les spectres nécessaires pour l’approximation de la couleur de la molécule. Ce fichier .log doit contenir les résultats d’un calcul d’energie d’excitation (CIS, TD-DFT,…).
  • .uv : Fichier réalisable à l’aide d’une fonction de la classe Spectral à partir d’un fichier Gaussian09. Ensuite deux colonnes de valeurs séparées par un « ; ». La première colonne correspond à la longueur d’onde en nm. La deuxième colonne correspond à l’énergie d’éxcitation et la troisième à l’intensité à cette longueur d’onde.
  • .fcuv: Copremo peut également lire les fichiers issus de FCclasses (cf ci-dessous) après conversion des nm en eV,on nommera ce fichier .fcuv.

summary of Copremo Gui utilities

 

To obtain the absorbance spectra (default) or transmittance spectrum (Files → Options, check box Tranmittance)
File Absorbance spectra Transmittance spectra
LEBLEU.csv copremo_abso copremo_trans Valeur B4

 

To normalize spectra (Files → Options, box Normalized).
File Transmittance spectra Normalized transmittance spectra
LEBLEU.csv copremo_trans_not_normalized copremo_trans
To change full width at half maximum (FWHM) of spectrum (only Gaussian input files).
File Absorption spectra FWHM 0.6 Absorption spectra FWHM 0.2
Bleu-lr.log copremo_abso_fwhm06 copremo_abso_fwhm02
To change the illuminant (Files → Options, other illuminants, D65 is the default illuminant).
File D65 illuminant A illuminant
H2O.csv d65_h20 a_h2o
To vary the concentration in a arbitrtory manner for a normalized spectrum (Files → Options, slider).
File Concentration 1.0 Concentration 0.7
LEBLEU.csv copremo_trans_color copremo_conc07
To get XY coordinates of the colorwithin the chromaticity diagram (bottom left corner)
File Colometric diagram at file opening event Colometric diagram after 2 manipulations
NiCl2.csv diag_abs diag_abs1

Note that the “dot” appears red of black according to the choice of using the absorbance or transmittance data, respectively, and the outputs are presented in the botomm right corner of the window.

To furnish the HTML color value et l’afficher and showing it up into the rectange (top corner).
File Concentration 1.0
LeBLEU.csv copremo_trans_color
To obtain various colorvalues depending of the chromaticity space (Files → Options, other spaces, default RGB).
File XYZ RGB24
LEBLEU.csv copremo_trans_xyz copremo_trans_rgb24

Copremo API

Copremo includes an API (Application Programming Interface) containing two classes Color and Spectral.

Test of Color class

  • Test 1 :use Color.py in command line to obtain the hexadecimal value corresponding tp the color of the studied dye, for instance CuSO4 (vérif2).
  • Test 2 : use test_color.py to create .png file with the color predictiopn from .csv file de test/verif1
 python test_Color.py all
  • Test 1 :use Color.py in command line to obtain the hexadecimal value corresponding tp the color of the studied dye, for instance CuSO4 (vérif2).
 python Color.py -i ../../test/verif2/CuSO4.csv -s Hexa

Classe Color docs

Test of Spectral class

  • Test 1 : use Spectral.py in command line to obtain the spectrum of Color.log file (verif4) in the .uv (Color.log.uv) format. Then just open GUI.
python Spectral.py -i ../../test/verif4/color.log -a
  • Test 2 : use test_spectral.py to get .uv files corresponding to .log file of test/verif4
python test_Spectral.py all

Documentation of Spectral class

Classe Spectral Doc

References

  • [1] :Beck, M. E. (2005), Estimation of physiologically perceived color from TDDFT-derived excitation spectra. Int. J. Quantum Chem., 101: 683–689. doi: 10.1002/qua.20326
  • [2]: Beyond λ[lambda]max: Transforming Visible Spectra into 24-Bit Color Values Darren L. Williams, Thomas J. Flaherty, Casie L. Jupe, Stephanie A. Coleman, Kara A. Marquez, and Jamie J. Stanton Journal of Chemical Education 2007 84 (11), 1873
  • [3]: M. Kness, “ColorPy-A Python package for handling physical descriptions of color and light spectra,” MarkKness.net, accessed on 08/06/2013 at http://markkness.net/colorpy/ColorPy.htm
  • [4]: O’boyle, N. M., Tenderholt, A. L. and Langner, K. M. (2008), cclib: A library for package-independent computational chemistry algorithms. J. Comput. Chem., 29: 839–845. doi: 10.1002/jcc.20823

Comments are closed.