Metadata-Version: 2.1
Name: whakaari
Version: 0.0.1
Summary: Whakaari Forecast Modelling
Project-URL: Homepage, https://github.com/martanto/whakaari
Project-URL: Issues, https://github.com/martanto/whakaari/issues
Author-email: David Dempsey <d.dempsey@auckland.ac.nz>
Maintainer-email: Martanto <martanto@live.com>
License: MIT License
        
        Copyright (c) 2020 David Dempsey
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: forecast,modelling,volcano,volcanoes,whakaari
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.7.6
Requires-Dist: corner==2.0.1
Requires-Dist: imbalanced-learn==0.6.1
Requires-Dist: joblib==0.14.0
Requires-Dist: numpy==1.18.1
Requires-Dist: obspy==1.1.0
Requires-Dist: openpyxl==3.1.3
Requires-Dist: pandas==0.25.3
Requires-Dist: scikit-learn==0.22
Requires-Dist: scipy==1.3.1
Requires-Dist: statsmodels==0.10.2
Requires-Dist: tsfresh==0.16.0
Description-Content-Type: text/markdown

# Whakaari
Eruption forecast model for Whakaari (White Island, New Zealand). This model implements a time series feature engineering and classification workflow that issues eruption alerts based on real-time tremor data. This is the real-time version for running on a VM with html forecaster output and email alerting.

## Installation

Ensure you have Anaconda Python 3.7 installed. Then

1. Clone the repo

```bash
git clone https://github.com/ddempsey/whakaari
```

2. CD into the repo and create a conda environment

```bash
cd whakaari

conda env create -f environment.yml

conda activate whakaari_env
```

The installation has been tested on Windows, Mac and Unix operating systems. Total install with Anaconda Python should be less than 10 minutes.

## Running models
Three examples have been included in ```scripts/forecast_model.py```. 

The first, ```forecast_test()``` trains on a small subset of tremor data in 2012 and then constructs a forecast of the Aug 2013 eruption. It will take about 10 minutes to run on a desktop computer and produces a forecast image in ../plots/test/forecast_Aug2013.png

The second, ```forecast_dec2019()``` trains on tremor data between 2011 and 2020 but *excluding* a two month period either side of the Dec 2019 eruption. It then constructs a model 'forecast' of this event. It could take several hours or a day to run depending on the cpus available for your computer.

The third, ```forecast_now()```, is an online forecaster. It trains a model on all data between 2011 and 2020 *including* the Dec 2019 eruption. It then downloads the latest Whakaari tremor data from GeoNet and constructs a forecast for the next 48 hours. See associated paper for guidance on interpreting model consensus levels. The model may take several hours or a day the first time it is constructed, but subsequent updates should be quick.

To run the models, open ```forecast_model.py```, comment/uncomment the forecasts you want to run, then in a terminal type
```bash
cd scripts

python forecast_model.py
```

## Disclaimers
1. This eruption forecast model is not guaranteed to predict every future eruption, it only increases the likelihood. In our paper, we discuss the conditions under which the forecast model is likely to perform poorly.

2. This eruption forecast model provides a probabilistic prediction of the future. During periods of higher risk, it issues an alert that an eruption is *more likely* to occur in the immediate future. At present, our best estimate is that when an alert is issued at 80% consensus there is a 1 in 12 chance of an eruption occurring. On average, alerts last about 5 days. Eruption probability and average alert length could change depending on which eruptions are used to train the model.

3. This software is not guaranteed to be free of bugs or errors. Most codes have a few errors and, provided these are minor, they will have only a marginal effect on accuracy and performance. That being said, if you discover a bug or error, please report this at [https://github.com/ddempsey/whakaari/issues](https://github.com/ddempsey/whakaari/issues).

4. This is not intended as an API for designing your own eruption forecast model. Nor is it designed to be especially user-friendly for Python/Machine Learning novices. Nevertheless, if you do want to adapt this model for another volcano, we encourage you to do that and are happy to answer queries about the best way forward. 

## Acknowledgments
This eruption model would not be possible without real-time seismic data streaming from Whakaari via GeoNet.

