WIXLIB

Transition Guide NCL à PyNGLVersion 1.1February 2019Karin Meier-Fleischer, DKRZ

Table of Contents1Introduction . 42Basics of the Languages NCL and Python . 53Arithmetic Functions . 94Read a File. 10564.1Read GRIB, HDF or netCDF Data Sets . 104.2Read an ASCII File . 104.3Read Multiple Files . 12Write a File. 145.1Write a netCDF File. 145.2Write an ASCII File . 18Plotting . 206.1Maps . 206.2XY-Plot . 236.2.1Bar Charts and Histograms. 256.3Contour Plots . 286.3.1Contour Line Plot . 286.3.2Contour Fill Plot . 296.3.3Contour Lines on Maps . 306.3.4Contour Fill on Maps. 326.4Vector and Streamline Plots. 346.4.1Vector Plot on Maps . 346.4.2Streamline Plot on Maps. 356.5Slices . 386.6Scatter Plots . 406.7Overlays . 426.8Panel Plots . 452018-09-042

6.9Annotations . 476.10Polylines, Polygons, and Polymarker . 506.11Masking . 536.12Shapefiles. 566.13Regridding . 592018-09-043

1 IntroductionFor most NCL users, the pivot from NCL to Python will likely be a big step which could take a significant amount of time. This guide was written to help users withthe transition and hopefully ease some of the anxiety.The first section provides a comparison table of NCL and Python language features, while the second section contains one-to-one mappings of NCL and Pythonarithmetic functions.The next two sections provide NCL and Python examples of reading and writing ASCII and NetCDF files.The rest of the guide contains a suite of graphical examples written in both NCL and Python, with the Python scripts using PyNGL for the graphics.For the sections that contain NCL and Python scripts, you will find the NCL part on the left side and the equivalent Python part on the right side. You can directlycompare the scripts line by line and you will see that there are not too many big differences as you might expect.Many of the examples in this document can be found on the NCL website at:http://www.ncl.ucar.edu/Applications/NCL to Python/Some of these examples use xarray instead of PyNIO, but the PyNIO code was commented out so you can use this if desired.To run the example scripts, the easiest thing to do is use conda. You first need to install Miniconda via:https://conda.io/en/latest/miniconda.htmlYou can then use conda to install all of the required packages. It is recommended that you install these packages to a separate environment:conda create -n ncl to python -c conda-forge xarray netcdf4 scipy pyngl pynio nclsource activate ncl to pythonYou can now download the NCL or Python scripts from the above website and any required data file(s) from:http://www.ncl.ucar.edu/Document/Manuals/NCL User Guide/Data/Finally, run the scripts with:NCL:ncl script name.nclPyNGL:python script name.py2018-09-044

2 Basics of the Languages NCL and PythonVariable assignment, array indexing, loops, and conditional statements differ in NCL and Python but there are many similarities. To give a complete comparisonwould go beyond the scope of this document, therefore only the important things are mentioned.To learn more about NCL, Python, Xarray, NumPy, etc. seeNCL documentationPython 2.x documentationPython 3.x documentationNumpy and io/en/latest/NCLPyNGL/PyNIO;-- this is a comment#-- this is a comment/;This is a block commentwhich can have multiple lines.;/"""This is a block commentwhich can have multiple lines.""";-- load library fileload "my lib.ncl"#-- import a moduleimport my lib;-- define variable varvar 12print(typeof(var))#-- define variablevar 12print(type(var));-- define variable vf of type floatvf 2.0print(typeof(vf))#-- define variable vf of type floatvf 2.0print(type(vf));-- convert var to floatvar : tofloat(var)print(typeof(var))#-- convert var to floatvar float(var)print(type(var));-- convert var to stringvar : tostring(var)print(typeof(var))#-- convert var to stringvar str(var)print(type(var))2018-09-045

