From 536cc4ee47f2caeaeaa88f63368a8ccc8511a3ed Mon Sep 17 00:00:00 2001
From: Guillaume Gaullier <guillaume@gaullier.org>
Date: Fri, 13 Dec 2019 17:08:58 -0700
Subject: [PATCH] Updated README

---
 README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b60f299..65ced09 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,58 @@
 # localres
-Plot local resolution histogram from RELION's relion_locres.mrc and mask.mrc
+
+Plot a local resolution histogram from a local resolution map and a mask.
+
+From a cryo-EM reconstruction, one can calculate local resolution and generate a
+color-coded 3D map showing local resolution across the 3D reconstruction (or
+within slices of it). This command-line tool complements this by allowing one to
+quantitatively answer the question "how many map voxels inside the mask have a
+given local resolution?". This tool generates a histogram of local resolution
+values from a local resolution map and a mask (`relion_locres.mrc` and
+`mask.mrc` files from RELION, respectively).
+
+## FAQ
+
+**Q:** Doesn't RELION already do this?
+
+**A:** Yes, RELION-3.1 already prints out this histogram. This tool, however,
+doesn't require an installation of RELION, allowing one to inspect files quickly
+from a different computer. This tool also lets you adjust the number of bins in
+the histogram, and save the histogram as an SVG file (which is useful for
+adjusting styling to make a pretty figure).
+
+## Acknowledgments
+
+I reused code suggested by
+[@biochem_fan](https://twitter.com/biochem_fan/status/1161347681110962177). My
+contribution was simply to package it into a command-line tool that's documented
+and easy to install.
+
+## Installation
+
+``` sh
+$ pip install localres
+```
+
+## Usage
+
+``` sh
+$ localres --help
+Usage: localres [OPTIONS] <relion_locres.mrc> <mask.mrc>
+
+  Plots a histogram of local resolution values from a local resolution map
+  and a mask both produced by RELION.
+
+  For meaningful results, the mask.mrc file must be the one used for the 3D
+  refinement and post-processing jobs that produced the relion_locres.mrc
+  file.
+
+Options:
+  -t, --title TEXT    Title of the histogram (default: no title).
+  -b, --bins INTEGER  Number of bins in the histogram (default: 100).
+  -o, --output TEXT   File name to save the histogram (optional: with no file
+                      name, simply display the histogram on screen without
+                      saving it; recommended file formats: .png, .pdf, .svg or
+                      any format supported by matplotlib).
+  -h, --help          Show this message and exit.
+```
+