locscale 2.3.1.post2

Contrast optimization for cryo-EM maps

LocScale-2.0

LocScale-2.0 is an automated map optimisation program performing physics-informed local sharpening and/or density modification of cryo-EM maps with the aim to improve their interpretability. It utilises general properties inherent to electron scattering from biological macromolecules to restrain the sharpening and/or optimisation filter. These can be inferred directly from the experimental density map, or - in legacy mode – provided from an existing atomic model.

What's new in LocScale-2.0?

• Completely automated process for map optimisation
• Feature-enhanced maps: Confidence-weighted map optimisation by variational inference.
• Hybrid sharpening: Reference-based local sharpening with partial (incomplete) models.
• Model-free sharpening: Reference-based local sharpening without atomic models.
• LocScale-SURFER: ChimeraX plugin to toggle contextual structure in LocScale maps.
• Full support for point group symmetry (helical symmetry to follow).

Documentation

[!IMPORTANT] Please visit https://cryotud.github.io/locscale/ for comprehensive documentation, tutorials and troubleshooting.

Installation

We recommend to use Conda for a local working environment. See here for more information on what Conda flavour may be the right choice for you, and here for Conda installation instructions.

[!NOTE] LocScale should run on any CPU system with Linux, OS X or Windows subsytem for Linux (WSL). To run LocScale efficiently in EMmerNet mode requires the availability of a GPU; it is possible to run it on CPUs but computation will be slow(er).

Quick installation

We recommend to use Conda for a local working environment. See here for more information on what Conda flavour may be the right choice for you, and here for Conda installation instructions.

1. Install LocScale-2.0 using environment files

Download environment.yml to your local computer, navigate to the location you wish to install Locscale-2.0 at and run the following:

conda env create -f /path/to/environment.yml
conda activate locscale2

2. Install REFMAC5 via CCP4/CCPEM

LocScale needs a working instance of REFMAC5. If you already have CCP4/CCPEM installed check if the path to run refmac5 is present in your environment.

which refmac5

If no valid path is returned, please install CCP4 to ensure refmac5 is accessible to the program.

Step-by-step instructions

1. Create and activate a new conda environment

conda create -n locscale python=3.11
conda activate locscale

2. Install parallelisation support and Fortran compiler

LocScale uses Fortran code to perform symmetry operations and requires a Fortran compiler to be present in your system. You can install gfortran, mpi4py and openmpi from conda-forge.

conda install -c conda-forge gfortran mpi4py openmpi

3. Install REFMAC5 via CCP4/CCPEM

The model-based and hybrid map sharpening modes of LocScale need a working instance of REFMAC5. If you already have CCP4/CCPEM installed check if the path to run refmac5 is present in your environment. For model-free sharpening and confidence-aware density modification REFMAC5 is not required.

which refmac5

If no valid path is returned, please install CCP4 to ensure REFMAC5 is accessible to the program.

4. Install LocScale and dependencies using pip:

We recommend using pip for installation. Use pip version 21.3 or later to ensure all packages and their version requirements are met.

pip install locscale 

[!NOTE]

Install development version:

If you would like to install the latest development version of locscale, use the following command to install from the git repository.

pip install git+https://github.com/cryoTUD/locscale.git

To install the git repository in editable mode, clone the repository, navigate to the locscale directory, and run pip install -e .

5. Testing

To test functionality after installation, you can run LocScale unit tests using the following command:

locscale test

ColabScale

[!TIP] For quick testing or if you have limited compute resources, many functionalities of LocScale-2.0 are available on ColabScale.

Credits

LoScale 2.0 is facilitated by a number of open-source projects.

• EMmer: Python library for electron microscopy map and model manipulations. [3-Clause BSD license]
• FDRthresholding: Tool for FDR-based density thresholding. [3-Clause BSD license]
• EMDA: Electron Microscopy Data Analytical Toolkit. [MPL2.0 license]
• Servalcat: Structure refinement and validation for crystallography and SPA. [MPL2.0 license]
• mrcfile: MRC file I/O. [3-Clause BSD license]

LocScale also makes use of REFMAC5. REFMAC is distributed as part of CCP-EM.

References

If you found LocScale useful for your research, please consider citing it:

• A. Bharadwaj, R.M. de Bruin, A.J. Jakobi: Confidence-guided cryo-EM map optimisation with LocScale-2.0, BioRxiv 2025.09.11.674726 (2025)
• A.J. Jakobi, M. Wilmanns and C. Sachse: Model-based local density sharpening of cryo-EM maps, eLife 6: e27131 (2017).
• A. Bharadwaj and A.J. Jakobi: Electron scattering properties and their use in cryo-EM map sharpening, Faraday Discussions 240, 168-183 (2022)

---

Bugs and questions

For bug reports please use the GitHub issue tracker.