;-- define an arrayarray (/0,3,6,9/)print(array)#-- define an arrayarray [0,3,6,9]print(array)#-- its better to use Numpy for arraysimport numpy as nparray np.array(array)print(array);-- overwrite array with zerosarray 0print(array)#-- overwrite array with zerosarray[:] 0print(array);-- overwrite array with onesarray 1print(array)#-- overwrite array with onesarray[:] 1print(array);-- addition of arraysa (/1,2,3,4/)b (/0,1,1,0/)c a bprint(c)#-- addition of arraysa np.array([1,2,3,4])b np.array([0,1,1,0])c np.array(a b)print(c);-- create some new arraysn new(4,integer)n 0q new((/2,3,5/),float)q 0.l new(100,float,1e20)print(n)print(q)print(l)#-- create some new arraysn np.zeros(4,np.int)q np.zeros(shape (2,3,5),dtype float)l np.full(100,1.0e20)print(n)print(q)print(l);-- subscriptinga sub a(1:3)print(a sub)#-- array indexing (doesn't include the last index)a sub a[1:3]print(a sub)#-- now it doesa sub a[1:4]print(a sub);-- reverse arraya rev a(::-1)#-- reverse arraya rev a[::-1]2018-09-046

print(a rev)print(a rev);-- select every second elementa sec a(::2)print(a sec)#-- select every second elementa sec a[::2]print(a sec);-- find values in arrayind 0 ind(b .eq. 0)print(b(ind 0)#-- find values in arrayind not0 np.nonzero(b ! 0)print(b[ind not0]);-- generate equaly spaced arraysi ispan(0,10,1)print(i)#-- generate equaly spaced arraysi np.arange(0,10,1)print(i)lat fspan(-180.0,180.0,13)print(lat)lat np.linspace(-180.0, 180.0,13)print(lat)#-- orlat np.arange(-180.0,210.0,30.0);-- dimension reshapingra ,3,4/),(/5,6,7,8/),(/5,4,2,0/)/) /)print(dimsizes(ra))ra1d ndtooned(ra)print("" ra1d)print(dimsizes(ra1d))ra3d onedtond(ra,dimsizes(ra))print(dimsizes(ra3d))#-- dimension reshapingra ,4],[5,6,7,8],[5,4,2,0]]])print(ra.shape)ra1d np.ravel(ra)print(ra1d)print(ra.shape)ra3d np.reshape(ra,ra.shape)print(ra3d.shape);-- if statements (NCL version 6.5.0)t 99if(t .eq. 0) thenprint("t 0")elseif (t .eq. 1) thenprint("t 1")elseprint("t " t)end if#-- if statementst 99if t 0:print("t 0")elif t 1:print("t 1")else:print("t {}".format(t));-- do loopsdo j 0,5print("j " j)end do#-- for loopsfor j in range(0,5,1):print("j {}".format(j))2018-09-047

str array (/"Hamburg","Munich","Berlin"/)do k 0,dimsizes(str array)-1print(str array(k) "")end dostr array ["Hamburg","Munich","Berlin"]for city in str array:print(city);-- while loopsj 0do while(j .lt. 5)print("j " j)if(j .eq. 3) thenprint("-- j " j)end ifj j 1end do#-- while loopsj 0while(j 5):print("j ",j)if j 3:print("-- j {}".format(j))j j 12018-09-048

3 Arithmetic FunctionsThe module numpy provides numerous arithmetic functions to calculate e.g. averages, means, minimum, maximum, and statistics. The list below doesn’t containall functions but the important ones.See /reference/routines.math.htmlModule loadimport numpy as solut valueSinusCosineTangentInverse sinusInverse cosineInverse tangentConvert radians in degreesConvert degrees in radiansAverageExponentLogarithmStandard deviationVarianceReturn the ceilingReturn the floorRemainder of divisionNCLmin, dim min nmax, dim max ndim sum ndim product nsqrtabssincostanasinacosatanget r2dget d2rdim avg nexplogstddev, dim stdev ndim variance nnp.degrees, np.rad2degnp.radians, lnp.floornp.mod2018-09-049

