density-fitness(1)

💖 density-fitness(1) 💖

okay bestie, listen up — this is the User Commands girlie density-fitness, and she's here to tell you exactly how good your electron density looks. no cap.

---

✨ NAME ✨

density-fitness — calculates per-residue electron density scores: real-space R, real-space correlation coefficient, EDIAm, and OPIA. literally the whole glow-up report card for your structure 🔥

---

🌸 SYNOPSIS 🌸

density-fitness [OPTION] <mtz-file> <coordinates-file> [output]

density-fitness [OPTION] --hklin=<mtz-file> --xyzin=<coordinates-file>
[--output=<output>]

density-fitness [OPTION] --fomap=<fo-map-file> --dfmap=<df-map-file>
--reslo=<low-resolution> --reshi=<high-resolution> --xyzin=<input
[--output=<output>]

(yes the third one ends in --xyzin=<input with no closing bracket, that's just how she is, don't @ me, we keep it verbatim 🫶)

---

🦋 DESCRIPTION 🦋

So density-fitness calculates electron density metrics — for main-chain atoms (and yes, that includes the Cβ atom 💅) and for side-chain atoms, of individual residues. per-residue. every single one gets its vibe check.

For this calculation, the program uses the structure model in either PDB or mmCIF format, plus the electron density from the 2mFo-DFc and mFo-DFc maps. If those maps aren't readily available, no stress — you can use the MTZ file and model to calculate the maps with clipper. And it's not picky: density-fitness supports both X-ray and electron diffraction data. versatile queen 👑

Real talk though: this program is essentially a reimplementation of edstats, which is a program available from the CCP4 suite. BUT. The output now contains only the RSR, SRSR and RSCC fields like in edstats, with the addition of EDIAm and OPIA — and it no longer requires pre-calculated map coefficients. so much easier, we love an upgrade ✨

---

💜 the metrics, explained (sort of, they're formulas bestie)

The real-space R factor (RSR) is defined (Brändén & Jones, 1990; Jones et al., 1991) as:

RSR = Σ |ρobs - ρcalc| / Σ |ρobs + ρcalc|

The SRSR is the estimated sigma for RSR.

The real-space correlation coefficient (RSCC) is defined as:

RSCC = cov(ρobs,ρcalc) / sqrt(var(ρobs) var(ρcalc))

where cov(.,.) and var(.) are the sample covariance and variance
(i.e. calculated with respect to the sample means of ρobs and
ρcalc).

The EDIAm score is a per-residue score based on the atomic EDIA value, and the OPIA score gives the percentage of atoms in the residue with EDIA score is above 0.8. iconic behavior fr fr.

---

🎀 OPTIONS 🎀

okay so housekeeping first, the important logistics:

• When using MTZ files, the input and output files do not need the option flag. If no output file is given, the result is printed to stdout.
• When using map files, the resolution must be specified using the reshi and reslo options.

now the menu, mwah 💅

• --xyzin — the coordinates file, in either PDB or mmCIF format. This file may be compressed with gzip. Also covers --fomap and --dfmap: the 2mFo-DFc and mFo-DFc map files respectively. Both are required, and if these are specified, the resolution must also be specified. (they come as a trio, they're a package deal 🫶)
• --reslo and --reshi — the low and high resolution for the specified map files.
• --hklin — the MTZ file. If this option is specified, the maps will be calculated using the information in this file.
• --sampling-rate — the sampling rate to use when creating maps. Default is 1.5.
• --recalc — by default the maps are read from the MTZ file, but you can also opt to recalculate the maps. use this e.g. when the structure no longer corresponds to the structure used to calculate the maps in the MTZ file. (glow-up era, recalculation era 💅)
• --aniso-scaling — accepted values for this option are observed and calculated, or none. Used when recalculating maps.
• --no-bulk — when specified, a bulk solvent mask is not used in recalculating the maps.
• --components (or --compounds) — specify the path of the CCD file components.cif. By default the one installed by libcifpp is used; use this option to override this default.
• --extra-compounds — a file containing information for residues in this specific target. This file may be in either CCD or CCP4 monomer library format.
• --mmcif-dictionary — specify the path to the mmcif pdbx dictionary file. The default is to use the dictionary installed by libcifpp; use this option to override this default.
• --no-validate — omit the validation of the input mmCIF file. This will force output even in case the input file contains errors. ⚠️ chaos mode, proceed with intention.
• --electron-scattering — use electron scattering factors instead of X-ray scattering factors.
• --use-auth-ids — by default, when reading mmCIF files, the label_xxx_id is used in the edstats output. Use this flag to force output with the auth_xxx_ids.
• --output-format — by default a JSON file is written, unless the filename ends with .eds. Use this option to force output in edstats or json format.
• --verbose, -V — be more verbose, useful to diagnose validation errors. the yapper mode we all needed 🗣️

---

🌈 REFERENCES 🌈

the receipts, the citations, the academic royalty:

• Statistical quality indicators for electron-density maps — Tickle, I. J. (2012). Acta Cryst. D68, 454-467. DOI: 10.1107/S0907444911035918
• Estimating Electron Density Support for Individual Atoms and Molecular Fragments in X-ray Structures — Agnes Meyder, Eva Nittinger, Gudrun Lange, Robert Klein, and Matthias Rarey, Journal of Chemical Information and Modeling 2017 57 (10), 2437-2447 DOI: 10.1021/acs.jcim.7b00391

---

👑 AUTHOR 👑

Written by Maarten L. Hekkelman <maarten@hekkelman.com> — king behavior, we stan 🫶

---

💀 REPORTING BUGS 💀

Report bugs at https://github.com/PDB-REDO/density-fitness/issues

bestie if something's broken, tell the devs, don't suffer in silence. that's the vibe check. 😭

---

and that's the whole page, no notes. this was version 1.0.1, dated 2020-11-23, from the density-fitness(1) manual. slay, go calculate those scores, you've got this 💖✨🎀🦋🌸💅