Term project: the WRFvis package

Term project: the WRFvis package#

updated by M. Lehner (new semester project WRFvis)

This is the main project of the semester and will count for 30% of the final grade. The submission is going to happen in three stages:

  • Feedback presentations: end of November/beginning of December Individual meetings with each group to receive some feedback. You will show me the structure of your package, the functionality of your code, which tests you are writing, who is writing what, a sample docstring, etc. You will also submit a first version of your WRFvis package (one .zip file per group) at least 24 h before our meeting so that I can test it.

  • Class presentations: Friday, 13 December 2024: Every group will briefly present their project to show what it can be used for. This is not graded. The goal is to simply share your amazing project ideas with the whole class.

  • Final submission: Friday, 20 December 2024 at 24:00. One .zip file per group containing your version of the WRFvis package .

Here is a tentative grading rubric.

Group grade (10 points):

  • Originality: 1 (did you do something more than following the list of suggestions)

  • Functionality of the code: 1 (can the package be installed and run on my computer)

  • Documentation: 2 (joint project documentation)

  • Traceability: 1 (who did what, are the author(s) name(s) provided in the function’s docstrings)

  • Coherence: 2 (how do the individual contributions fit together)

  • Integration tests: 2 (tool / project level tests)

  • Response to feedback: 1 (response to the received feedback)

Individual grade (10 points):

  • Narrative self-report: 1 (quality and honesty of the self-report)

  • Complexity: 3 (level and complexity of the implemented tools, i.e., the amount of programming work)

  • Functionality of the code: 1 (is your individual contribution running and doing what it is supposed to do)

  • Unit tests: 2 (individual function tests)

  • Documentation: 2 (Individual contributions’ docstrings and comments)

  • PEP8: 1 (compliance to pep8)

Important

I will try and test the code (using pytest) on my computer - any new data or library that is necessary should be documented in the code, or in the command line utility documentation!

The WRFvis package#

I have put together a small package called WRFvis. Its design is based on the template package and the ClimVis package written by Fabien Maussion.

Download the zipped package from here and extract it. Read the README and the package requirements first.

Now install wrfvis in development mode. If you are working on your own computer run:

pip install -e .

from the root directory. If you are working on a computer on which you have no admin rights, run:

pip install --user -e .

instead.

Try the command line interface (wrfvis_gridcell -h) from a terminal. Now explore setup.py: can you identify what makes the command available from the terminal? Where is the code executing the command wrfvis_gridcell?

Familiarize yourself with the tool. Can you understand what the role of each function is?

Can you run the tests successfully? Probably not. Somewhere in cfg.py, a hard coded path is pointing to a non-existing directory.

You can access an example WRF dataset here. Working with the dataset might be faster if you download it to your computer or to an external hard disk, but the file is rather large (about 12 GB). Because of the large file size, running all the tests may also take some time. The WRF output comes from a simulation of a cold-air pool on the Seefeld Plateau (https://zenodo.org/records/13842030).

Make sure you are able to run the command succesfully before going on. For example, wrfvis_gridcell -p T -l 11 45 200 should work fine and display a page in your browser. But remember that it will take some time because of the file size.

Some information about WRF model output#

The goal of WRFvis is to visualize output from the WRF numerical weather prediction model.

Some of the WRF output variables are perturbation variables. To get physically meaningful values, you need to perform some calculations, for example, adding two output variables. Potential temperature is such an example. Have a look at the wrfvis code and find the line, where the timeseries of full potential temperature is calculated.

WRF uses a so-called Arakawa-C grid (see, e.g., Fig. 3 in this publication), where mass-related variables (e.g., pressure and temperature) are defined at the center of the grid cells and the wind components in the center of the respective faces of the grid cell. The dimensions of the variable T are thus (Time, bottom_top, south_north, west_east), of U (Time, bottom_top, south_north, west_east_stag), of V (Time, bottom_top, south_north_stag, west_east), and of W (Time, bottom_top_stag, south_north, west_east). The length of the staggered dimension (e.g., bottom_top_stag) is always longer by one element than the unstaggered dimension (e.g., bottom_top). Have a look at the wrfvis code and find where the geopotential height (with dimension bottom_top_stag) is unstaggered in the vertical direction. To calculate the horizontal wind components at the mass grid points, you thus need to unstagger them similarly to the geopotential height in the vertical direction. Alternatively, there are also staggered longitude (XLONG_U and XLONG_V) and latitude (XLAT_U and XLAT_V) arrays in the model output.

If you are interested, there is more information in the WRF user manual, including a description of possible output variables.

Guided exercise: make the tool more robust#

Here are a couple of smaller tasks to get you started:

  • Add a safety check in the code to make sure that the WRF output file specified in cfg.py actually exists. If the data file does not exist, print the following message and exit the program:

    The specified WRF output file does not exist. Please set a valid path in cfg.py.

  • The current implementation extracts the model timeseries from the grid point closest to the specified longitude and latitude and the vertical model level closest to the specified height above ground. This works fine for 3D variables, but not for 2D surface variables (e.g., radiation, sensible heat flux, …). Add a check whether the user-specified parameter refers to a 2D variable and if so, adjust the code to extract the timeseries correctly.

Hint: 2D variables have only 3 dimensions (time, longitude, latitude) and no height dimensions (top_bottom or top_bottom_stag).

Project: make the package better#

Now you should be ready to contribute to this great package! Add at least N+1 simple functionalities to it, where N is your group size. This functionality can be anything you want, as long as it makes you write some code.

Here are some ideas of functionalities that you can adapt at wish.

  • You could use the python windrose package to plot a windrose from the gridcell data instead of the time series (see above for working with wind data from the WRF output).

  • You could add a new command line tool to plot vertical profiles instead of timeseries from a single grid cell.

  • You could expand the tool for plotting vertical profiles to produce a Skew-T diagram.

  • You could add a new command line tool to plot horizontal or vertical cross sections.

  • You could add the possibility to plot derived parameters that are calculated from the parameters in the WRF output.

  • You could add the possibility to plot multiple timeseries from different grid points in a single plot for comparison.

  • Come up with your own ideas that interest you!

Expectations#

In addition to the joint package, each group member and the entire group needs to write a short narrative self-report (a few lines per point) addressing the following points:

  • What task was assigned to you when you started?

  • What changed during the implementation, that is, what is the outcome of the project?

  • What was the biggest challenge you faced in the implementation?

  • Group question: what was the biggest challenge when merging everyone’s work into one package?

The narrative report should be written in markdown format, and will count towards your individual grade.

Some tasks in the list above are simpler than others. There is no threshold on the number of lines of code, because producing many lines of code is not a measure of quality. The goal is that you get better at programming during the project, regardless of your starting level.

The list of possible topics should help you decide on what to code, but aside from that here is a vague rule of thumb: if you coded 10 lines of code (without comments), it is probably not enough (unless they are very clever lines of code). If you coded 1000 lines of code, it is probably too much.

It is okay to select an easy task, as long as you write something on your own, and write good code. The difficulty of the task will, however, influence the grade in addition to the quality of the code and the tests. If you pick an “easy” task, you could also pick two or three tasks instead of just one. Try to split the tasks within the group to get a coherent product!

You all have very different backgrounds and interest. Try to find a project you like, and convince me that you pushed your own programming limit a little bit and that you learned something in the process.

Ah! And don’t forget to write tests.

Contents