4 Read a FileThe best way to compare NCL and PyNGL is to oppose an NCL script to a PyNGL script. In this chapter we will give an overview of the differences and howsimilar the scripts are. Using PyNIO to open and read a file is straight forward to the addfiles handling, you don’t have to take care if you have a GRIB, HDF ornetCDF file. Reading an ASCII file is as with NCL a little bit different and will be explained afterwards.4.1 Read GRIB, HDF or netCDF Data SetsThe start makes a script which opens a file, print the variables it contains, reads a variable and print some information about some variables.NCLimport Ngl,NioPyNGL/PyNIO#-- import PyNGL and PyNIO modules;-- data file namefname "rectilinear grid 3D.nc"#-- data file namefname "rectilinear grid 3D.nc";-- open filef addfile(fname,"r")#-- open filef Nio.open file(fname);-- retrieve the variables stored in fileprint(getfilevarnames(f))#-- retrieve the variables stored in fileprint(f.variables);-- read variable, first time steptemp f- t(0,:,:)#-- read variable, first time steptemp f.variables["t"][0]#temp f.variables["t"][0,:,:] # Also valid;-- print variable summaryprintVarSummary(temp);-- print variable lat contentprint("" f- lat);-- print variable lon contentprint("" f- lon)#-- print variable summaryprint(f.variables["t"])#-- print variable lat contentprint(f.variables["lat"])#-- print variable lon contentprint(f.variables["lon"])4.2 Read an ASCII FileUsually ASCII files are used to store data in a readable format e.g. for observed data (station data). The ASCII data files can contain data written column-wisewith delimiter separating the columns (CSV files), block-wise or any other combination. Therefor it is very important to have a description what is in the file.2018-09-0410

Assume we want to read some data, store it in an array, print the array values and some more information like number of columns and lines, rank and shape. Theinput ASCII file is Test 0.50NCLPyNGL/PyNIOimport numpy as npimport Ngl;-- data file namefili "Test 6h.csv"#-- data file namefili "Test 6h.csv";-- number of lines and columns in input filenrows 5ncols 4#-- number of lines and columns in input filenrows 5ncols 4;-- read all datavals asciiread(fili,(/nrows,ncols/),"float")#-- read all datavals Ngl.asciiread(fili,(nrows,ncols),"float",sep ';');-- print informationprint("vals:" vals)print("rank of vals: " dimsizes(dimsizes(vals)))print("shape vals:" dimsizes(vals))#-- print k of vals: {}".format(len(vals.shape)))print("shape vals:{}".format(vals.shape))exit()The next example will show you how to read an ASCII file which contains 21361 lines. One header line and 21360 lines with latitudes, longitudes, andtemperature values. The file name is asc6.txt which can be downloaded from .Lat Lon Temp (C)33.3 76.5 20.333.3 76.6 20.333.3 76.7 21.533.3 76.8 20.0.NCLPyNGL/PyNIOimport numpy as npimport Ngl2018-09-0411

;-- file has 21361 lines but 1 header line;-- 3 columnsnrows 21360ncols 3num lon 240;-- number of longitudesnum lat 89;-- number of latitudes#-- file has 21361 lines but 1 header line#-- 3 columnsnrows 21360ncols 3num lon 240#-- number of longitudesnum lat 89#-- number of latitudes;-- read all data from filedata asciiread("asc6.txt",(/nrows,ncols/),"float")#-- read all data from filedata Ngl.asciiread("asc6.txt",(nrows,ncols),"float");-- select lat, lon and temp datalat data(::num lon,0)lon data(:num lon-1,1)temp1D data(:,2)#-- select lat, lon and temp datalat data[::num lon,0]lon data[:num lon,1]temp1D data[:,2];-- sizenlats nlons ntemp #-- sizenlats nlons ntemp of lat, lon and temp1Ddimsizes(lat)dimsizes(lon)dimsizes(temp1D)of lat, lon and temp1Dlen(lat)len(lon)len(temp1D);-- reshape temp1d to 2D-array temp2D array (89,240)temp2D onedtond(temp1D,(/nlats,nlons/))#-- reshape temp1d to 2D-array temp2d with size (89,240)temp2D np.reshape(temp1D,(nlats,nlons));-- print informationprint("rank temp1D: "print("shape temp1D: "print("rank temp2D: "print("shape temp2D: "#-- print informationprint("rank temp1D: {}".format (len(temp1D.shape)))print("shape temp1D: {}".format (ntemp))print("rank temp2D: {}".format(len(temp2D.shape)))print("shape temp2D: {}".format (temp2D.shape)) (temp2D)))dimsizes(temp2D))exit()4.3 Read Multiple FilesSometimes a variable is stored in more than one file for different time steps. In this case NCL and Python’s netCDF4 package are able to read the multiple filesas one.NCLPyNGL/PyNIOimport netCDF4 as nc;-- list of filesfile list systemfunc("ls file *.nc")#-- list of filesfile list "file *.nc";-- open file2018-09-0412