Installation

KLASSEZ can be installed from PyPI through:

pip install klassez

Another option is to clone the GitHub repository and install the package with pip directly from the source folder:

git clone https://github.com/MetallerTM/klassez

cd klassez
pip install .

If you do not care about keeping a copy of the package on your hard drive, you can install the latest version of KLASSEZ directly from the GitHub repository in a single command:

pip install git+https://github.com/MetallerTM/klassez.git

Notably, in this way you can also install the dev version:

pip install git+https://github.com/MetallerTM/klassez.git@dev

The required dependencies are sorted out automatically in either case.

There also exist the possibility to install a dedicated environment using the .yml file in the main directory of the GitHub page. It works with either Anaconda/miniconda, and points to the latest stable version of KLASSEZ (i.e. the one in the main branch and on PyPI). You can download the kz_environment.yml file from the GitHub page and install the environment with

conda env create -f kz_environment.yml

The name of the created environment will be kz_<version>, but it can be changed by adding the option -n <new name> to the command. The environment will contain the required packages to make KLASSEZ work, including the GUIs with the qt backend. Remember to activate it in matplotlib by following the instructions in the relative section (A note on matplotlib backends). Note that pyqt6 is already installed by the environment!

A note on matplotlib backends

KLASSEZ employs matplotlib for the GUIs needed to plot the spectra, adjust the phases, etc. In order for this functionality to work properly, it is required to set an appropriate backend able to render such interactive figures.

It is recommended to use either qtagg (faster) or tkagg. Although gtk4agg is a viable option, it is now deprecated and has some problems in the installation. qtagg requires either the package pyqt5 (or pyqt6, not both! Raises conflicts) to work properly. These requirements are not set as mandatory for the installation of KLASSEZ! The user must provide to the installation and to the set of the appropriate backend by themself.

Here follows the instructions on how to set qtagg as backend for rendering figures in matplotlib. The requirements are accessible on PyPI and installable through pip as follows:

pip install pyqt5

or

pip install pyqt6

Then, in a script or in the interactive interpreter, execute the following code:

import matplotlib as mpl

mpl.use('qtagg')

You can check if the backend was successfully loaded with:

>>> print(mpl.rcParams['backend'])
qtagg

As the backend is permanently stored in matplotlib.rcParams['backend'], there is no need to repeat the configuration more than once.

Additional information can be found here.

Import instructions

Initialize the package by writing, at the top of your file:

from klassez import *

This line executes the following code:

#! /usr/bin/env python3

import os
import sys
import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt
from copy import deepcopy
from pprint import pprint
from pathlib import Path

from . import fit, misc, sim, figures, processing, anal, gui

from .Spectra import *

from .config import CM, CM_2D, COLORS, cron, safe_kws, textcolor, _print, cprint

print = cprint

__version__ = "0.2.2.dev0"

This means these can be not imported in your code, as KLASSEZ already does it for you.

An alternative, safer version to prevent overwriting of custom functions is:

import klassez as kz

In this case, additional packages for the main script must be declared explicitely.

Initializing KLASSEZ also grants access to CM and COLORS.

CM is a dictionary of colormaps taken from seaborn and saved in a dictionary whose keys are their names, so that also matplotlib can use them. You can inspect the keys through:

print(CM.keys())

There is a restricted list of colormaps, CM_2D, that should be used for visualizing 2D spectra.

COLORS is:

colors = [ 'tab:blue', 'tab:red', 'tab:green', 'tab:orange', 'tab:cyan', 'tab:purple', 'tab:pink', 'tab:gray', 'tab:brown', 'tab:olive', 'salmon', 'indigo', 'm', 'c', 'g', 'r', 'b', 'k', ]

repeated cyclically ten times and stored as tuple.

Other two “quality of life” variables are figures.figsize_small and figures.figsize_large, which correspond to figure panel sizes of \(3.59 \times 2.56\) inches and \(15 \times 8\) inches, respectively. The former suits well for saving figures of spectra with font sizes of about 10 pt, whereas the latter are best for GUIs and withstand font sizes of about 14 pt.

For NMR: the variable sim.gamma is a dictionary containing the gyromagnetic ratio, in MHz/T, of all the magnetically-active nuclei. For instance:

print(sim.gamma['13C'])
>>> 10.70611

A decorator function called klassez.config.cron() is defined in the top-level script config, and imported by __init__, so that you can use it after writing:

from klassez import cron

This decorator allows to measure the runtime of a function, and print it on standard output once it ended.

The other decorator function present in klassez is klassez.config.safe_kws(). Its purpose is to filter the keyworded arguments passed to the decorated function to keep only the matching ones. This allows to use the same set of keyworded arguments with functions that work in a slightly different manner, and thus have a different signature. This decorator is imported from config as well, therefore it can be accessed after:

from klassez import safe_kws