Package: colour-of-molecule
Contents:InstallationPrerequisitiesPackage installationUpdating the packageUninstallationUsageImporting template scriptsAlternative way of importing template scriptsArchive a new script inside the package folderRunning the scriptsCode structure and commandsclass Fileclass FontSettingsPlotting functionsGeneral keyword argumentsFunction-specific keyword argumentsExample outputsExample 1Example 2InstallationPrerequisitiesTo be able to install and use the packagecolour_of_molecule, Python language (version >= 3.6) needs to be installed on your computer.You can check the installation by passingpythonorpython3to the console. If Python distribution is ready to be used, you will enter the Python console:Python 3.9.7 (tags/v3.9.7:1016ef3, Aug 30 2021, 20:19:38) [MSC v.1929 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> |Any time you would like to close the Python console and return to the standard console, call:quit()Besides, you will need to have installed apippackage manager.
It can be installed by the following command:python -m install pipPackage installationThe package, along with all necessary dependencies, can be installed by the following command:pip install colour-of-moleculeThe installation can be checked by calling:pythonand then trying to import the package:import colour_of_moleculeYou can again leave the Python console by callingquit()if no error has occurred.Updating the packageYou can upgrade the package to the current version by:pip install colour-of-molecule --upgradeor alternatively by a shorter command:pip install colour-of-molecule -UIf you wish to install a specific version, the command might look like this:pip install colour-of-molecule==0.0.2.dev3UninstallationThe package can be completely removed from your machine by following command:pip uninstall colour-of-moleculeUsageImporting template scriptsThe package contains several preset template scripts which can be copied to current folder at any time by following commands.Initialize Python console:pythonThen import the templates:import colour_of_molecule.templatesAn interactive menu should appear:>>> import colour_of_molecule.templates
? What category of templates are you interested in? (use arrows to navigate)
 > Colours_and_plotting
 > Multiple_files_manipulation
 ... custom folders ...
 --exitFollow the instructions and select the desired .py script by using arrows and enter keys. You will be asked to confirm the creation of the selected .py script in the directory the console was navigated into. For example if the Python console was invoked inC:\Users\Joefolder and the scriptplot_spectrum.pywas selected, the confirmation might look like this:INFO:   File "plot_spectrum.py" will be copied
        > from "C:\Users\Joe\miniconda3\envs\env-01\lib\site-packages\colour_of_molecule\templates\plot_spectrum.py"
        > to "C:\Users\Joe\plot_spectrum.py"

Press Enter to proceed.
|The saving process contains failsafe against possible file overwrite. You will be asked to enter a new script filename or to confirm the ovewrite if any filename collision was found.Alternative way of importing template scriptsIf your console doesn’t support interactive prompt provided byInquirerPyPython package (sectionImporting template scripts), an alternative menu might be displayed:>>> import colour_of_molecule.templates
Select a template you wish to import:
> Multiple_files_manipulation
    0  >  analyze_multiple_files.py
> Colours_and_plotting
    1  >  find_colour.py
    2  >  plot_spectrum.py
Then run a function "colour_of_molecule.templates.create(#)" where # is the index of selected file to copy it into current directory.

>>> |Follow the listed instructions and create the desired script by calling, for example (#=1):colour_of_molecule.templates.create(1)Archive a new script inside the package folderIf you want to make your script easily accessible by the template script importing mechanism listed above, you can archive your own custom script inside the package folder along with the template ones. Pleasekeep in mind that thecolour_of_moleculepackage update might remove or overwrite these archived custom scriptsso please store them somewhere else as well to keep them safe in a longterm perspective.The scripts can be distributed into “virtual” folders or categories that will be displayed during the script import process to keep it organized. The folder assignment is done in the first line of the script itself by a following text:### category: folder-nameTo add the custom scipt to the templates folder, within the package, navigate to the folder your custom script is currently stored. Then use the following command similar to the one normally used to run the script itself but with the--savekeyword added to the command instead of the input file path. For example it might look like followlingly:python plot_spectrum2.py --saveYou will be asked to confirm the archiving or to enter a new filename if the current is already used in the templates folder.Running the scriptsThere are multiple ways how the scripts can be used. You can either specify the input file path in the script itself, for example into a variable calledinput_file:importcolour_of_moleculeascom# importing the packageinput_file="C:/..."# specifying the input file pathfile=com.file_in(input_file)# loading the input fileThe script would be then run by a simple command:python my_script.pyAlternatively, you can also pass the input file path straight from the command line, for example:python my_script.py ./gaussian/asp-B3LYP-pVDZ.logIt’s important to mention that this way of passing the input file path as an in-line argument is possible if and only if the script contains appropriate piece of code which enables it:importsys# importing python built-in packageiflen(sys.argv)>1:# checks the number of arguments passed to python (0 - script, 1 - input file path)path=sys.argv[1]# sets the variable path to the input file path (argument with index 1)else:path=input_file# if only one argument was passed (i.e. only the script), use the in-file specified path (see the beginning of this docs section)Code structure and commandsAll settings related to numerical parameters or analysis enters the process via the classFile. Setting related to fonts are managed by classFontSettings.class FileThe first step every script has to contain is the command to load the input file. This is done byfile_in()function directly accessible directly from the package directly. It takes a single argument - path to the input file. For example:importcolour_of_moleculeascomfile=com.file_in(PATH)Currently, output formats of four QCh programs are supported:Gaussian,ORCA,MNDO, andMOLPRO. The format will be recognised automatically during the loading process.Any settings are now passed to thefileobject (an instance ofFileclass) as attributes:file.XwhereXcan be:o.wavelength_rangewavelength range to be plottede.g.:file.wavelength_range = (250,850)o.standard_deviationsets the width of gaussian peaks used to create absorption spectrume.g.:file.standard_deviation = 3096.01(default value)o.optical_densitysets the optical density used to calculate the complementary absorption spectrum needed to determine the actual coloure.g.:file.optical_density = 0.15(default value)o.transition_minimal_amplitudesets the minimal transition amplitude which will be included in the plot of absorption linese.g.:file.transition_minimal_amplitude = 0.5(default value)o.normalize_absorption_spectrumdetermine if the absorption spectrum should be normalized to 1 at maximum valuee.g.:file.normalize_absorption_spectrum = False(default value)o.normalize_complementary_spectrumdetermine if the complementary absorption spectrum should be normalizede.g.:file.normalize_complementary_spectrum = True(default value)Setting related to plotting:o.plot_titlesets custom title to the plots, string needs to be enquotede.g.:file.plot_title = ""(default value)o.legend_titlesets custom title to the legend, string needs to be enquotede.g.:file.legend_title = ""(default value)class FontSettingsAll settings related to fonts used and displayed in the plots are managed by theFontSettingsclass. To begin with, the class needs to be imported:fromcolour_of_molecule.classes.classesimportFontSettingsAfter that, the class can be instatiated while taking up to two keyword arguments:newfonts,newsizes; and a single boolean keyword argumentuse_all.
Both keyword arguments has to be dictionaries and the can specify font or font size for these keys:oallit is used for all text ifuse_all = Trueotitletitle of the plotoaxisx and y axis labelsoaxis_tick_labelsx and y axis tick labels (i.e. numbers adjacent to axis ticks)olegendtitle of the legend and the whole legend itselfThe default font isCalibriand the default font size is14for plot title and12for everything else.The final usage might look like this:font_settings=FontSettings(newfonts={'all':'Consolas'},newsizes={'title':11,'legend':8},use_all=True)The instance can be then passed to any of the plotting functions, for example:com.plot_single_spectrum(file,fonts=font_settings)Plotting functionsThere are currently three functions capable of returning an image of a plot:oplot_single_spectrum()oplot_abs_lines()oget_colour()Each of these functions takes a single positional argument - an instance of classFile- and various keyword arguments.The keyword arguments can be categorised into two groups -generalandfunction-specific.General keyword argumentsosavesets the path where to save the output imagee.g.:com.plot_single_spectrum(file,save="C:/...")otitletitle of the plot displayed in its headere.g.:com.plot_single_spectrum(file,title="Example1")to hide the title use expressiontitle=None(please note that in case of axis labels the preferred way is to use null string""instead)oxaxis_labellabel for the x-axis displayed below the plote.g.:com.plot_single_spectrum(file,xaxis_label="wavelength[nm]")(default value)oyaxis_labellabel for the y-axis displayed on the left side of the plote.g.:com.plot_single_spectrum(file,xaxis_label="wavelength[nm]")(default value)oyaxis_labellabel for the y-axis displayed on the left side of the plote.g.:com.plot_single_spectrum(file,yaxis_label="relativeabsorbance")oyaxis_label_rightlabel for the right y-axis displayed on the right side of the plote.g.:com.plot_single_spectrum(file,yaxis_label_right="oscillatorstrength")osizetuple, diameters of the plot expressed by a tuple of values, i.e.(width, height)e.g.:com.plot_single_spectrum(file,size=(6,4),)odpiresolution of the generated image (dots per inch)e.g.:com.plot_single_spectrum(file, dpi=400)(default value)ofonts… already mentioned aboveFunction-specific keyword argumentscom.plot_single_spectrum():olines_showboolean, True if absorption lines should be plotted below the spectrum, False if note.g.:com.plot_single_spectrum(file, lines_show=True)(default value)olines_ratiotuple, sets the relative height of the main plot area (where spectrum is plotted) and the supportive stripe with positions of abs. linese.g.:com.plot_single_spectrum(file,lines_ratio=(14,1),)(default value)olines_coloursboolean, True if absorption lines with oscillator strength larger thanlines_limshould be coloured according to their corresponding wavelength, otherwise they will be coloured blacke.g.:com.plot_single_spectrum(file, lines_colours=True)(default value)olines_limfloat, limiting value of oscillator strength separating so-called dark and bright transitionse.g.:com.plot_single_spectrum(file, lines_lim=0.0001)(default value)olines_widthfloat, width of plotted abs. lines in pts.e.g.:com.plot_single_spectrum(file, lines_width=1.2)(default value)orainbowboolean, True if a colour spectrum should be displayed below the line of plotted abs. spectrum linee.g.:com.plot_single_spectrum(file, rainbow=True)(default value)Example outputsExample 1file=com.file_in("C:/Users/xyz/carotenoid.out")file.wavelength_range=(100,1000)com.plot_single_spectrum(file,save="C:/Users/xyz/exp1.png",dpi=200,size=(10,3),title="Example1",xaxis_label="wavelength [nanometers]",yaxis_label="rel. abs.",lines_show=False,)Example 2file=com.file_in("C:/Users/xyz/phenolphtalein.log")file.wavelength_range=(200,700)com.plot_single_spectrum(file,save="C:/Users/xyz/exp2.png",dpi=200,size=(10,3),title=None,xaxis_label="wavelength [nm]",yaxis_label="relative absorbance",lines_show=True,lines_colours=True,lines_lim=0.001,lines_ratio=(12,2),lines_width=1.8,)