Merge pull request #1 from helioforecast/master

Merging updates

Author: bairaelyn

.gitignore

@@ -1,4 +1,15 @@
 __pycache__
 results
+real
+data
+build
+dist
+predstorm.egg*
 sta_beacon
+predstorm/spice/kernels/*
 *.png
+*.pickle
+*.log
+omni2*.*
+.DS*
+predstorm_real*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 IWF-helio
+
+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.

README.md

@@ -1,64 +1,58 @@
 # PREDSTORM
 
-This is a python code for space weather prediction research.
+This is Python3 code for space weather prediction research.
 
-The package is used for research on predicting the background solar wind, 
-high speed solar wind streams and solar storm magnetic flux ropes, 
-based on data from solar wind monitors at the Sun-Earth L1 and L5 points, 
-as well as from any spacecraft positioned east of the Sun-Earth line around or < 1 AU.
-We also derive predictions of the geomagnetic Dst index, Kp and auroral power.
+The package is used for predicting the background solar wind, high speed solar wind streams and solar storm magnetic flux ropes based on data from solar wind monitors at the Sun-Earth L1 and L5 points, as well as from any spacecraft positioned east of the Sun-Earth line around or < 1 AU. We also derive predictions of the geomagnetic Dst index, Kp and auroral power.
 
-Status: work in progress, 9 April 2019.
+Status in 2019: work in progress.
 
-If you want to use parts of these codes for generating results for 
-peer-reviewed scientific publications, please contact us per email (see contributor biographies)
-or via twitter @chrisoutofspace (Christian Moestl).
+If you want to use parts of this code for generating results for peer-reviewed scientific publications, please contact us per email (see contributor biographies) or via twitter @chrisoutofspace (Christian Moestl).
 
-## Dependencies
+## Installation
 
-To install the packages that need to be added to an existing anaconda python3 installation (https://www.anaconda.com/distribution/), 
+PREDSTORM is written in Python 3. Most dependencies (numpy, scipy, matplotlib) can be downloaded and used in an anaconda environment (https://www.anaconda.com/distribution/) and can be installed using the following lines:
 
-* sunpy (https://github.com/sunpy/sunpy), cdflib (https://github.com/MAVENSDC/cdflib),
+	  conda install scipy numpy matplotlib scikit-learn seaborn requests-ftp beautifulsoup4
+	  conda install -c conda-forge spiceypy cftime
+	  conda install -c numba numba
 
-use this on a command line:
+Remaining dependencies (particularly those for CDF handling) can be downloaded using pip:
 
-```
-conda config --append channels conda-forge
-conda install sunpy
-pip install cdflib
-```
+    pip install cdflib spacepy astropy
 
-* predstorm_l5.py checks for an ffmpeg (for converting images, making movies) executable 
-in the current directory, otherwise the system-wide available version is used.
+PREDSTORM also relies on the HelioSat package for all heliospheric data downloads and SPICE kernel handling. Currently it can be downloaded from GitHub:
+
+    git clone https://github.com/IWF-helio/HelioSat.git
+    cd HelioSat
+	  python setup.py install
+
+HelioSat automatically downloads kernels and all required satellite files (e.g. STEREO, DSCOVR, ...). To set the path where these files are downloaded to, set the following environment variable (in .bashrc on Linux, .bash_profile on Mac):
+
+    export HELIOSAT_DATAPATH="/path/to/data/heliosat"
+    
+It's a good idea to import the package after first installation to handle first download of all required SPICE kernels.
 
 ## Running the code
 
-* On the command line:
+In the command line:
 
-```
-python predstorm_L1.py
-python predstorm_L5.py
-python mfr_predict.py
-```
+    python predstorm_l1.py
+    python predstorm_l5.py
 
-* use 
-```
-python predstorm_L5.py --server 
-```
-for Agg backend. 
+Use the following option for the Agg backend in matplotlib:
 
-* In ipython:
+    python predstorm_l5.py --server 
 
-```
-run predstorm_l1
-run predstorm_l5
-run mfr_predict
-```
+### Notes
 
+* Running the scripts creates the local folder /data. OMNI2 data, among other things, are automatically downloaded into this folder.
 
+* Results are saved in the folder /results.
 
-* Folder "data/" contains a position file for planets and spacecraft 
-(to be replaced with positions in spiceypy/heliopy) and an unpublished v2.0 of the HELCATS ICME catalog.
-OMNI2 data are automatically downloaded in this folder.
+* Logs of the scripts are saved in predstorm.log.
 
+## Contributors
 
+IWF-Helio Group, Space Research Institute (ÖAW), Graz, Austria:
+* Christian Möstl
+* Rachel L. Bailey