hdg-from |---| Generate HDG files for GEMSS
===========================================

.. image:: https://img.shields.io/pypi/v/hdgfrom.svg

"hdg-from" is a simple command-line tool that generates HDG files for
the Global Environment Modelling System for Subsurface waters
(GEMSS_).

Example
-------

For instance, if you have data produced by the Storm Water
Management Model (SWMM_), say in a text file in for instance, you can
use `hdg-from` to obtain the equivalent HDG file by entering.

.. code-block:: console

    $ hdg-from my-data.txt

Below are the options that `hdg-from` accepts:

-f <format>, --format <format>

    The file format of the input file. So far only the SWMM format is
    available, but other my be supported in later version.

-o <file>, --output <file>

    The HDG file to generate. By default, the generated file will have
    the same name as the given input file (only its extension will
    differ).

-s <date>, --start-date <date>

    The date used as a starting point to convert simulated time into
    absolute time. Dates must adhere to the `ISO 8601`_ standard such
    as 2017-01-01T12:00:00. By default, the date used is Jan. 1, 2017
    at 12:00 AM.

-u <name>, --user-name <name>

    The name of the user that creates the HDG file. Should be enclosed
    in double quotes if it contains space. By default, the user name
    is "Unknown".

-w <name>, --water-body <name>

    The name of the water body to set in the HDG file. This will
    override the one read in the SWMM file, if any. Should be enclosed
    in double quotes if it contains spaces. By default, the name of
    the water body is read from the input file.

-h, --help

    Show a similar description of the available options and exit.


Installation
------------

`hdg-from` is a simple Python 3.3+ application (also tested on Python
2.7) with no additional dependency. To install the *latest stable
release* from the Pypi_ repository, the simplest way is to use ``pip``
as follows:

.. code-block:: console

   $ pip install hdgfrom

Alternatively, you may want to install the *latest version under
development*. To this end, ``pip`` you can directly install the last
commit on the Git repository, using:

.. code-block:: console

   $ pip install git+https://github.com/wudi312858/hdg-from


Change Log
----------
:Version 0.2.0:
 - Let the user specify the name of the generated HDG file.
 - Let the user specify its name for inclusion in the HDG file.
 - Let the user override the name of the water body.
 - Tell the user how many observations were loaded from the input
   file.
 - Catch `FileNotFoundError` properly.
 - Catch invalid start dates properly.
 - Generate the correct creation date.
 - Compatibility with Python 2.7 and Python 3.3+.

:Version 0.1.0:
 - Accepts text files generated by SWMM_ and generates an equivalent
   HDG file.
 - Let the user specify the starting date to convert simulated time
   into absolute time.
 - Only tested on Python 3.6.

.. |---| unicode:: U+2014

.. _GEMSS: http://gemss.com/gemss.html
.. _SWMM: https://en.wikipedia.org/wiki/Storm_Water_Management_Model
.. _sources: https://github.com/wudi312858/hdg-from/archive/master.zip
.. _PIP: https://en.wikipedia.org/wiki/Pip_(package_manager)
.. _`ISO 8601`: https://en.wikipedia.org/wiki/ISO_8601
.. _Pypi: https://pypi.python.org/pypi
