FORESEE landslide and ground motion tools

Python software for predicting landslide failures based on precipitation, ground motion data and groundwater pressure. The main outputs of this model are the identified failure locations, the timing of the failure, depth of failure and factor of safety. It makes use of lsdfailtools, a set of python-c++ tools that implement the landslide model from Iverson (2000).

Basic overview and workflow

To obtain failure locations and times, the following steps are needed.

Download or build the docker container.
Run the installation script withing the container.
Collect required data: a DEM of the area, a shapefile of the infrastructure corridor of interest, rainfall data (this can be collected using a script provided), peizometer data (where available) and ground motion data derived from radar satellites.
Run data pre-processing routines if required.
Run calibration step if required.
Run validation and/or prediction script.
Collect model outputs.

These steps are descrbed in full below.

Installation

These software scripts and packages are a combination of python and c++. The simplest way to use these tools is via our docker container, which has all the necessary python packages installed, and includes a startup script.

First, you need to install Docker on your machine using the following link https://docs.docker.com/get-docker/ (note that these instructions may need administrator privileges to run properly)

You then need to create a directory on your host computer that is visible to the docker container. In the instructions below, we use C:\LSDTopoTools but you can replace this with any directory you wish.

You can then install the lsdfailtools container one of two ways:

To build from DockerHub (recommended):

Pull the docker container from docker hub: docker pull lsdtoptools/lsdtt_failtools_docker
Create a folder into which to put all the files, then run:
docker run --rm -it -v C:/LSDTopoTools:/LSDTopoTools dockerhub/dockerhub_info
This should pull the repository along with setting up your Docker container ready for analysis
You should now be inside the Docker container at the top directory of your cloned repo ready to begin!
To escape your docker session at any point use ctrl-d
Now you need to install the software. Run the following commands:
```
python setup.py bdist_wheel
```
```
pip install dist/XXX.whl
```
Where XXX is the name of the wheel generated by the python line!
Rather than navigating to dist/ to check the name you can just autocomplete this using tab autocomplete e.g. type pip install dis then hit tab before enter
Everything is now ready to run, note you will need to follow these steps everytime you want to use the software.

To build locally from a local Dockerfile

Download the Dockerfile from https://github.com/LSDtopotools/lsdtt_failtools_docker
Place the Dockerfile in a directory then navigate there via the command line and run:
docker build --tag lsdtt_failtools_docker .

After you have built the container

