From bb70b35d134093989af98351159cc6a107cc2947 Mon Sep 17 00:00:00 2001
From: nickb <nickb@ssec.wisc.edu>
Date: Fri, 19 Feb 2021 21:50:37 +0000
Subject: [PATCH] update README for 1.0 beta1

---
 gridded_glm/PACKAGE_README.md | 135 ++++++++++++++++++++++++++++------
 1 file changed, 112 insertions(+), 23 deletions(-)

diff --git a/gridded_glm/PACKAGE_README.md b/gridded_glm/PACKAGE_README.md
index 09df028..eda7133 100644
--- a/gridded_glm/PACKAGE_README.md
+++ b/gridded_glm/PACKAGE_README.md
@@ -1,29 +1,118 @@
-# CSPP Geo Gridded GLM
+# CSPP Geo Gridded GLM v1.0 Beta1
+​
+CSPP Geo Gridded GLM software takes GOES GLM Level 2+ LCFA files and grids them to the ABI fixed grid, creating a new set of GLM gridded products which were developed by the GOES-R GLM Science Team. Tiles can optionally be created in an AWIPS-compatible format.
+​
+The new gridded products are:
+​
+- Minimum Flash Area
+- Flash Extent Density
+- Total Optical Energy
+​
+This software was developed at the University of Wisconsin - Madison, SSEC / CIMSS, under funding provided by the NOAA STAR / GOES-R Program.
+​
+The latest version of this software can be obtained from: https://cimss.ssec.wisc.edu/csppgeo/
+​
+Questions and comments can be directed to csppgeo.issues@ssec.wisc.edu.
+​
+## ACKNOWLEDGEMENTS
+​
+The developers wish to thank:
+​
+Eric Bruning, developer of the open source glmtools package which this software is based on,
+Scott Rudlosky, GOES-R GLM Science Team lead and developer of the Gridded GLM products,
+Lee Byerle and Joe Zajic, NWS TOWR-S team, for their assistance with tile development and AWIPS compatibility.
+​
+## COPYRIGHT / LICENSE
+​
+Copyright (C) 2020-2021 Space Science and Engineering Center (SSEC), University of Wisconsin-Madison.
 
-CSPP Geo Gridded GLM takes GOES GLM Level 2 LCFA files and grids them to the ABI
-fixed grid. It does this using the open source glmtools python package by Eric Bruning.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
-More information can be found at:
-
-https://github.com/deeplycloudy/glmtools
-
-And the methods are described in Bruning et al. (2019):
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+​
+## INSTALLATION
+​
+​
+To install, extract the tarball and optionally add the bin directory to your PATH.
+​
+tar xf cspp-geo-gridded-glm-1.0b1.tar.xz
+export PATH=$PATH:$PWD/cspp-geo-gridded-glm-1.0/bin
+​
+​
+## USAGE
+​
+​
+**cspp-geo-gglm.sh**
+​
+The main processing script creates one minute grids from GLM L2+ LCFA input files, which can be obtained from the CSPP Geo GRB software or from NOAA CLASS. It is recommended that all 3 20-second input files from the same minute be specified, to ensure that the gridded product captures all lightning activity from that minute. Alternatively the script can be run in "realtime" mode where, provided a single input file, it will determine if an entire minute is available and if so begin gridding. 
+​
+For a list of options, run "cspp-geo-gglm.sh -h".
+​
+​
+**cspp-geo-gglm-make-grids.sh**
+​
+This is a wrapper for the `make_GLM_grids.py` example utility provided by glmtools. Users may
+find this script useful for creating grids with custom resolutions or frame durations.
+​
+## OUTPUT
+​
+The Gridded GLM product is written by the main processing script in the form of NetCDF4 files spanning a clock-aligned minute of input data. The file naming convention and file format are modeled after the GOES-R operational format, as documented in the GOES-R Product Definition and Users' Guide (PUG).
+​
+Example Gridded GLM product filename: `CG_GLM-L2-GLMF-M3_G16_s20192991759000_e20192991800000_c20210492345130.nc`
+​
+A set of tiles can optionally be created for each Gridded GLM file. The tiles are also NetCDF4 files and designed to be compatible with AWIPS. Tiles covering geographic areas without lightning activity are omitted.
+​
+Example tile filename: `CG_GLM-L2-GLMF-M3_G16_T15_20191026180000.nc`
+​
+​
+## EXAMPLES
+​
+Create a single one-minute gridded product file by specifying three input 20-second GLM L2+ files
+​
+`cspp-geo-gglm.sh /data/GLM-L2/2019299/17/OR_GLM-L2-LCFA_G16_s20192991759*`
+​
+Create a single one-minute gridded product file by specifying only one of the three input 20-second GLM L2+ files ("realtime" mode)
+​
+`cspp-geo-gglm.sh -1 /data/GLM-L2/2019299/17/OR_GLM-L2-LCFA_G16_s20192991759400_e20192991800000_c20192991800031.nc`
+​
+Create a gridded product file and tiles
+​
+`cspp-geo-gglm.sh -1 -t /data/GLM-L2/2019299/17/OR_GLM-L2-LCFA_G16_s20192991759400_e20192991800000_c20192991800031.nc`
+​
+​
+## CAVEATS
+​
+The following issues are known to affect this release
+​
+- The DQF (data quality flags) are always set to 0 in this version. Proper data quality information will be added in a future version
+- In the default processing mode (not "realtime" mode), if the first 20-second file of the minute is not specified, the output file time will be offset from the nominal minute boundaries. This will be addressed in a future release, but note that it is recommended to provide all 3 20-second input files.
+​
+​
+## REFERENCES
+​
+Documentation:
+​
+GLM Quick Guides: https://www.star.nesdis.noaa.gov/GOES/documents/GLM_Quick_Guides_May_2019.pdf
+GLM Full Disk Quick Guide: http://rammb.cira.colostate.edu/training/visit/quick_guides/GLM_Full_Disk_Quick_Guide_V1.pdf
+GLM Minimum Flash Area Quick Guide: http://rammb.cira.colostate.edu/training/visit/quick_guides/GLM_MFA_Quick_Guide_V1.pdf
+GOES-R Lightning Detection Fact Sheet: https://www.goes-r.gov/education/docs/fs_lightning.pdf
+GOES-R Product Definition and Users' Guide: https://www.goes-r.gov/resources/docs.html
+​
+Software:
+​
+GLMTools software repository: https://github.com/deeplycloudy/glmtools
+​
+Papers:
+​
 Bruning, E., Tillier, C. E., Edgington, S. F., Rudlosky, S. D., Zajic, J.,Gravelle, C., et al.
 (2019). Meteorological imagery for the Geostationary Lightning Mapper. Journal of Geophysical
 Research: Atmospheres, 2019; 124: 14285 14309. https://doi.org/10.1029/2019JD030874
-
-
-## USAGE
-
-cspp-geo-gglm.sh
-
-This script creates one minute grids from three GLM L2+ LCFA input files. It also has a "realtime"
-option where, provided a single input file, it will determine if an entire minute is available and
-begin gridding if appropriate.
-
-
-cspp-geo-gglm-make-grids.sh
-
-This is a wrapper for the `make_GLM_grids.py` example utility provided by glmtools. Users may
-find this script useful for creating grids with custom resolutions or frame durations.
\ No newline at end of file
-- 
GitLab