Package: iconarray
iconarrayIntroductionThe iconarray python package contains various modules to facilitate working with ICON data with xarray or other xarray based tools (such aspsyplot- a plotting package). The package was developed together withicon-vis.API Documentation:https://c2sm.github.io/iconarrayTable of contentsIntroductionInstallation and SetupModulesFormatoptionsContactsInstallation and SetupIconarray and the packages it depends on are installable with conda. Some of these dependencies, e.g. eccodes and cartopy are not easily installable with pip, but easily installable with conda.First clone the iconarray repository andcdinto its parent directory:gitclonegit@github.com:C2SM/iconarray.gitcdiconarrayIf you are setting up anew conda environmentfor iconarray, carry out these two steps:Create a conda environment (e.g. called iconarray) and install iconarray and its requirements:condaenvcreate-niconarray-fenv/environment.ymlActivate environment:condaactivateiconarrayAlternatively if you are adding iconarray to yourexisting conda environment, carry out these two steps:Update your existing conda environment by executing this command. It will install all missing dependencies of iconarray into your existing conda environment:condaenvupdate-n{YOUR_ENVIRONMENT}-fenv/environment.ymlYou can then re-export an updatedenvironment.ymlfile of your environment:condaactivate{YOUR_ENVIRONMENT}condaenvexport|grep-v"^prefix: ">environment.ymlAlternatively, you can also update your own environment.yml file manually, according toenv/environment.yml.ICON GRIB DefinitionsIf you are using the conda setup and want to use GRIB data, you probably need to set theGRIB_DEFINITION_PATH. The GRIB_DEFINITION_PATH environment variable can be configured in order to use local definition files (text files defining the decoding rules) instead of the default definition files provided with eccodes. This can be done by sourcing the script setup-conda-env.sh. It only needs to be run a single time, as it will save theGRIB_DEFINITION_PATHenvironment variable to the conda environment. You will need to deactivate and reactivate the conda environment after doing this. You can check it has been correctly set by runningconda env config vars list../env/setup-conda-env.shThe above script also sets the Fieldextra installation path (FIELDEXTRA_PATH). Fieldextra is a tool which can be used for interpolating data to another grid (lon/lat or another ICON grid). The use of this specific installation of Fieldextra depends on your CSCS access rights, so you may need to changeFIELDEXTRA_PATHif you have problems interpolating.ModulesThere are a number ofmoduleswhich are part of theiconarraypackage (installed by conda usingenv/environment.yml), which you can import like a normal python package into your scripts. To work with the modules from iconarray, you can add this code block to the start of your script / notebook. You will see many examples of the modules being used within the scripts in this repo.importiconarray# import iconarray modulesfromiconarray.plotimportformatoptions# import plotting formatoptions (for use with psyplot)Then you can use the functions or modules as needed, eg:iconarray.get_example_data()Grid -backend/grid.pycombine_grid_information()This adds the required grid information from a provided grid file to your dataset if not present. It also adds coordinates encoding to each variable, which is needed to plot using psyplot.check_grid_information()Checks whether or not the grid data needs to be added. eg:ifcheck_grid_information(nc_file):print('The grid information is available')data=psy.open_dataset(nc_file)else:print('The grid information is not available')data=combine_grid_information(nc_file,grid_file)Utilities -core/utilities.pyind_from_latlon()Returns the nearest neighbouring index of lat-lon within given lats-lons.add_coordinates()Returns the position of given coordinates on the plot (useful to add markers at a fixed location).get_stats()Returns the mean of two given variables, the difference of the mean and the p values.wilks()Returns a value for which differences are significant when data point dependencies are accounted for (based onWilks 2016).show_data_vars()Returns a table with variables in your data. The first column shows the variable name psyplot will need to plot that variable.
This is useful if you plot GRIB data, because ifGRIB_cfVarNameis defined, cfgrib will set this as the variable name, as opposed toGRIB_shortNamewhich you might expect.Interpolate -core/interpolate.pyThe functions in interpolate.py are used to facilitate the interpolation of ICON vector data to a regular grid, or a coarser ICON grid, for the purpose of vectorplots, eg wind plots. For psyplot we recommend to plot wind data on the regular grid as you can then scale the density of arrows in a vector plot as desired.remap_ICON_to_ICON()This calls the_create_remap_nl()function to create a fieldextra namelist with your datafile, and subsequently runs fieldextra with this namelist. The output file along with a LOG and the namelist are saved in atmpfolder. The function returns the file location of the output file.remap_ICON_to_regulargrid()This calls the_create_remap_nl()function to create a fieldextra namelist with your datafile, and subsequently runs fieldextra with this namelist. The output file along with a LOG and the namelist are saved in atmpfolder. The function returns the file location of the output file.FormatoptionsPsyplot has a large number of ‘formatoptions’ which can be used to customize the look of visualizations. For example, the descriptions of the formatoptions associated with the MapPlotter class of psyplot can be found in thepsyplot documentation. The documentation for using formatoptions is also all on the psyplot documentation, or seen in theexamples.Psyplot is designed in a way that is very modular and extensible, allowing users to easily create custom formatoptions and register them to plotters. Instructions for doing so arehere.This repository includes various custom formatoptions, that are not included in psyplot. For example:Borders- Adds internal land borders to mapplot, vectorplots, and combinedplots.Rivers- Adds rivers to mapplot, vectorplots, and combinedplots.Lakes- Adds lakes to mapplot, vectorplots, and combinedplots.Standard Title- Adds a descriptive title based on your data to your mapplot.Mean Max Wind- Work In Progress.Custom Text- Work In Progress.We encourage you to create your own formatoptions and contribute to this repository if they would be useful for others.Once registered to a plotter class, the formatoptions can be used as seen in many of the icon-vis scripts, for example inmapplot.py.ContactsThis repo has been developed by:Annika Lauber (C2SM) -annika.lauber@c2sm.ethz.chVictoria Cherkas (MeteoSwiss) -victoria.cherkas@meteoswiss.ch