Ensure that you have already cloned the lsdfailtools repository somewhere on your machine either using git from the command line or by downloading from the github website directly and unzipping it (https://github.com/LSDtopotools/lsdfailtools.git)
Then run the command

sudo docker run -it -v /path/to/your/cloned/repo:/LSDTopoTools -e NASA_USERNAME="username" -e NASA_PASSWORD="password"
Note: this requires a an account on the NASA EartData website (https://urs.earthdata.nasa.gov), make a login and password, click in Applications>Authorized Apps> Approve More Applications and select NASA GESDISC DATA ARCHIVE. This will be used in the PRECIPITATION section for downloading precipitaiton data.

MODEL DATA INPUTS

You must collect the following data before the model can be run.

Piezometer data:

.csv file with piezometer readings and the information about where they are located. They must be obtained from on-site locations or purchased.

Piezometer reading example (.csv file):

ID=unique identifier

DATE = reading date

READING NUMBER = progressive number of reading with time

FF = Depth of hole bottom

LIV = Depth of water from ground level - When the reading is 'dry' the number 999 is used

ID,DATE,READ_NUM,FF1,LIV1,FF2,LIV2,FF3,LIV3,FF4,LIV4
7,23/10/2014,0,3.7,3.5,6.2,999,6.1,999,9.6,5.5
7,24/06/2016,1,3.5,3.5,11.9,7.4,18.5,7.8,9.8,3.7
7,15/05/2017,2,3.5,3.5,11.8,7.4,18.1,7.4,9.8,3.8

Piezometer location information example (.csv file):

ID=unique identifier

NAME = Piezometer name

PROGR_KM = KP of A16 motorway from "Autostrade"

CARR = Carriageway (East or West) from "Autostrade"

LONGITUDE, LATITUDE = coordinates in decimal degrees in WGS84

ELEVATION = elevation in meters from "Autostrade"

ID,NAME,PROGR_KM,Carr,LONGITUDE,LATITUDE,ELEVATION,LENGTH
1,PzA,89+500,E,15.145169,41.090146,440,25.6
2,Pz4,89+500,E,15.144353,41.090037,447,23.8
3,Pz23,89+500,E,15.14341,41.088143,476,29.9

Precipitation data:

Obtained from the Global Precipitation Measurement Mission by NASA, which is freely available online but requires the creation of a free account in their website.

If alternative data sources are to be used instead, they must be in a .csv file, with columns indicating the duration of precipitation (s) and the precipitation intensity (mm/s).

Example:

duration_s,intensity_mm_sec
86400,0
86400,2.26E-07
86400,1.99E-06
86400,8.75E-07

Sentinel interferometry

Shapefile containing a time series of displacement derived from an ISBAS analysis of Sentinel-1 images. Projection: UTM Zone 33N Datum WGS84 (EPGS 32633).

The fields contained in the shapefile are:

EASTING, Easting coordinate in UTM Zone32N Datum WGS84 [m]
NORTHING, Northing coordinate in UTM Zone32N Datum WGS84 [m]
VEL, mean velocity of displacement [mm/year]
STDDEV_VEL, standard deviation of the mean velocity of displacement [mm/year]
Dyyyymmdd, displacement per date, where yyyy is the year, mm is the month and dd is the day of measure [mm]

Cosmo-SKYMed interferometry

Shapefiles containing a time series of displacement derived from PSP-IfSAR analysis of COSMO-SkyMed images. Ascending, descending, East-West and Vertical components required. Projection: UTM Zone 33N Datum WGS84 (EPGS 32633).

The fields contained in the shapefile are:

CODE, unique measure identification
HEIGHT, height of the measure [m]
H_STDEV, standard deviation of the height [m]
VEL, mean velocity of displacement [mm/year]
V_STDEV, standard deviation of the mean velocity of displacement [mm/year]
ACCEL, acceleration of the time series [mm/year2]
COHE, quality of the measure between 0 (low) and 1 (hight)
Dyyyymmdd, displacement per date, where yyyy is the year, mm is the month and dd is the day of measure [mm]

Area of Interest:

Polygon shapefile outlining the area of interest where the calibration and validation points will be sampled from. Required projection: EPSG 4326

Digital Elevation Model (DEM)

.bil raster file containing the elevation of the area of interest with coordinate system in EPSG:32633 (UTM zone 33N). In our case we use the EU-DEM 25 m which is obtained freely from the Copernicus Land Monitoring Service https://www.eea.europa.eu/data-and-maps/data/copernicus-land-monitoring-service-eu-dem. Alternatively, a 10m DEM can be found on the Tinitaly website http://tinitaly.pi.ingv.it/. However, other resolutions are also accepted by the model, although it will affect the calibration and validation process.

Topographic slope:

.bil raster file containing the slope of the area of interest with coordinate system in EPSG:32633 (UTM zone 33N). This file can be derived from the DEM using ArcMap or open source software such as LSDTopoTools.

Road:

line shapefile with the outline of the road of interest for the study. Required projection: EPSG:32633 (UTM zone 33N).

Monte Carlo parameters:

.csv file with the ranges of the parameters used in the Monte Carlo simulation. The first row of values corresponds to the minimum values and the second row to the maximum values.

Example file:

D_0,K_sat,Iz_over_K_steady,friction_angle,cohesion,weight_of_water,weight_of_soil,depth
0.000001,0.00000001,0.1,0.2,5000,9800,15000,0.1
0.0001,0.000001,0.8,0.5,20000,9800,25000,3

Variable names and units:

|PARAMETER NAME| UNITS| | ----------- | ----------- | |HYDRAULIC DIFFUSIVITY (D_0)| m^{2} s^{-1}| |HYDRAULIC CONDUCTIVITY (K_sat)|m s^{-1} | |STEADY STATE (LONG TERM) WATER BALANCE (IZ/KZ) (Iz_over_K_steady)|dimensionless | |TANGENT OF FRICTION ANGLE| dimensionless| |COHESION |Pa| |COLUMN WEIGHT OF THE WATER (DENSITY TIME GRAVITATIONAL ACCELERATION)| m^{-2} kg s^{-2} | |VOLUME WEIGHT OF THE SOIL (DENSITY TIME GRAVITATIONAL ACCELERATION)| m^{-2} kg s^{-2} | |SOIL COLUMN DEPTH |m|

Calibration parameters:

.csv file including the number of Monte Carlo runs (Nruns), the maximum number of iterations of the Monte Carlo process (itermax), the number of points to calibrate (Num_cal), the start (StartDate) and end date (EndDate) of the timeseries which correspond to the length of the precipitation record, and the failure interval (failinterval) which is the accepted time window (in days) to simulate acceptable failure times.