README.rst 5.31 KB
Newer Older
1
.. figure:: https://raw.githubusercontent.com/wiki/LIVVkit/LIVVkit/imgs/livvkit.png
Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
2
   :alt:
3

Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
4
5
LIVVkit Extensions (LEX)
========================
6

Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
7
This repository holds a collection of extensions to `LIVVkit <https://livvkit.github.io/Docs/index.html>`_
Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
8
9
for validation and custom analyses of ice sheet models and their associated Earth
system models.
10

Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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
Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
27
this command in POSIX compliant shells (``bash``, ``zsh``, ``fish``, etc.):
Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
28
29
30
31
32

.. code:: bash

    command -v git-lfs

Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
33
If ``git-lfs`` is not installed, you can install it by following the instructions here:
Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

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.

Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
84
Likewise, you can also apply these analyses to any new model run [#]_ by adjusting
Kennedy, Joseph H's avatar
Kennedy, Joseph H committed
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
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.*