Skip to content

lfcoords

Jump to bottom
casadoj edited this page Sep 10, 2024 · 7 revisions

This tool finds the appropriate coordinates in the LISFLOOD river network of any point, provided that the catchment area is known. A thourough explanation of the method can be found in Burek and Smilovic (2023).

First, it uses the original coordinates and catchment area to find the most accurate pixel in a high-resolution map. Burek and Smilovic (2023) use MERIT (Yamazaki et al., 2019), which has a spatial resolution of 3 arc-seconds. The result of this first step is, for every point, a new value of coordinates and area, and a shapefile of the catchment polygon in high-resolution.

Second, it finds the pixel in the low-resolution grid (LISFLOOD static maps) that better matches the catchment shape derived in the previous step. As a result, for each point we obtain a new value of coordinates and area, and a new shapefile of the catchment polygon in low-resolution.

Reservoirs in LISFLOOD need to be located one pixel downstream of their actual location. This is because LISFLOOD reads the reservoir inflow from one pixel upstream of the location defined in the reservoir static map, and releases the outflow at the reservoir pixel. The tool includes a flag (-r) to specify that the input points are reservoirs; if that is the case, the output coordinates refer to one pixel downstream, i.e., they can be directly used in LISFLOOD.

Inputs

The tool requires 5 inputs:

  • A CSV file of the stations to be located in the LISFLOOD grid. This file must contain four columns with four specific names: 'ID', 'area' in km2, 'lat', 'lon'. Below you find an example of the stations CSV file:
ID,area,lat,lon
429,35399,49.018,12.144
436,26448,48.947,12.015
439,37687,48.88,12.747
  • A map of the local drainage directions in high-resolution, e.g., MERIT.
  • A map of the upstream area in high-resolution, e.g., MERIT. The units of this map must be km2, same units as the area field in the CSV file.
  • A map of the local drainage directions in low-resolution, i.e., the LISFLOOD static map.
  • A map of the upstream area in low-resolution, i.e., the LISFLOOD static map. The units of this map are m2 (instead of km2), as these are the units used in LISFLOOD; the code converts internally this map into km2.

All maps can be provided either in TIFF or NetCDF format.

Outputs

The tool saves the outputs in the folder specified in the configuration file (output_folder). Within this folder, it will create a series of shapefiles:

  • Intermediate results:

    • A point shapefile with the original location of the points. In the example, it will be named stations.shp.
    • A point shapefile with the updated location of the points in the finer grid. In the example, it will be named stations_3sec.shp.
    • A polygon shapefile with the catchments delineated in the finer grid for each of the points. In the example, it will be named catchments_3sec.shp.

  • Final results for the LISFLOOD grid:

    • A point shapefile with the updated location of the points in the LISFLOOD grid. In the example, it will be named stations_3min.shp.
    • A polygon shapefile with the catchment delineated in the LISFLOOD grid for each of the points. In the example, it will be named catchments_3min.shp.

The attribute table of the final point layer contains 6 new columns defining the coordinates and catchment area in both the high-resolution (3sec in the example) and low-resolution grids (3min in the example). Example:

ID area area_3min area_3sec lat lat_3min lat_3sec lon lon_3min lon_3sec
429 35399 35216 35344 49.018 49.025 49.022083 12.144 12.125 12.143750
436 26448 26334 26394 48.947 48.925 48.946250 12.015 12.025 12.014583
439 37687 37540 37605 48.880 48.925 48.879583 12.747 12.675 12.746250

The tool checks for conflicts in the relocation of the points both in the finer and coarser grids. If two or more points are in the same location, the tool will create another shapefile (conflicts_3min.shp in the example) with only the conflicting points, so that the user can fix the issue manually.

Configuration file

The configuration file defines the input files, the folder where the resulting shapefiles will be saved, and some thresholds used in the process. A template of the configuration file can be found here. Below you find an example:

input:
    points: points.csv # ID, lat, lon, area
    ldd_fine: ldd_MERIT.tif
    upstream_fine: uparea_MERIT.tif # km2
    ldd_coarse: ldd_LISFLOOD.tif
    upstream_coarse: uparea_LISFLOOD.nc # m2
            
output_folder: ./shapefiles/

conditions:
    min_area: 200 # km2
    abs_error: 50 # km2
    pct_error: 1 # %

Usage

In the command prompt

The tool can be executed from the command prompt by indicating a configuration file.

usage: lfcoords.py [-h] -c CONFIG_FILE -r

Correct the coordinates of a set of stations to match the river network in the
LISFLOOD static map.
First, it uses a reference value of catchment area to find the most accurate
pixel in a high-resolution map.
Second, it finds the pixel in the low-resolution map that better matches the
catchment shape derived from the high-resolution map.

options:
  -h, --help
                          show this help message and exit
  -c CONFIG_FILE, --config-file CONFIG FILE
                          path to the YML configuration file
  -r, --reservoirs
                          the input points are reservoirs

Examples

The tool can be executed from the command prompt by indicating a configuration file:

lfcoords --config-file config.yml

If the input points are reservoirs, you can use the flag -r (or --reservoirs) to get the coordinates one pixel downstream of the original result:

lfcoords --config-file config.yml -r

In a Python script

The functions that compose the lfcoords tool can be imported in a Python script to be able to save in memory the output of the two steps in the procedure:

# import functions
from lisfloodutilities.lfcoords import Config, read_input_files
from lisfloodutilities.lfcoords.finer_grid import coordinates_fine
from lisfloodutilities.lfcoords.coarser_grid import coordinates_coarse

# read the configuration file
cfg = Config(CONFIG_FILE)

# read the input files
# inputs = read_input_files(cfg)
# or any other option to read the inputs

# find coordinates in high-resolution (HR) grid
points_HR, polygons_HR = coordinates_fine(cfg,
                                          points,
                                          ldd_fine,
                                          uptream_fine,
                                          save=False)

# find coordinates in LISFLOOD
points_LF, polygons_LF = coordinates_coarse(cfg,
                                            points_HR,
                                            polygons_HR,
                                            ldd_lisflood,
                                            upstream_lisflod,
                                            reservoirs=False,
                                            save=False)
Clone this wiki locally