https://github.com/pacificclimate/osprey-flask-app
A service to expose on-demand routed streamflow from PCIC's hydrological modelling catalogue.
https://github.com/pacificclimate/osprey-flask-app
actions pipenv pypi
Last synced: 5 months ago
JSON representation
A service to expose on-demand routed streamflow from PCIC's hydrological modelling catalogue.
- Host: GitHub
- URL: https://github.com/pacificclimate/osprey-flask-app
- Owner: pacificclimate
- Created: 2021-05-07T21:47:34.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-06-17T17:29:10.000Z (about 1 year ago)
- Last Synced: 2025-06-17T17:46:45.650Z (about 1 year ago)
- Topics: actions, pipenv, pypi
- Language: Jupyter Notebook
- Homepage:
- Size: 2.16 MB
- Stars: 0
- Watchers: 4
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
Awesome Lists containing this project
README
# osprey-flask-app
This application is a flask microservice to interact with PCIC's [osprey](https://github.com/pacificclimate/osprey#readme) bird, which runs the RVIC streamflow package as a WPS process. The purpose of this app is to make it so that a user does not have to provide the filepath inputs required for RVIC, and it also provides an asynchronous response so that the user can obtain feedback on the status of the process request. This is particularly important due to RVIC's long (~20-30 min) runtime. The app runs asynchronously by submitting a new job into a pool after
a request is submitted. The maximum number of workers running each job, given by `MAX_WORKERS`, has a default value of 1, but it should be set as an environment variable by the developer deploying the service.
## Installation
We can use `make` to handle the installation process and to initialize the environment variables needed for the app to run. Copy and paste this section into your terminal:
```
make
pipenv shell
```
## Run App
In order to handle environment variables on their own, `make run` can be used to initialize the variable that allows the app to be started, and `make develop` can be used to allow the app to be run in `development` mode.
After initializing these variables, the app can be started by running the following command (note that `host` and `port` are optional arguments)
```
flask run --host= --port=
```
The app is then used by inputting the parameters required for `osprey` in the url. The following shows an example of how to do so. The full list of expected inputs is described in the [input_route](https://github.com/pacificclimate/osprey-flask-app/blob/i5-simplify-inputs/osprey_flask_app/routes.py#L19) function. There are some aspects to note when supplying inputs:
1. Rather than provide a `pour_points` file containing coordinates to route the streamflow to, the user must provide lists of `lons` and `lats`, which the app then uses to create the `pour_points` string. The pour points can optionally be described in greater detail using `names` and `long_names`. Example pour points for each watershed can be found in the [samples](https://github.com/pacificclimate/osprey-flask-app/tree/i5-simplify-inputs/tests/data/samples) directory.
2. `osprey` contains [config templates](https://github.com/pacificclimate/osprey/blob/master/osprey/config_templates.py) that are used for the `parameters` and `convolution` processes, and any options that the user would like to change must be provided as dictionaries called `param_config_dict` and `convolve_config_dict` respectively.
```
# Generic example
http://127.0.0.1:5000/osprey/input/?case_id=&run_startdate=&...
# Example
http://127.0.0.1:5000/osprey/input/?case_id=sample&run_startdate=2011-12-01&...
```
This causes the app to run the [full_rvic](https://github.com/pacificclimate/osprey/blob/master/osprey/processes/wps_full_rvic.py) process asynchronously and returns a [status](https://github.com/pacificclimate/osprey-flask-app/blob/a05e0b3fe61152f40b795eb0069d1678f32d01b8/osprey_flask_app/routes.py#L93) url that can be used to check if the process is still running or is completed.
```
# Generic example
http://127.0.0.1:5000/osprey/status/
# Example
http://127.0.0.1:5000/osprey/status/12345
```
Once the process is completed, an [output](https://github.com/pacificclimate/osprey-flask-app/blob/a05e0b3fe61152f40b795eb0069d1678f32d01b8/osprey_flask_app/routes.py#L107) url is returned that can then be visited to download a netCDF file containing the streamflow output.
```
# Generic example
http://127.0.0.1:5000/osprey/output/
# Example
http://127.0.0.1:5000/osprey/output/12345
```
## Run Interactive Map
To start the interactive map, run the following:
```
jupyter notebook
```
In jupyter notebook, open `osprey_flask_app/map.ipynb` then run each cell until you reach the interactive map (cell #6). Select dates and pour points from the map, then start the process by running the cells below. At cell #8, wait for the `Process completed` message before running the rest of the cells. The resulting `NetCDF` file will be saved to your `Downloads` folder.
## Docker
To run the application using a docker container, run the following:
```
docker-compose up -d
```
To stop the container:
```
docker-compose down -f
```
The urls will look similar to the aforementioned examples with a different prefix:
```
# Generic example
http://docker-dev03.pcic.uvic.ca:30110/osprey/input/?case_id=&run_startdate=&...
# Example
http://docker-dev03.pcic.uvic.ca:30110/osprey/input/?case_id=sample&run_startdate=2011-12-01&...
```
## Run Tests
The automated tests can be run by executing the following command:
```
pytest
```