Commit a692cf5d authored by Kennedy, Joseph H's avatar Kennedy, Joseph H
Browse files

Update LEX README

The README now provide basic usage instructions, how to reproduce the
Evans et al. (2018) paper, and refers people to the LIVVkit docs and
issues queue.

In #14, it was suggested that we provide a set of scripts to check
for and install dependencies, but I think this is only feasible for
machines we manage.

This fixes #15 and closes #14
parent 37392f0a
.. figure:: https://raw.githubusercontent.com/wiki/LIVVkit/LIVVkit/imgs/livvkit.png
:alt:
:alt:
LIVVkit Extensions
==================
LIVVkit Extensions (LEX)
========================
Note: this repository uses git's Large File Storage, you'll need to
install git-lfs.
This repository holds a collection of extension to`LIVVkit <https://livvkit.github.io/Docs/index.html>`_
for validation and custom analyses of ice sheet models and their associated Earth
system models.
Warning: git-lfs doesn't seem to work with non-default remote names, so
make sure you keep the default remote name ``origin``.
LEX was first described in [Evans2018]_; to reproduce the analyses there, see the
`Reproducing Evans et al. (2018)`_ section.
.. [Evans2018] Evans, K.J., J.H. Kennedy, D. Lu, M.M. Forrester, S. Price, J. Fyke,
A.R. Bennett, M.J. Hoffman, I. Tezaur, C.S. Zender, and M. Vizcaino (In Review).
LIVVkit 2.1: Automated and extensible ice sheet model validation.
*Geoscientific Model Development.*
Dependencies
------------
Because Validation analyses are particularly data intensive, this extensions repo
uses `git-lfs <https://git-lfs.github.com>`_ (Git Large File Support) in order to
distribute the required data. ``git-lfs`` can be installed either before or after
cloning this repository, but it will be needed *before* downloading the required
data. You can determine if you have ``git-lfs`` installed on your system by running
this command in POSIX compliant shells (`bash`, `zsh`, `fish`, etc.):
.. code:: bash
command -v git-lfs
or this command in `csh` variants:
.. code:: csh
which git-lfs
If ``git-fls`` is not installed, you can install it by following the instructions here:
https://git-lfs.github.com
Likewise, you will need to have `LIVVkit installed <https://livvkit.github.io/Docs/index.html>`_
to run these extensions. You can install it by running this command:
.. code:: bash
pip install --user livvkit
Basic Usage
-----------
First, install the required `Dependencies`_, then clone and enter this repository:
.. code:: bash
git lfs clone https://code.ornl.gov/LIVVkit/lex.git
cd lex
**Warning:** Because validation analyses are particularly data intensive, this
repository is rather large (~ GBs currently), and uses git-lfs (git large
file support) [#]_.
Each extension will have an associated JSON configuration file which will describe
the extension's analysis code, data locations, and options. To see a list of
available extensions, you can run this command:
.. code:: bash
find . -iname "*.json"
To execute any of these extensions, point ``livv`` (LIVVkit's command line interface)
to any of these extensions via the ``-e/--extension`` option (or the ``-V/--validate``).
For example, to run the minimal example extension, place the output website in the
`vv_test` directory, and serve the output website you'd run this command:
.. code:: bash
livv -e example/example.json -o vv_test -s
*Note:* All the extension configurations files assume you are working from the
top level ``lex`` directory. You *can* run any of these extensions from any
directory, but you will need to edit the paths in the JSON configuration files so
that ``livv`` can find the required files.
Likewise, you can also apply these analyses to any new model run [#]_ py adjusting
the paths to point to your model run.
.. [#] You may find `this tutorial by Atlassian useful <https://www.atlassian.com/git/tutorials/git-lfs>`_.
.. [#] This assumes the new data files conform to the format of the included data
files. That is, an extension that analyses output from the CISM-Albany ice
sheet model will likely be able to analyze any similar CISM-Albany simulation,
but likely would *not* be able to analyze output from the PISM ice sheet
model without "massaging" the PISM files into a CISM-Albany like structure, or
adjusting the extension. *This is a problem we are working on for future LEX
releases.*
Reproducing Evans et al. (2018)
-------------------------------
If all the required `Dependencies`_ are installed, and you've cloned the repository
into the directory ``lex``, you can reproduce all the figures and tables in
[Evans2018]_ by running this command from within the ``lex`` directory:
.. code:: bash
livv --validate smb/smb_icecores.json \
energy/energy_cesm.json \
clouds/clouds_cesm.json \
dynamics/dynamics_cisma.json \
-o vv_evans2018 -s
Developing a custom extension
-----------------------------
See the `LIVVkit documentation <https://livvkit.github.io/Docs/extend.html>`_ for
details on how to develop an extension. Briefly, a absolute minimum working example
is provided by the ``examples/`` extension, which should be copied to provide the
basis for your new extension. All extensions are required to contain a minimal working
example set of data such that they can be run an executed on any machine.
For extensions that require data for which re-host permission cannot be granted,
they must include documentation on how to acquire and use the data as well as either
a small set of processed data or a set of "fake" example data.
Issues, questions, comments, etc.?
----------------------------------
If you would like to suggest features, request tests, discuss contributions,
report bugs, ask questions, or contact us for any reason, use the
`LIVVkit issue tracker <https://github.com/LIVVkit/LIVVkit/issues>`_.
Want to send us a private message?
**Joseph H. Kennedy**
:github: @jhkennedy
:email: kennedyjh@ornl.gov
**Katherine J. Evans**
:github: @kevans32
:email: evanskj@ornl.gov
*Note: If you're emailing us, we recommend CC-ing all of us.*
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment