labellib 1!1.0.0

Python bindings for LabelLib - Library for coarse-grained simulations of probes flexibly coupled to biomolecules

LabelLib

General description

LabelLib is a low-level C++ library for the simulation of small probes flexibly coupled to biomolecules for the development of higher-level applications and libraries. LabelLib can calculate the distribution of flexible labels around attachment points. Such probes are for instance dyes for fluorescence spectroscopy, spin-labels for EPR and NMR, or chemical cross-links for mass-spectrometry. Typically, these labels are fluorescent dyes. For such dyes LabelLib can calculate FRET observables.

LabelLib uses a coarse-grained approach to simulate the spatial distribution of probes around their attachment point. In this coarse-grained approach, LabelLib determines the sterically accessible volume of the probe considering the linker length and the spatial dimensions of the probe. The linker connecting the probe to the biomolecule and the probe are approximated by a tube and soft sphere, respectively. Details are provided in the publications .

LabelLib is a library for programmers and provides APIs for C/C++ and Python. Furthermore, LabelLib can be integrated into PyMOL installations as described below. This allows to visualize the distributions of molecular probes.

Relation of other software and libraries

LabelLib serves as core low-level library for the software Olga and the higher-level Python library AvTraj. The deprecated software FPS is independent of LabelLib.

Olga is a software dedicated towards experimentalists. Olga provides a graphical user interface for the calculation of accessible volumes (AVs), screen a set of structural models against experimental observables, rigid-body docking, and the optimal design of new FRET experiments.

Labelizer is a web application for accessible-volume and labeling workflows, including FRET-oriented setup and analysis built on top of the LabelLib ecosystem. Labelizer paper: Nature Communications (2025)

AvTraj AvTraj is a Python library for the calculation of accessible volumes (AVs), screening. AvTraj facilitates the development of new analytical approaches for FRET-based structural models. Avtraj facilitates processing of MD-simulations and the development of Python scripts handling FRET-based structural models.

IMP is a framework for integrative structural modeling that combines multiple experimental restraints.

IMP.bff is IMP's Bayesian Fluorescence Framework. It extends IMP with fluorescence/FRET functionality, including Accessible Volume (AV) calculations and FRET restraints that can be combined with other restraints in integrative modeling workflows. Documentation: docs.peulen.xyz/bff IMP.bff preprint: bioRxiv (2023)

FPS is a software with a graphical user interface for the FRET-based structural modeling. FPS can calculate accessible volumes (AVs), screen a set of structural models against experimental observables, and can generate new structural models by rigid-body docking using experimental FRET data.

Building and installation

C++ shared library

C++ shared library can be installed from source with cmake:

git clone --recursive https://github.com/Fluorescence-Tools/LabelLib.git
mkdir LabelLib/build
cd LabelLib/build
cmake ..
sudo make install

If you build from a source archive without git submodules (for example GitHub/Zenodo tarballs), install Eigen3 and pybind11 in your build environment first. On Linux you can build and install a package instead (prefered):

...
cmake .. && make package
sudo dpkg -i FlexLabel-*-Linux.deb

Python bindings

Python bindings can be be either installed via pip or conda. Installation of the C++ library is not necessary for this. The python binding can be installed via pip using the following command:

sudo pip install LabelLib

The python bindings can be installed via conda using the following command:

conda install -c tpeulen labellib

Usage

Pymol

To access the functionality of LabelLib in PyMOL two basic prerequisites need to be fulfilled:

1. LabelLib needs to be installed in the Python installation used by PyMOL
2. The file LabelLib_pymol.py needs to be downloaded and executed from PyMOL's command line interace.

These two prerequisite can be fulfiled manually, by copying LabelLib into your PyMOL installation folder or by installing both, PyMol and LabelLib in the same conda environment using precompiled distributions for both.

conda install -c tpeulen labellib
conda install -c schrodinger pymol

Using a PyMol installation that has access to a LabelLib installation, the PyMol script file "LabelLib_pymol.py" is executed from PyMOL's command line interface by entering "run LabelLib_pymol.py". Once, "LabelLib_pymol.py" is executed Accessible Volumes(AV) can be simulated from PyMOL's command line. The procedure of running "LabelLib_pymol.py" and simulating an AV is shown below for an example:

cmd.do('run ./LabelLib/FlexLabel/python/LabelLib_pymol.py')
cmd.fetch('1BNA', async=0)
genAV('1BNA', '/1BNA/B/B/19/C5', allowed_sphere_radius=1.5)

As a result you should see something like this:

More extended examples of genAV() usage can be found in LabelLib_pymol.py.

C++

C++ usage example can be found in testFlexLabel.cxx. Your own software could be compiled like this:

cd LabelLib/FlexLabel/test
g++ -std=c++14 -O3 -o FlexLabelTest testFlexLabel.cxx -lFlexLabel
./FlexLabelTest

Possible output:

AV calculation took: 20.783 ms

Python

The LabelLib can be used from python as shown below in a code example. LabelLib requires the Cartesian-coordinates, xyz, and van der Waals radii, vdW, of the biomolecule the label is attached to. The Cartesian coordinates and the vdW radii are passed to LabelLib as a single array (see example below). The array-oriented API uses an _arr suffix and validates input shapes for NumPy users:

• atomsXyzr: (4, N) or (N, 4)
• sourceXyz: (3,), (1, 3), or (3, 1)
• xyzRQ: (5, N) or (N, 5)

import LabelLib as ll
import numpy as np

atoms_nx4 = np.zeros((11, 4), dtype=np.float32)  # [x, y, z, r] rows

linker_length = 20.0
linker_width = 2.0
dye_radius = 3.5
simulation_grid_spacing = 0.9
dye_attachment_point = np.zeros(3)
av1 = ll.dyeDensityAV1_arr(
    atoms_nx4,
    dye_attachment_point,
    linker_length,
    linker_width,
    dye_radius,
    simulation_grid_spacing,
)

# The object av1 has the property grid, which stores
# the dye densities within the reach of the dye linker as a positive number. 
# For points out of out reach of the linker, the the 
# grid contains negative numbers.
grid = av1.grid_arr()

# The shape of the grid is defined by the property '.shape'
shape = av1.shape_arr()

# The 3D grid is a flat 1D python list in 'Fortran' order
grid3d = np.array(grid).reshape(shape, order='F')

Another usage example is available in usage.py

Citation

If you have used LabelLib in a scientific publication, we would appreciate citations to the following paper:

Dimura, M., Peulen, T.O., Hanke, C.A., Prakash, A., Gohlke, H. and Seidel, C.A., 2016. Quantitative FRET studies and integrative modeling unravel the structure and dynamics of biomolecular systems. Current opinion in structural biology, 40, pp.163-185.

Additional information is available in FPS toolkit paper:

Kalinin, S., Peulen, T., Sindbert, S., Rothwell, P.J., Berger, S., Restle, T., Goody, R.S., Gohlke, H. and Seidel, C.A., 2012. A toolkit and benchmark study for FRET-restrained high-precision structural modeling. Nature methods, 9(12), pp.1218-1225.

Related software papers:

• Labelizer: Nature Communications (2025)
• IMP.bff preprint: bioRxiv (2023)