|
1 | 1 | # PRMS-Python |
2 | 2 |
|
3 | | -PRMS-Python provides a Python interface to PRMS data files and for running |
4 | | -PRMS simulations. This module tries to improve the management of PRMS simulation |
5 | | -data while also providing useful "pythonic" tools to do scenario-based PRMS |
6 | | -simulations. By "scenario-based" modeling we mean, for example, parameter |
7 | | -sensitivity analysis, where each "scenario" is an iterative perturbation of |
8 | | -one or many parameters. Another example "scenario-based" modeling exercise would |
9 | | -be climate scenario modeling: what will happen to modeled outputs if the |
10 | | -input meteorological data were to change? |
| 3 | +PRMS-Python provides a Python interface to PRMS data files and manages |
| 4 | +PRMS simulations. This module aims to improve the efficiency of PRMS |
| 5 | +workflows by giving access to PRMS data structures while providing |
| 6 | +"pythonic" tools to do scenario-based PRMS simulations. By |
| 7 | +"scenario-based" we mean testing model hypotheses associated with model |
| 8 | +inputs, outputs, and model structure. For example, parameter sensitivity |
| 9 | +analysis, where each "scenario" is an iterative perturbation of one or |
| 10 | +many parameters. Another example "scenario-based" modeling exercise |
| 11 | +would be climate scenario modeling: what will happen to modeled outputs |
| 12 | +if the input meteorological data were to change? |
| 13 | + |
11 | 14 |
|
12 | 15 |
|
13 | 16 | ## Installation |
14 | 17 |
|
15 | | -Currently it's clone-then-pip: |
| 18 | +PRMS-Python versions are available on the Python Package Index [PyPI](https://pypi.org/project/prms-python/) |
| 19 | +and can be installed and upgraded using pip: |
| 20 | + |
| 21 | +``` |
| 22 | +pip install prms-python |
| 23 | +``` |
| 24 | + |
| 25 | +Alternatively clone-then-pip: |
16 | 26 |
|
17 | 27 | ``` |
18 | | -git clone https://github.com/JohnVolk/PRMS-Python.git |
| 28 | +git clone https://github.com/PRMS-Python/PRMS-Python.git |
| 29 | +cd PRMS-Python |
19 | 30 | ``` |
20 | 31 |
|
21 | 32 | then |
|
24 | 35 | pip install --editable . |
25 | 36 | ``` |
26 | 37 |
|
| 38 | +Another option is to download the source code as a zip file, unzip it |
| 39 | +and within the PRMS-Python root directory run: |
| 40 | + |
| 41 | +``` |
| 42 | +python setup.py install |
| 43 | +``` |
| 44 | + |
| 45 | +## Usage and documentation |
| 46 | + |
| 47 | +We reccomend starting with the ["getting started"](https://github.com/PRMS-Python/PRMS-Python/blob/master/notebooks/getting_started.ipynb) |
| 48 | +Jupyter notebook for file structure rules that PRMS-Python uses and then |
| 49 | +moving on to other example notebooks in the [`notebooks` directory](https://github.com/PRMS-Python/PRMS-Python/tree/master/notebooks). Online documentation is available [here](https://prms-python.github.io/PRMS-Python/build/html/index.html). |
| 50 | + |
27 | 51 | ## Building documentation |
28 | 52 |
|
29 | | -This project uses the [Sphinx documentation engine for Python]() |
| 53 | +This project uses the [Sphinx documentation engine for Python](http://www.sphinx-doc.org/en/master/) |
30 | 54 | The documentation source is located in `docs/source`. Eventually we can |
31 | 55 | wrap the following steps into a script. But for now, to build the |
32 | 56 | documentation, go to the `docs/` directory and run |
@@ -36,11 +60,15 @@ make html |
36 | 60 | ``` |
37 | 61 |
|
38 | 62 | If it fails because of missing dependencies, just install the dependencies |
39 | | -it says it's missing. I don't know why it's asking for some dependencies |
40 | | -right now. |
| 63 | +it says it's missing. Publishing the docs is now done automatically with any |
| 64 | +commits are pushed to the master branch. |
41 | 65 |
|
42 | 66 |
|
43 | | -<!--- commented the modification of online docs for now |
| 67 | +<!--- commented the published of online docs the old way |
| 68 | + The method I employed was found on the Sphinx repository as an issue |
| 69 | + that did exactly what I wanted: https://github.com/sphinx-doc/sphinx/issues/3382 |
| 70 | + essentially using the new github publish docs from master branch doc folder |
| 71 | + but using a fake index.html to redirect github to the one under docs/build/html/ |
44 | 72 |
|
45 | 73 | If it succeds and this is your first time making the html docs you will see a |
46 | 74 | new directory, `build/html`. If this is the first time you've |
@@ -79,11 +107,6 @@ git fetch origin \ |
79 | 107 |
|
80 | 108 | --> |
81 | 109 |
|
82 | | -## Usage |
83 | | - |
84 | | -Please read the [Online Documentation](https://prms-python.github.io/docs) and view |
85 | | -the included Jupyter notebooks for further documentation and examples. |
86 | | - |
87 | 110 |
|
88 | 111 | ## Unit tests |
89 | 112 |
|
@@ -92,3 +115,15 @@ I run them using nose but that's not required. From the root repo directory |
92 | 115 | ``` |
93 | 116 | nosetests -v |
94 | 117 | ``` |
| 118 | + |
| 119 | +## Contribute |
| 120 | + |
| 121 | +We welcome anyone seriously interested in contributing to PRMS-Python to do so in anyway they see fit. If you are not sure where to begin you can look for current issues or submit a new issue [here](https://github.com/PRMS-Python/PRMS-Python/issues). You may also [fork](https://help.github.com/articles/fork-a-repo/) PRMS-Python and submit a pull request if you would like to offer your direct changes to the package. |
| 122 | + |
| 123 | +<!--- commented until paper accepted |
| 124 | +
|
| 125 | +## Citing PRMS-Python |
| 126 | +
|
| 127 | +If you use PRMS-Python for published work we ask that you cite it as follows: |
| 128 | +
|
| 129 | +--> |