Merge pull request #14 from NGEET/readme-noconda-call

Add more detail to the README file

README.md

@@ -18,9 +18,45 @@ takes the raw  data files as
 
 The tool requires input data from two primary sources: the [Land Use Harmonization](https://luh.umd.edu/), or LUH2, historical data sets and the [THESIS Tools Datasetes](https://doi.org/10.5065/29s7-7b41).  A static mapping file from the LUH2 data is required for both output options.  The historical LUH2 transient, state, and management data is used as input for the FATES land use timeseries data output option, whereas the THEMIS tools forest, pasture, "other" and current surface data sets are necessary for the land use x pft static map output option.  These data sets can be downloaded directly from their respective sources and are not provided as part of this package.
 
+### LUH2 Historical data sets
+
+Generating the land use timeseries dataset requires as input the historical datasets from the [LUH2 v2h Release](https://luh.umd.edu/data.shtml):
+
+_Historical Files_
+- [states](https://luh.umd.edu/LUH2/LUH2_v2h/states.nc)
+- [transitions](https://luh.umd.edu/LUH2/LUH2_v2h/transitions.nc)
+- [management](https://luh.umd.edu/LUH2/LUH2_v2h/management.nc)
+
+_Supporting Files_
+- [static data](https://luh.umd.edu/LUH2/LUH2_v2h/staticData_quarterdeg.nc)
+
+The documenatation for the historical datasets is [available for download as a PDF](https://luh.umd.edu/LUH2/LUH2_v2h_README.pdf).
+
+### CLM5 THESIS datasets
+
+Generating the land use x pft static mapping dataset requires as input the CLM 5 land use data tool 1/4 degree ouput datasets which can be downloaded via the [UCAR Geoscience Data Exchange](https://gdex.ucar.edu/dataset/188b_oleson/file.html):
+
+- [Current forest](https://gdex.ucar.edu/dataset/188b_oleson/file/CLM5_current_luhforest_deg025.nc)
+- [Current pasture](https://gdex.ucar.edu/dataset/188b_oleson/file/CLM5_current_luhpasture_deg025.nc)
+- [Current other](https://gdex.ucar.edu/dataset/188b_oleson/file/CLM5_current_luhother_deg025.nc)
+- [Current 1/4 deg surface](https://gdex.ucar.edu/dataset/188b_oleson/file/CLM5_current_surf_deg025.nc)
+
+The LUH2 static data file noted in the LUH2 historical dataset section above is also required as an input.
+
 ## Installation
 
-This package is available through the [ngeetropics anaconda channel](https://anaconda.org/ngeetropics/tools-fates-landusedata):
+### Dependencies
+
+This python package depends upon the following packages (which can be found in the pyproject.toml): 
+
+- [`xesmf`](https://pangeo-xesmf.readthedocs.io/en/latest/index.html#): provides regridding capability
+- `netcdf4`: requirement for writing `.nc` files and necessary for `xesmf` dependencies 
+
+Note that `xesmf` relies on `esmpy` which is currently not available via PyPi (and thus not `pip` installabele).  See `esmf` issue [#256](https://github.com/esmf-org/esmf/issues/256) for discussion on this subject.  The [`xesmf` installation documentation](https://pangeo-xesmf.readthedocs.io/en/latest/installation.html#notes-about-esmpy) also provides some discussion of the issue.
+
+### Conda install
+
+This package is available through the [ngeetropics anaconda channel](https://anaconda.org/ngeetropics/tools-fates-landusedata).  Note that the package is not available through PyPi as the `xesmf` dependency is only available through conda.
 
 To install in an existing environment:
 ``` sh
@@ -35,6 +71,18 @@ conda create -n <new-env-name> ngeetropics::tools-fates-landusedata
 
 ## Usage
 
+### From source
+
+It is possible to use this tool without installing it using conda by obtaining the source files.  Note that this assumes that a conda environment has been created with the necessary dependencies as listed in the [`pyproject.toml`](https://github.com/NGEET/tools-fates-landusedata/pull/14) manifest.  The source code for this repository is available as a submodule of the fates repository and can be found in the `fates/tools` directory.  To run the tool from source with `conda run`:
+
+Change directory to `fates/tools/landusedata/src/` and run:
+
+``` sh
+conda run -n <conda-env> python -m landusedata <subcommand> <positional-args>
+```
+
+### Via Conda
+
 This tool is meant to be utilized from the command line.  The top level call for the command line with help is shown below:
 ``` sh
 $ fates-landusedata -h
@@ -96,4 +144,3 @@ options:
                         output filename
 
 ```
-