search

matthiasdemuzere / w2w

A python tool that ingests WUDAPT information into WRF.
MIT License
40 stars 16 forks source link

readme

ci pre-commit.ci status DOI

w2w.py

A WUDAPT-to-WRF python tool that injects WUDAPT's Local Climate Zone information into WRF.

Install

pip install w2w

Install from GitHub:

pip install git+https://github.com/matthiasdemuzere/w2w

Run the tool

  1. Check out its help:

    w2w --help

  2. Try with the provided sample:

    Sample data used here can be downloaded from the repository in the sample_data folder. After clicking on the file you can download it.

    w2w ./sample_data lcz_zaragoza.tif geo_em.d04.nc

  3. Deploy using your own data:

    w2w INPUT_DIRECTORY YOUR_LCZ.TIF YOUR_GEO_EM.dXX.NC

    Output

    The original files are not modified. Three new files are generated by w2w:

    • geo_em.d04_NoUrban.nc: Urban areas are replaced with the dominant surrounding rural land use.
    • geo_em.d04_LCZ_extent.nc: The extension of urban areas is updated using LCZ.
    • geo_em.d04_LCZ_params.nc: Urban areas are described using three different urban density categories.

    Differences between the original file and the newly created files by w2w are shown below for the sample data provided.

before and after Fig.1: w2w results on sample data. Land use categories from the original file (a), the params file (b), the extent file (d) and the NoUrban (f). Pixels replaced with respect to the original file in params (c), extent (e) and NoUrb (g).

A sample Jupyter notebook is provided to recreate this Figure but is not part of the package, thus additional modules are required to run it.

Requirements

  1. A geo_em.dXX.nc file (produced by WRF's WPS geoegrid.exe), for the inner WRF model domain in which you would like to use the LCZ-based information.

  2. A Local Climate Zone map (lcz.tif) that is slightly bigger than the domain of the geo_em.d0X.nc file. There are a number of ways to obtain an LCZ map for your region of interest:

    • Extract your domain from the continental-scale LCZ maps for Europe (Demuzere et al., 2019) or the United States (Demuzere et al., 2020). For more information, see here. Make sure you use the version ending with _epsg4326.tif.
    • Check if your region of interest is already covered by the many LCZ maps available in the LCZ Generator submission table.
    • Use the LCZ Generator to make an LCZ map for your region of interest. In case the geo_em.d0X.nc domain is larger than ~ 2.5 x 2.5°, the LCZ Generator will fail. In that case, please contact Matthias Demuzere for support.

Important notes

Arguments

-b --built-lcz = LCZ classes considered as urban (DEFAULT: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-l --lcz-band = Band to use from LCZ file (DEFAULT: 0). For maps produced with LCZ Generator, use 1
-f --frc-threshold = FRC_URB2D threshold value to assign pixel as urban (DEFAULT: 0.2)
-n --npix-nlc = Number of pixels to use for sampling neighbouring natural land cover (DEFAULT: 45)
-a --npix_area = Area in number of pixels to look for the NPIX_NLC nearest number of pixels for sampling neighbouring natural land cover (DEFAULT: NPIX_NLC**2)
--lcz-ucp = Specify a custom lookup table for the LCZ-based Urban Canopy Parameters
   ,FRC_URB2D ,MH_URB2D_MIN ,MH_URB2D ,MH_URB2D_MAX ,BLDFR_URB2D ,H2W
1  ,0.95      ,25           ,50       ,75           ,0.5         ,2.5
2  ,0.9       ,10           ,17.5     ,25           ,0.55        ,1.25
3  ,0.85      ,3            ,6.5      ,10           ,0.55        ,1.25
4  ,0.65      ,25           ,50       ,75           ,0.3         ,1
5  ,0.7       ,10           ,17.5     ,25           ,0.3         ,0.5
6  ,0.6       ,3            ,6.5      ,10           ,0.3         ,0.5
7  ,0.85      ,4            ,5        ,6            ,0.75        ,1.5
8  ,0.85      ,3            ,6.5      ,10           ,0.4         ,0.2
9  ,0.3       ,3            ,6.5      ,10           ,0.15        ,0.15
10 ,0.55      ,5            ,10       ,15           ,0.25        ,0.35
11 ,0         ,0            ,0        ,0            ,0           ,0
12 ,0         ,0            ,0        ,0            ,0           ,0
13 ,0         ,0            ,0        ,0            ,0           ,0
14 ,0         ,0            ,0        ,0            ,0           ,0
15 ,0.95      ,0            ,0        ,0            ,0.05        ,0
16 ,0         ,0            ,0        ,0            ,0           ,0
17 ,0         ,0            ,0        ,0            ,0           ,0

Background context

An important objective of WUDAPT, the World Urban Database and Access Portals Tools community project, is to generate urban canopy information and provide the (open-source) tools to facilitate urban-focused modelling studies (Ching et al., 2018).

Since the work of Brousse et al. (2016), the level-0 WUDAPT information, the Local Climate Zone maps, have been used increasingly in WRF, the community “Weather Research and Forecasting” model. Their original guide and code on how to use WUDAPT information into WRF (originally designed for WRF v3.2) is available here. Note that this tool was first assigning the LCZ mode to each WRF grid cell, and only afterwards assigning corresponding morphological, radiative and thermal properties to this modal LCZ class. This is done differently in w2w, see below.

As of spring 2021, WRF v4.3.x is able to ingest LCZ information by default (previous versions required manual WRF code changes by the user). See more details on "Updates of WRF-urban in WRF 4.3: Local Climate Zones, Mitigation Strategies, building materials permeability and new buildings drag coefficient" here. Because of this, we decided to simultaneously built an improved WUDAPT-to-WRF routine, to make the translation of LCZ-based parameters better and simpler. As before, the LCZ-based urban canopy parameters generally follow the values provided by Stewart and Oke (2012) and Stewart et al. (2014).

The procedure in this new w2w tool is different from the former tool. Morphological parameters are assigned directly to the high-resolution LCZ map, and only afterwards aggregated to the WRF grid. In this way, the method produces a unique value of the different urban morphology parameters for each model cell. This was found to be more efficient in reproducing urban boundary layer features, especially in the outskirts of the city (Zonato et al., 2020), and is in line with the WUDAPT-to-COSMO routine (Varentsov et al., 2020). Other radiative and thermal parameters are for now still assigned to the modal LCZ class. More details on the procedure and its assumptions will soon be available here.

How to cite?

Demuzere, M., Argüeso, D., Zonato, A. and Kittner, J. (2022). W2W: A Python package that injects WUDAPT's Local Climate Zone information in WRF. Journal of Open Source Software, 7(76), 4432, DOI: 10.21105/joss.04432.

License

The project is licensed under the MIT license.

Contributing

Contributions to w2w are welcome! This is how:

Running the tests

The project uses tox to check the package installs correctly and all tests pass on different versions of python. The tests can be run using:

pytest can also be used directly:

  1. install the package in the current virtual environment (-e editable install) 
    pip install -e .
  2. install the development dependencies 
    pip install -r requirements-dev.txt
  3. run pytest 
    pytest

Artists

Credits