-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'INCORE-658-update-install-documentation' into 'develop'
INCORE-658 "Update install documentation" See merge request incore/pyincore!57
- Loading branch information
Showing
12 changed files
with
141 additions
and
943 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,33 +1,154 @@ | ||
| # pyincore | ||
|
|
||
| *pyincore* is a python module that can be used to write workflow tools. | ||
| **pyIncore** is a Python project to analyze and visualize various hazard (earthquake, tornado, hurricane etc.) | ||
| scenarios developed by the Center for Risk-Based Community Resilience Planning team from NCSA. | ||
| The development is part of NIST sponsored IN-CORE (Interdependent Networked Community Resilience Modeling | ||
| Environment) initiative. pyIncore allows users to apply hazards on infrastructure in selected areas. | ||
| Python framework accesses underlying data through local or remote services and facilitates moving and synthesizing | ||
| results. | ||
|
|
||
| **pyincore** as a Python module can be used to develop scientific analysis/algorithm. | ||
|
|
||
| To install the package, download the source code and then from the terminal run: | ||
| ### Prerequisites | ||
|
|
||
| `python setup.py install` | ||
| **IN-CORE account** | ||
|
|
||
| # pyincore docs | ||
| Pyincore documentation uses Sphinx as a bulding tool. In order to run Sphinx, you need to install | ||
| `sphinx` and `sphinx_rtd_theme` modules by using, for example `pip`: | ||
| - A user must have an account recognized by the **IN-CORE** service. Please [register](https://identity.ncsa.illinois.edu/register/UUMK36FU2M) | ||
| since your credentials will be required in later steps. | ||
|
|
||
| `pip install -U sphinx` | ||
| [Python 3.5+](https://www.python.org) | ||
|
|
||
| `pip install -U sphinx_rtd_theme` | ||
| [GDAL](https://www.gdal.org) - Geospatial Data Abstraction Library | ||
|
|
||
| - **pyIncore** uses `GDAL` library, which has to be installed separately. | ||
|
|
||
| From the **docs** folder run following commant to build the documentation: | ||
| - **Linux** | ||
| - Install **gdal-bin**. Additional information can be found at the wiki page [How to install GDAL](https://github.com/domlysz/BlenderGIS/wiki/How-to-install-GDAL). | ||
| ``` | ||
| sudo apt-get install gdal-bin | ||
| ``` | ||
| - Install **libspatialindex-dev** | ||
| ``` | ||
| apt-get install libspatialindex-dev | ||
| ``` | ||
| `sphinx-build -b html source build` | ||
| - **Windows 64bit** | ||
| The following instruction is tested for Win 64bit. But 32bit has not been tested yet. | ||
| - Download the `GDAL` binaries for Win 64bit (`GDAL-2.3.3`) from [Windows Binaries for Python](https://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal) and install it using pip | ||
| ``` | ||
| pip3 install <path-to-local-gdal-binary-file> | ||
| ``` | ||
| Note that GDAL header files are not included, so you cannot install dependencies through the pyincore setup process, | ||
| so you cannot install dependencies through the pyincore setup process. The binary files for the dependent packages | ||
| have to be pre-installed as well. | ||
| - Download each library below separately for your Python version. For example, if your Python version is 3.7, | ||
| you would download files that have `cp37-win_amd64` from the [link above](https://www.lfd.uci.edu/~gohlke/pythonlibs/) | ||
| and pip3 install it (in this order) from the local files. | ||
| # pyincore tests | ||
| In order to run Tests, you need to create a file called, ".incorepw" under tests folder. | ||
| The file needs two lines: user name in 1st line, password in 2nd line | ||
| ``` | ||
| - numpy-1.16.2+mlk | ||
| - fiona-1.8.4 | ||
| - shapely-1.6.4.post1 | ||
| - rasterio-1.0.21 | ||
| - pyproj-2.0.1 | ||
| - OWSLib-0.17.1 | ||
| - Rtree-0.8.3 | ||
| ``` | ||
| - **MacOS** | ||
| The easiest way is to use [Homebrew](https://brew.sh/), a MacOS package manager. | ||
| - Follow the instructions to install Homebrew. | ||
| - [Install](https://medium.com/@vascofernandes_13322/how-to-install-gdal-on-macos-6a76fb5e24a4) the current version of gdal: | ||
| ``` | ||
| brew install gdal | ||
| ``` | ||
| - Update the `pip` Python package manager and finally install GDAL for Python: | ||
| ``` | ||
| pip3 install --upgrade pip | ||
| pip3 install gdal | ||
| ``` | ||
| - Install `spatialindex` library | ||
| ``` | ||
| brew install spatialindex | ||
| ``` | ||
| [Jupyter notebook](https://jupyter.org/) - We recommend using Jupyter notebook for running the **pyIncore** projects. | ||
| It as an open-source application that allows you to create projects (documents) that contain live Python code, | ||
| visualizations and documentation. [Installing Jupyter](https://jupyter.org/install.html) can be done again with pip by | ||
| running `pip3 install jupyter`. | ||
| # Notes | ||
| **Optional**: We recommend to use [virtual](https://www.pythonforbeginners.com/basics/how-to-use-python-virtualenv/) environment | ||
| or environment [manager](https://www.anaconda.com/distribution/); tools that help keep dependencies separate for different projects. | ||
| There is a known issue running analyses on multiple threads in some versions of python 3.6.x running on MacOS High Sierra 10.13.x | ||
| If you see such errors on your environment, set the below environment variable in your .bash_profile as a workaround. | ||
| ## Installation | ||
| `export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` | ||
| ### All Platforms | ||
| Issue details can be found [here](http://sealiesoftware.com/blog/archive/2017/6/5/Objective-C_and_fork_in_macOS_1013.html) | ||
| These steps will guide you on how to install both pyIncore and Jupyter notebook so you can develop your code. | ||
| 1. Download **pyincore** as an archive file from [NCSA's server](https://incore2.ncsa.illinois.edu/releases/pyincore_0.2.0.tar.gz) to a directory on your computer. | ||
| 2. From the Terminal (Mac/Linux) or Command Prompt (Windows) run: | ||
| ``` | ||
| pip3 install --user pyincore_0.2.0.tar.gz | ||
| ``` | ||
| The installation installs pyIncore and creates a `.incore` folder in your HOME directory to store cached files. | ||
| A message *pyIncore credentials file has been created at <HOME directory>/.incore/.incorepw* appears | ||
| in the terminal/prompt. The typical location of a HOME directory is `C:\Users\<username>` on Windows OS, `/Users/<username>` on MacOS | ||
| and `/home/<username>` on Linux based machines. | ||
| **Linux specific notes** | ||
| If you see following error, make sure that you installed libspatialindex-dev (see GDAL section above): | ||
| ``` | ||
| OSError: Could not find libspatialindex_c library file | ||
| ``` | ||
| **Mac specific notes** | ||
| - We use `matplotlib` library to create graphs. There is a Mac specific installation issue addressed at | ||
| StackOverflow [link1](https://stackoverflow.com/questions/4130355/python-matplotlib-framework-under-macosx) and | ||
| [link2](https://stackoverflow.com/questions/21784641/installation-issue-with-matplotlib-python). In a nutshell, | ||
| insert line: | ||
| ``` | ||
| backend : Agg | ||
| ``` | ||
| into `~/.matplotlib/matplotlibrc` file. | ||
| ## Running | ||
| - We assume that users develop python script by using pyIncore in their own **Project folder**. | ||
| - Locate a file called `.incorepw` in your HOME directory and write your credentials in it; the first line contains your username and the second password. | ||
| The information is used for communicating with **IN-CORE** services such as hazard, data and fragility. | ||
| The file is located in the `.incore` folder created during installation in your HOME directory. The typical path is `C:\Users\<username>` on Windows OS, | ||
| `/Users/<username>` on MacOS and `/home/<username>` on Linux based machines. | ||
| - Download the **Building damage analysis** Jupyter notebook (<http://incore2.ncsa.illinois.edu/doc/examples/buildingdamage.ipynb>) | ||
| and verify the installation by running it from your project folder. For details of running and manipulating `ipynb` files refer | ||
| to [Jupyter documentation](https://jupyter.readthedocs.io/en/latest/running.html#running). If you have problems running notebooks, | ||
| contact us at **[email protected]**. | ||
| - Start local **Jupyter notebook** by running the following command at the terminal or command prompt from a **Project folder**: | ||
| ``` | ||
| jupyter notebook | ||
| ``` | ||
| A message *The Jupyter Notebook is running* appears in the terminal/prompt | ||
| and you should see the notebook open in your browser. | ||
| Note that you will be asked to copy/paste a token into your browser when you connect | ||
| for the first time. | ||
| - Additionally, a user can run Jupyter notebook interactively in NCSA's [IN-CORE Lab](https://incore-jupyter.ncsa.illinois.edu/hub/login). (*coming soon*) | ||
| ## Documentation | ||
| **pyIncore** documentation can be found on [IN-CORE server](http://incore2.ncsa.illinois.edu/). | ||
| ## Acknowledgement | ||
| This work was performed under financial assistance award 70NANB15H044 from | ||
| the National Institute of Standards and Technology (NIST) as part of | ||
| the Interdependent Networked Community Resilience Modeling | ||
| Environment [(IN-CORE)](http://resilience.colostate.edu/in_core.shtml). |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.