Package: locscale
LocScale - reference-based local sharpening of cryo-EM mapsLocScaleis an automated program for local sharpening 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 filter. These can be provided either from an existing atomic model, or inferred directly from the experimental density map.New in LocScale 2.1:Hybrid sharpening:LocScalenow supports reference-based sharpening when only partial atomic model information is presentModel-free sharpening:LocScalenow supports reference-based sharpening without the need to supply an atomic modelEMmerNet: a physics-inspired deep convolutional neural network sharpening method.Completely automated process for local map sharpeningFull support for point group symmetry (helical symmetry to follow)LocScaleis distributed as a portable stand-alone installation that includes all the needed libraries from:https://gitlab.tudelft.nl/aj-lab/locscale/releases.Please note that there is a GUI implemented version available as part of theCCP-EMproject; LocScale2 is also implemented inScipion(thanks to Grigory Sharov, MRC-LMB). Note that currently the CCPEM GUI implementations only supports an older version of Locscale (Locscale 1.0, with only model-based sharpening).InstallationWe recommend to useCondafor a local working environment. Seeherefor more information on what Conda flavour may be the right choice for you, andherefor Conda installation instructions.RequirementsLocScale 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.Installation instructions:Quick installation:1. Install REFMAC5 via CCP4/CCPEMLocScale needs a working instance ofREFMAC5. If you already have CCP4/CCPEM installed check if the path to runrefmac5is present in your environment.whichrefmac5If no valid path is returned, please installCCP4to ensure refmac5 is accessible to the program.2. Install LocScale using environment filesThere are two yml files in the repo: environment_cpu.yml and environment_gpu.yml. We recommend you to download and install the GPU version.Once you download the yml file of your choice:condaenvcreate-f/path/to/environment_cpu.yml
condaactivatecpu_locscaleorcondaenvcreate-f/path/to/environment_gpu.yml
condaactivategpu_locscaleAlternativelyYou can also follow these steps to install locscale using pip.1. Create and activate a new conda environmentcondacreate-nlocscalepython=3.8condaactivatelocscale2. Install fortran compilerLocScale uses Fortran code to perform symmetry operations and requires a Fortran compiler to be present in your system. You can installgfortranfrom conda-forge.condainstall-cconda-forgegfortran3. Install REFMAC5 via CCP4/CCPEMLocScale needs a working instance ofREFMAC5. If you already have CCP4/CCPEM installed check if the path to runrefmac5is present in your environment.whichrefmac5If no valid path is returned, please installCCP4to ensure refmac5 is accessible to the program.4. Install LocScale and dependencies using pip:Recommended installationWe recommend using pip for installation. Use pip version 21.3 or later to ensure all packages and their version requirements are met.pipinstalllocscaleInstall development versionIf you would like to install the latest development version of locscale, use the following command to install from the git repository.pipinstallgit+https://gitlab.tudelft.nl/aj-lab/locscale.gitTo install the git repository in editable mode, clone the repository, navigate to thelocscaledirectory, and runpip install -e .5. TestingTo test functionality after installation, you can run LocScale unit tests using the following command:locscaletestHow to useLocScale can generate locally sharpened cryo-EM maps either using model-based sharpening based on available atomic model(s), using model-free sharpening, or using deep neural network-based sharpening method (EMmerNet).1. Run LocScale using an existing atomic model:locscalerun_locscale-empath/to/emmap.mrc-mcpath/to/model.pdb-res3-v-omodel_based_locscale.mrcHere, emmap.mrc should be the unsharpened and unfiltered density map. If you wish to use the two half maps instead, use the following command:locscalerun_locscale-hmpath/to/halfmap1.mrcpath/to/halfmap2.mrc-mcpath/to/model.pdb-res3-v-omodel_based_locscale.mrcThe output will be a locally sharpened map scaled according to the refined atomic B-factor distribution of the supplied atomic model.To speed up computation, you can use multiple CPUs if available. LocScale usesOpenMPI/mpi4pyfor parallelisation, which should have been automatically set up during installation. You can run it as follows:mpirun-np4locscalerun_locscale-empath/to/emmap.mrc-mcpath/to/model.pdb-res3-v-omodel_based_locscale.mrc-mpi2. Run LocScale using a partial atomic model:locscalerun_locscale-empath/to/emmap.mrc-mcpath/to/model.pdb-res3-v-omodel_based_locscale.mrc--complete_modelHere, emmap.mrc should be the unsharpened and unfiltered density map. If you wish to use the two half maps instead, use the following command:locscalerun_locscale-hmpath/to/halfmap1.mrcpath/to/halfmap2.mrc-mcpath/to/model.pdb-res3-v-omodel_based_locscale.mrc--complete_modelSymmetryIf your map has point group symmetry, you need to specify the symmetry to force the pseudomodel generator for produce a symmetrised reference map for scaling. You can do this by specifying the required point group symmetry using the-sym/--symmetryflag, e.g. for D2:locscalerun_locscale-hmpath/to/halfmap1.mrcpath/to/halfmap2.mrc-mcpath/to/model.pdb-res3-v-symD2-omodel_based_locscale.mrc--complete_modelThe output will be a locally sharpened map scaled according to the refined atomic B-factor distribution of the supplied atomic model.To speed up computation, you can use multiple CPUs if available. LocScale usesOpenMPI/mpi4pyfor parallelisation, which should have been automatically set up during installation. You can run it as follows:mpirun-np4locscalerun_locscale-empath/to/emmap.mrc-mcpath/to/model.pdb-res3-v-omodel_based_locscale.mrc--complete_model-mpi3. Run LocScale without atomic model:If no atomic model is available, or if you do not want to use prior model information, you can use the model-free mode ofLocScale. This mode will estimate the molecular volume using statistical thresholding and generate a pseudo-atomic model in the thresholded density map to approximate the distribution of atomic scatterers and estimate the local B-factor. It will then generate an average reference profile for local sharpening based on the experimental data and expected properties for electron scattering of biological macromolecules[2]. Usually all default parameters for pseudomodel and reference profile generation are fine, but you canchangethem if you deem fit.locscalerun_locscale-empath/to/emmap.mrc-res3-v-omodel_free_locscale.mrcSymmetryIf your map has point group symmetry, you need to specify the symmetry to force the pseudomodel generator for produce a symmetrised reference map for scaling. You can do this by specifying the required point group symmetry using the-sym/--symmetryflag, e.g. for D2:locscalerun_locscale-empath/to/emmap.mrc-res3-symD2-v-omodel_free_locscale.mrcLocScale currently supports all common point group symmetries. We are working on supporting helical symmetry, but this is not yet implemented.For faster computation, useOpenMPI:mpirun-np4locscalerun_locscale-empath/to/emmap.mrc-res3-symD2-v-omodel_free_locscale.mrc-mpiFor an exhaustive list of options, use:locscalerun_locscale--helpAlternatively, seeherefor more information. Please note that these pages are still being updated.3. Run LocScale using EMmerNet predictions:Instead of using model-based or model-free reference profiles, LocScale also supports local sharpening based on a physics-inspired deep neural network prediction method using our ensemble networkEMmerNetthat is under development. While we have done our very best to validate the network and mitigate the risk of hallucination, as for any such approach care needs to be exercised to avoid bias. We do encourage its use for model building and visualisation, but recommend to perform model refinement against the original map.locscalerun_emmernet-empath/to/emmap.mrc-v-trained_modelmodel_based-gpus1-oemmernet_model_based.mrcCurrently, three different EMmerNet models are available and can be specified using the-trained_modelflag as follows:ModelSyntaxModel Based EMmerNet-trained_model model_basedModel Free EMmerNet-trained_model model_freeEnsemble EMmerNet-trained_model ensembleAdditional models may become available and will be listed here.For an exhaustive list of options, run:locscalerun_emmernet--helpTutorial and FAQsWe are currently working on the tutorial andWikihelp. If you are still using LocScale 1.0, see theLocScale1-Wiki for usage instructions, FAQs and tutorial.CreditsThis project is using code from a number of third-party open-source projects. Projects used byLocScaleare included under include/:EMmer- Python library for electron microscopy map and model manipulations. License: 3-Clause BSD.FDRthresholding– tool for FDR-based density thresholding. License: 3-Clause BSD.LocScalealso makes use ofRefmac– coordinate refinement program for macromolecular structures. Refmac is distributed as part of CCP-EM.ReferencesIf you foundLocScaleuseful, please consider citing it: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 D2FD00078D (2022)Bugs and questionsFor bug reports please use theGitLab issue tracker.