diff --git a/README.md b/README.md index 09434cf9b70a37d616faa0d388892bf24942d7d9..ef79c15e5abeb52821815a96e4414fb6ab2be4b6 100644 --- a/README.md +++ b/README.md @@ -31,18 +31,16 @@ <br /> <div align="center"> <a href="https://git-ce.rwth-aachen.de/mbd/shire.git"> - <img src="images/Logo.png" alt="Logo" width="680" height="160"> + <img src="images/Logo.png" alt="Logo" width="680" height="165"> </a> <!--<h3 align="center">Shire</h3> --> <p align="center"> - project_description + <a href="https://git-ce.rwth-aachen.de/mbd/shire.git/docs"><strong>Explore the docs »</strong></a> <br /> - <a href="https://github.com/github_username/repo_name"><strong>Explore the docs »</strong></a> <br /> - <br /> - <a href="https://github.com/github_username/repo_name">View Demo</a> + <a href="https://github.com/github_username/repo_name">View Publication</a> · <a href="https://github.com/github_username/repo_name/issues">Report Bug</a> · @@ -134,87 +132,10 @@ and then install the prerequisites in requirement.txt pip install -r /path/to/requirements.txt ``` -## How to use Shire - -### Gui version -#### Necessary manual preparations - -keys_to_include-file: - - format: csv-file - - list of feature names to be included as features in the mapping processing - - feature names have to match feature names provided in the data_summary-file - -data_summary-file: - - format: csv-file - - table with the columns providing information on path where the dataset is stored, feature name, list of no data values, boolen parameter whether the dataset is categorical - - no column headers should be included - - all fields have to be provided - -#### Running Shire - -Shire can be intuitively started by running shire.py which launches the gui. The gui queries important user-defined parameters and data-specific information in order to then automatically create training and prediction datasets and/or create the susceptibility map using existing input datasets. - -The initial window (see Fig. 1) covers the basic information on the resulting map: -Fig.1: GUI for defining the general settings for the mapping project - -- _What do you want to do?_: Here it can be defined what should be done in this run. The options can either be ticked individually or in various combinations. _Training dataset_ and _prediction dataset_ launch the training and prediction dataset generation, _Map generation_ launches the susceptibilty map generation using already existing input datasets -- _General settings_: _Resolution_ defines the resolution of the final map in meters, _No data value_: defines the value that shall be used as the value for missing data, e.g. -999, _CRS_ defines the coordinate reference system that should be saved as metadata along with the map such as wgs84, _Random seed_ defines the value to be used as random seed -- _Save the settings for later use_: if ticked, as soon as the _submit_ button is pressed, a window is opened to choose the path to save the settings for later use as a pickle file. It will be saved as "settings.pkl" -- _Import settings_: if during a previous run the settings defined in this window have been entered and saved, this button allows to load the previous settings to save time - -If in the general settings window the _prediction dataset_ option has been ticked the following window opens: -| GUI when ticking the delete feature or add feature tickbox | GUI when ticking the Generate dataset from scratch | -| ---------------------- | ---------------------- | -| | | -- _Where is your geospatial data stored?_: Here, the path to the csv file needs to be given which provides information on the geospatial data (see Necessary manual preparations above) -- _Feature names_: the path to the list of features to include in the training dataset generation needs to be specified -- _Where do you want the prediction data to be stored?_: A directory can be chosen in which the prediction dataset will be saved. The dataset is stored as a netCDF4 file with the name "prediction.nc". More information on what the netCDF4 file contains can be found below -- _Information on the area of intrest_: under the four _Bounding box_ input boxes _West_, _East_, _North_ and _South_ the boundaries of the area of interest need to be given in decimal degree. -- _Save the settings for later use_: if ticked, as soon as the _submit_ button is pressed, a window is opened to choose the path to save the settings for later use as a pickle file. It will be saved as "settings_pred.pkl" -- _What do you want to do?_: This setting defines how the prediction dataset is generated. _Generate the prediction dataset from scratch_ assumes that no prediction dataset in the directory given above is available to build upon, _Delete feature_ assumes that there is a prediction dataset from which one or several freatures shall be dropped, _Add feature_ assumes there is a prediction dataset to which one or several features shall be added -- If _Delete feature_ or _Add feature_ has been chosen _Which features do you want to add/delete?_ defines which features to add or delete. If there are several, they should be seperated with a comma. Please don't include spacing! -- If _Delete feature_ or _Add feature_ has been chosen _How would you like to preprocess the datasets?_ defines how the features that have been added in the inbox above. Options are 'no_interpolation', 'cluster' and 'interpolation'. Their meaning is described more closely below. For each of the features to add/delete one preprocessing option can be specified which are comma-separated. Please don't include spacing! -- _Import settings_: if during a previous run the settings defined in this window have been entered and saved, this button allows to load the previous settings to save time - -If in the general settings window the _training dataset_ option has been ticked the following window opens: -| GUI when ticking the delete feature or add feature tickbox | GUI when ticking the Generate dataset from scratch | -| ---------------------- | ---------------------- | -| | | - -- _Where is your landslide data stored_: The path to the landslide inventory needs to be given here -- _Where is your geospatial data stored?_: Here, the path to the csv file needs to be given which provides information on the geospatial data (see Necessary manual preparations above) -- _Feature names_: the path to the list of features to include in the training dataset generation needs to be specified -- _Where are your absence locations stored?_: The path to the absence locations needs to be given. For more information see necessary manual preparations -- _Where do you want your training data to be stored?_: Choose a directory to store the training dataset. The file is stored in csv format and is called 'training.csv'. More information on the resulting file can be found below. -- _Import settings_: if during a previous run the settings defined in this window have been entered and saved, this button allows to load the previous settings to save time --_Information on the landslide data_: To allow for individual landslide and absence locations inventories information on naming conventions need to be provided here. _x coordinates_ and _y coordinates_ require the labels in the landslide inventory and the absence locations inventory respectively for the x and y coordinates. _Landslide ID_ requires the label for the landslide ID. -- _Number of absence locations_: This defines the number of absence locations included in the training dataset. Please follow the recommendations in the Necessary manual preparations section -- _Save the settings for later use_: if ticked, as soon as the _submit_ button is pressed, a window is opened to choose the path to save the settings for later use as a pickle file. It will be saved as "settings_train.pkl" -- _What do you want to do?_: This setting defines how the training dataset is generated. _Generate the training dataset from scratch_ assumes that no training dataset in the directory given above is available to build upon, _Delete feature_ assumes that there is a training dataset from which one or several freatures shall be dropped, _Add feature_ assumes there is a training dataset to which one or several features shall be added -- If _Generate training dataset from scratch_ is chosen, _How shall the training dataset be compiled?_ can be determined. The options are 'Clustering', 'Interpolation' and 'No interpolation'. More information can be found below -- If _Delete feature_ or _Add feature_ has been chosen _Which features do you want to add/delete?_ defines which features to add or delete. If there are several, they should be seperated with a comma. Please don't include spacing! -- If _Delete feature_ or _Add feature_ has been chosen _How would you like to preprocess the datasets?_ defines how the features that have been added in the inbox above. Options are 'no_interpolation', 'cluster' and 'interpolation'. Their meaning is described more closely below. For each of the features to add/delete one preprocessing option can be specified which are comma-separated. Please don't include spacing! -- _Import settings_: if during a previous run the settings defined in this window have been entered and saved, this button allows to load the previous settings to save time - -If in the general settings window the _Map generation_ option has been ticked the following window opens: -Fig.4: GUI for defining the settings for the map generation - -- _Path to training dataset_: The path to the existing training dataset needs to be provided -- _Path to prediction dataset_: The path to the existing prediction dataset needs to be provided -- _Where do you want the model to be stored?_: The path needs to be provided where the model shall be stored -- _Features to drop - training_ and _Features to drop - prediction_: If applicable list features that are included in the training or prediction dataset respectively that shall not be considered during training and prediction. If several features shall be dropped, seperate them with a comma. Please don't use spacing after the comma! -- _Model to save_ and _Model to load_: Name of the folder in which the model shall be stored. It should not be generic so that specific models can be imported at a later point in time again. If training and mapping is conducted in one go, both parameters are typically the same. -- _Save above settings for later use_: if ticked, as soon as the _submit_ button is pressed, a window is opened to choose the path to save the settings for later use as a pickle file. It will be saved as "settings_map.pkl" -- _What do you want to do?_: _Model training_ and _Mapping_ can be conducted in one go by ticking both boxes but can also performed independently. -<!-- ROADMAP --> -## Roadmap - -- [ ] Feature 1 -- [ ] Feature 2 -- [ ] Feature 3 - - [ ] Nested Feature - -See the [open issues](https://github.com/github_username/repo_name/issues) for a full list of proposed features (and known issues). +## How to use SHIRE + +SHIRE is available as plain python code (called Plain version) or as a version with user interface (called GUI version). +Please refer to the documentation in Docs which summarises all necessary preperatory steps for both versions, explains settings and options and describes the output files of the framework. <p align="right">(<a href="#readme-top">back to top</a>)</p> @@ -249,10 +170,11 @@ Distributed under the MIT License. See `LICENSE.txt` for more information. <!-- CONTACT --> ## Contact +If you have questions or comments please feel free to reach out to: -Your Name - [@twitter_handle](https://twitter.com/twitter_handle) - email@email_client.com +Ann-Kathrin Edrich - edrich@mbd.rwth-aachen.de -Project Link: [https://github.com/github_username/repo_name](https://github.com/github_username/repo_name) +Project Link: [KISTE Project](https://kiste-project.de/) <p align="right">(<a href="#readme-top">back to top</a>)</p> @@ -261,9 +183,8 @@ Project Link: [https://github.com/github_username/repo_name](https://github.com/ <!-- ACKNOWLEDGMENTS --> ## Acknowledgments -* []() -* []() -* []() +* We acknowledge the funding through the German Federal Ministry for the Environment, Nature Conservation, Nuclear Safety and Consumer Protection under grant no 67KI2043 (KISTE project). +* This work was performed as part of the Helmholtz School for Data Science in Life, Earth and Energy (HDS-LEE) <p align="right">(<a href="#readme-top">back to top</a>)</p>