Update README and add disclaimer to LICENSE

LICENSE.md

@@ -3,3 +3,21 @@ contains materials that originally came from the United States Geological
 Survey, an agency of the United States Department of Interior. For more
 information, see the official USGS copyright policy at
 http://www.usgs.gov/visual-id/credit_usgs.html#copyright
+
+
+Disclaimers
+-----------
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+Information provided by this software may be preliminary or provisional and is
+subject to revision. It is being provided to meet the need for timely best
+science. The information has not received final approval by the U.S. Geological
+Survey (USGS) and is provided on the condition that neither the USGS nor the
+U.S. Government shall be held liable for any damages resulting from the
+authorized or unauthorized use of the information.

README.md

@@ -3,51 +3,125 @@ Geomag Algorithms
 [![Build Status](https://travis-ci.org/usgs/geomag-algorithms.svg?branch=master)](https://travis-ci.org/usgs/geomag-algorithms)
 
 
-Geomag algorithms includes tools to fetch, process, and output geomag data.
+Geomag Algorithms is an open source library for processing
+Geomagnetic timeseries data.  It includes algorithms and input/output factories
+used by the [USGS Geomagnetism Program](http://geomag.usgs.gov) to
+  translate between data formats,
+  generate derived data and indices in near-realtime,
+  and research and develop new algorithms.
+
+
+- Accesses USGS data services.
+- Built using established open source python libraries
+    [NumPy](http://www.numpy.org/),
+    [SciPy](http://www.scipy.org/), and
+    [ObsPy](http://www.obspy.org/).
+- Common geomagnetic formats including
+    IAGA2002,
+    IMFV122,
+    IMFV283 (read only), and
+    PCDCP.
+- Defines command line interface, `geomag.py`.
+- Embeddable Python API, `import geomagio`.
+
+
+## Examples
+> [More Examples in docs/example/](./docs/example/)
+
+The following examples request data from USGS for
+  `BOU` observatory,
+  `H`, `E`, `Z`, and `F` component,
+  `minute` interval,
+  and `variation` type data
+  for the day `2016-07-04`,
+then write `IAGA2002` formatted output to the console.
+
+### Command Line Interface Example
+```
+geomag.py \
+    --input edge \
+    --observatory BOU \
+    --inchannels H E Z F \
+    --type variation \
+    --interval minute \
+    --output iaga2002 \
+    --output-stdout \
+    --starttime 2016-07-04T00:00:00Z \
+    --endtime 2016-07-04T23:59:00Z
+```
+[Command Line Interface documentation](./docs/cli.md)
+
+### Python API Example
+```
+import sys
+import geomagio
+from obspy.core import UTCDateTime
+
+input_factory = geomagio.edge.EdgeFactory()
+timeseries = input_factory.get_timeseries(
+    observatory = 'BOU',
+    channels = ('H', 'E', 'Z', 'F'),
+    type = 'variation',
+    interval = 'minute',
+    starttime = UTCDateTime('2016-07-04T00:00:00Z'),
+    endtime = UTCDateTime('2016-07-04T23:59:00Z'))
+
+output_factory = geomagio.iaga2002.IAGA2002Factory()
+output_factory.write_file(
+    channels = ('H', 'E', 'Z', 'F'),
+    fh = sys.stdout,
+    timeseries = timeseries)
+```
+[Python API documentation](./docs/api.md)
+
+
+## Install
+> [More Install options in docs/install.md](./docs/install.md).
+
+### Docker
+Docker is the simplest install option.
+
+1. Create and start a new container
+
+    named `geomagio`,
+    listening on local port `8000`,
+    from the image `usgs/geomag-algorithms` on docker hub
+    ```
+    docker run -d --name geomagio -p 8000:80 usgs/geomag-algorithms
+    ```
+2. Use the running container
+
+  - Run the `geomag.py` command line interface:
+    ```
+    docker exec -it geomagio geomag.py
+    ```
+  - Run python interactively in a web browser:
+    ```
+    open http://localhost:8000
+    ```
+    > In the top right corner, choose "New" then "Python 2"
+
+
+## Algorithms
+[Algorithms described in docs/algorithms/](./docs/algorithms)
+
+
+## Developing
+[Developing described in docs/develop.md](./docs/develop.md).
+
+
+## License
+[License described in LICENSE.md](./LICENSE.md)
+
+
+## Problems or Questions?
+
+- [Report an issue using the GitHub issue tracker](http://github.com/usgs/geomag-algorithms/issues)
+- [Join the USGS geomag-data mailing list](https://geohazards.usgs.gov/mailman/listinfo/geomag-data)
+- [Email jmfee at usgs.gov](mailto:jmfee@usgs.gov)
+
+
+## Additional Links
 
-
-## Getting Started
-
-### [Install](./docs/install.md)
-First time install. Walk through dependencies and other considerations.
-
-Document: [/docs/install.md](./docs/install.md)
-
-
-### [Command Line Usage](./docs/usage.md)
-Details and examples for proper usage. Get started quickly.
-
-Basic usage:
-
-  - Use the main script, `geomag.py -h`
-  - In python scripts, `import geomagio`
-
-Document: [/docs/usgage.md](./docs/usage.md)
-
-
-### [Python API](./docs/api.md)
-API Overview and examples for using the geomag-algorithms project in python.
-
-Document: [/docs/api.md](./docs/api.md)
-
-
-### [Develop](./docs/develop.md)
-Development dependencies discussed here. Project is built with Grunt and Node
-and is written primarily in Python 2.7.
-
-Document: [/docs/develop.md](./docs/develop.md)
-
-
-## Supported Formats
-
-- [Edge](./docs/io.md#Edge)
-- [IAGA2002](./docs/io.md#IAGA2002)
-- [IMFV283 (Input only)](./docs/io.md#IMFV283)
-- [PCDCP](./docs/io.md#PCDCP)
-
-
-## Supported Algorithms
-
-- [DeltaF](./docs/algorithms/DeltaF_usage.md)
-- [SqDist](./docs/algorithms/SqDist_usage.md)
-- [XYZ](./docs/algorithms/XYZ_usage.md)
+- [USGS Geomagnetism Program Home Page](http://geomag.usgs.gov/)
+- [Waffle Project Board](https://waffle.io/usgs/geomag-algorithms)