IRT Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 8
Iterative Rain Cell Tracking Tool (Version V1) Manual
Christopher Moseley, Jan Haerter
May 18, 2018
1 License
The Iterative Rain cell Tracking (IRT) tool can be distributed and modified freely for non-commercial
use. For publications resulting from the use of the code, the following reference has to be cited:
•C. Moseley, O. Henneberg, and J.O. Haerter, 2018: Amplified convective precipitation from
multi-merging. Manuscript submitted to Journal of Advances in Modelling Earth Systems
2 Software Requirements
•It is recommended to use the IRT code on a Linux or UNIX system.
•A standard Fortan 90 compiler: The IRT code is written completely in Fortran 90. It can
be compiled by any standard fortran compiler. The code is currently not paralellized.
•Climate Data Operators (CDO): The IRT tool uses the SERVICE format (file ending “.srv”)
for input and output data sets, since this format is easy to handle in Fortan 90 and no additional
libraries have to be included. As data sets are usually given in more wide spread formats like
NetCDF, they have to be converted to SERVICE first. This is conveniently possible with the
CDO software. It is freely available through https://code.mpimet.mpg.de/projects/cdo/
3 Files included in the IRT package
irt objects v1.f90
The Fortran 90 code of the program that identifies spatially connected objects for every time step
independently, and establishes links between objects of subsequent time steps. Input data in SERVICE
format: The data file of the tracked field, additional field which are to be averaged over the track
life cycles (optionally), and the field of the advection velocity on a coarse grid (optionally). Output:
Object data (ASCII format), mask of object IDs (SERVICE format).
irt advection field v1.f90
The Fortran 90 code of the program that generated the field of the advection velocity on a coarser
spatial and temporal grid that is used for the next iteration of irt objects v1.f90. Input data: The
object data output file of by irt objects v1.f90. Output data: The coarse velocity field (SERVICE
format).
irt tracks v1.f90
The Fortran 90 code of the program that forms tracks out of the identified objects. Input data: The
object data output file of by irt objects v1.f90. Output data in ASCII format: Track data with all
available information and a header line of every track, and track data with reduced information which
1
is used as input for the program irt trackmask v1.f90.
irt trackmask v1.f90
The Fortran 90 code of the program that generates a mask with track IDs in SERVICE format. Input
data: The (sorted) output of reduced information track data from irt tracks v1.f90, and the field of
object IDs generated by irt objects v1.f90.
compile.sh
A shell script to compile the code.
iterate.sh
A shell script to perform one IRT iteration automatically.
example dataset.nc
A tutorial dataset for testing the IRT code in NetCDF format. Due to large file size not included in
this repository. Availabe on request via email to christopher.moseley@mpimet.mpg.de
4 Setting the parameters
The parameters for the tracking have to be written hard-coded into the Fortran 90 file
irt parameters.f90. This file has to be modified first, before the code can be compiled. The fol-
lowing parameters have to be set:
Domain size:
The domain size longitudinal and latitudinal direction is given by the parameters domainsize x and
domainsize y, respectively. The domain size of an input field can be found e.g. by the calling the
CDO command
cdo griddes example dataset.nc .
and the domainsize must be set according to the values of xsize and ysize in the output of the CDO
command, i.e.
INTEGER, PARAMETER :: domainsize x = 960
INTEGER, PARAMETER :: domainsize y = 960
in the case of the tutorial dataset.
Switch for periodic/non-periodic boundary conditions:
If doulbe-periodic boundary conditions should be applied in both x- and y-direction, the switch lperi-
odic has to be set to
LOGICAL, PARAMETER :: lperiodic = .TRUE.
Otherwise, it has to be set to
LOGICAL, PARAMETER :: lperiodic = .FALSE.
Threshold value for the tracking field:
A minimal cutoff value has to be defined that decides, if a grid point should be counted as belonging
to an object or not. E.g. in the case of rain intensity, a grid point must have at least the intensity
given by cutoff to be counted as a precipitating patch. If precipitation intensity given in mm/h is
tracked,
REAL, PARAMETER :: threshold = 1.0
could be a reasonable choice.
2
Minimum size of a patch:
Patches which are smaller than minimum size grid points will be neglected. A reasonable choice may
be: REAL, PARAMETER :: minimum size=4.
Grid description of the coarse velocity field:
The coarse advection velocity field is not needed for the first run of irt objects v1.f90 (i.e. the first
iteration of IRT), but for all subsequent iterations. It is given in grid points per time interval. To
define the spatial and temporal grid of the velocity field, the following parameters have to be set:
•The number of time steps in the input dataset can be found e.g. by running the CDO command
cdo ntime example dataset.nc ,
and the parameter time steps has to be set accordingly:
INTEGER, PARAMETER :: time steps = 120
•The number of time steps of the velocity field is nt bins, and the number of grid boxes in x- and
y-direction are nx bins and ny bins, e.g.
INTEGER, PARAMETER :: nt bins = 10
INTEGER, PARAMETER :: nx bins = 2
INTEGER, PARAMETER :: ny bins = 2
In this case, the domain will be divided into 2 ×2 equally spaced squares. The whole time series
will be divided into nt bins= 10 equally long time intervals, therefore the temporal resolution of
the velocity dataset is one hour (the input dataset has 120 time steps with 5 minutes interval,
i.e. is in total 10 hours long).
Maximum velocity:
The parameter max velocity is a threshold with the intent to filter out events with unrealisticly high
diagnosed velocities. This could e.g. happen when patched which do not actually belong to the same
event accidently overlap, and therefore create artifacts. A reasonable value could be
REAL, PARAMETER :: max velocity = 10.
Minimum sample size for advection velocity:
If the sample size for the diagnostics of advection velocity is too small, the mean value could be too
noisy. The parameter min cells gives the minimum sample size of cells that are required to assign a
mean value to a velocity grid box. If the sample size is smaller, then the velocity of the grid box will
be interpolated from the neighbouring grid boxes. A reasonable value could be
INTEGER, PARAMETER :: min cells = 10
Additional averaging fields:
Besides reading in only the tracking field (i.e. rain intensity in case of the tutorial dataset), there is
the option to read in additional fields that will be averaged over the track life cycles. This is controlled
by the parameter n fields. If the tracking field should be the only input file, then it should be set to 0:
INTEGER, PARAMETER :: n fields = 0
If we want to study e.g. the life cycles of the convergence field inside the tutorial file example dataset.nc,
we can set n fields= 1.
Controlling the sensitivity of tracks to merging and splitting events:
The parameter termination sensitivity controls if a merging/splitting event terminates tracks or not,
and must have a value between 0 and 1. If threshold ratio= 0, every such event leads to termination
of all involved track. If threshold ratio= 1, at every merging/spitting event the largest involved track
is not terminated, while all others terminate. A more detailed description is given in Moseley et al.,
3
2018. Example:
REAL, PARAMETER :: termination sensitivity = 0.5
Buffer sizes:
The following parameters are just buffer sizes and do not affect the tracking results. They have to be
increased if necessary.
•The maximum number of objects in a single time step: max no of cells
•The maximum length of a track: max length of track
•The maximum number of tracks at a single time step: max no of tracks
Missing value:
The parameter miss defines the missing value. If a value is less or equal than miss will be regarded as
missing value. By default we use:
REAL, PARAMETER :: miss = -9999.
5 Compiling the code
After all parameters have to be adjusted in the Fotran 90 files, the code can be compiled. All code files
can be compiled independently. The shell script compile.sh compiles all four Fortran 90 files with the
Intel compiler “ifort”. If you use another compiler, you can adjust the variable COMPILE COMMAND
in the script. The executables will be generated with the file ending “.x”.
6 Running the tracking
In the following, we apply the tracking on the tutorial dataset example dataset.nc.
Preparing input datasets:
The NetCDF file example dataset.nc contains the variables r int (the rain intensity given in [mm/h])
and conv h low (the moisture convergence below 2000 mgiven in [mm/s]). It is given on a 960 ×960
grid with periodic boundary conditions and contains 120 time steps.
We use the intensity field as tracking field and the convergence field as additional averaging field.
Using CDO, the fields should first be separated and converted into SERVICE format. There are
n fields+1 input datsets, and they must have the file names irt objects input 00.srv for the tracking
field (here: rain intensity) and irt objects input xx.srv where xx= 01,02, . . . for the additional fields:
cdo -f srv selvar,r int example dataset.nc irt objects input 00.srv
cdo -f srv selvar,conv h low example dataset.nc irt objects input 01.srv
The tutorial dataset does not contain missing values. If a dataset contains missing values, they
must be set to miss (-9999 by default) before the conversion. This is possible with the CDO command
setmisstoc, e.g.:
cdo -f srv setmisstoc,-9999 <filename>.nc irt objects input.srv
Setting parameters:
Before compiling, the following parameters have to be set as described in section 4:
domainsize x= 960
domainsize y= 960
time steps= 120
4
lperiodic=.TRUE.
threshold= 1.0 (try also different values here)
n fields= 1
input filename = (/”irt objects input.srv ”,”irt objects input conv.srv”/)
For the coarse velocity field we choose:
nt bins = 5
nx bins = 2
ny bins = 2
The other parameters can be chosen arbitrarily. After all this is done, the code can be compiled as
described in section 5.
Running first iteration:
•Step 1: The objects have to be identified by calling:
./irt objects v1.x 1
The argument “1” means that no advection velocity field will be read in. The program reads
in the files irt objects input.srv and irt objects input conv.srv, and generates the output files
irt objects output.txt, and irt objects mask.srv
•Step 2: To generate the coarse advection velocity field, call:
./irt advection field v1.x
The program reads in the file irt objects output.txt, and writes the advection velocity field into
the file irt advection field.srv in SERVICE format.
•Step 3: Combining the identified objects to tracks is done by calling the program:
./irt tracks v1.x
It reads in the file irt objects output.txt and writes two output files: irt tracks output.txt contain-
ing the full tracks information, and the auxiliary file irt tracks nohead output.txt with reduced
information.
•Step 4: The final step is to generate the SERVICE file with the mask of track IDs. Therefore,
two steps have to be done: First, the auxiliary file irt tracks nohead output.txt has to be sorted
with respect to time step (second column). With a Linux system, this can by done e.g by using
the “sort” command:
sort -n -k2 irt tracks nohead output.txt >irt tracks sorted.txt
In the second step, call the program:
./irt trackmask v1.x
It reads in the sorted file irt tracks sorted.txt and the mask of object IDs irt objects mask.srv
and writes out the SERVICE file irt tracks mask.srv.
Running second and subsequent iterations:
After the first iteration has been run, the file irt advection field.srv exists which is needed to perform
the second iteration. This can be done by calling: ./irt objects v1.x 2
Here, the argument “2” means that the velocity field will be read in and applied for the identification of
overlaps between objects of consecutive time steps. Steps 2 to 4 are the same as for the first iteration.
The procedure can be iterated until the velocity field converges. Note: In principle, it is possible to
perform the second and all further iteration already after step 2, steps 3 and 4 do not have to be run
every time necessarily.
Shell script for the iteration process The shell script iterate.sh performs all the above mentioned
5
steps automatically, and saves the tracking result of every iteration in separate files. Otherwise the
output files will be overwritten with every new iteration. For the first iteration, modify the script and
set the variable iteration= 1. Then run the script with: ./iterate.sh
For the second and all subsequent iteration, set iteration= 1,2,3, . . . and call the script again.
7 Format of the output files
This section explains the output files which are necessary for the analysis and visualization of the
tracking results.
Format of the objects data output file irt objects output.txt
The data file is in text format. Each line contains information of one identified object (connected
patch). The number of colums is 23+3×n fields, where n fields is the parameter defining the number
of additional input fields as described in section 4. The columns contain the following information:
1. Time step
2. Object ID1: ID of the object for the given time step (counting begins with 1 at every new time
step). If 0, it means that no object was found at the given time step, and all values in the other
columns will be set to 0.
3. Object ID2: ID of the object for the whole time series (counting is continued at every new time
step)
4. Area of the object in grid points
5. Mean value of the tracked field, averaged over the object’s area. If n fields>0, then the next
n fields columns contain area-averages over the other input fields.
6. Minimum value of the tracked field within the object’s area. If n fields>0, then the next n fields
columns contain minimum values over the other input fields within the object.
7. Maximum value of the tracked field within the object’s area. If n fields>0, then the next n fields
columns contain maximum values over the other input fields within the object.
8. x coordinate (in grid boxes, starting with 1) of the object’s most western point (i.e. smallest
x-coordinate)
9. x coordinate of the object’s most eastern point (i.e. largest x-coordinate)
10. y coordinate of the object’s most southern point (i.e. smallest y-coordinate)
11. y coordinate of the object’s most northern point (i.e. largest y-coordinate)
12. x coordinate of the weighted center of mass of the object
13. y coordinate of the weighted center of mass of the object
14. x component of the object’s estimated velocity given in grid points per time step. Missing value
if not detectable.
15. y component of the object’s estimated velocity given in grid points per time step. Missing value
if not detectable.
16. ID2 of the largest object of the next time step that overlaps with this object. If 0, no such object
exists.
6
17. Area of the object given in the column before
18. ID2 of the second largest object of the next time step that overlaps with this object. If 0, no
such object exists.
19. Area of the object given in the column before
20. ID2 of the largest object of the previous time step that overlaps with this object. If 0, no such
object exists.
21. Area of the object given in the column before
22. ID2 of the second largest object of the previous time step that overlaps with this object. If 0,
no such object exists.
23. Area of the object given in the column before
Format of the tracks data output file irt tracks output.txt
The data file is in text format. Each track consists of a header line, followed by a track body. Tracks
are separated by a dummy line containing the character *. A track header line consists of 5 columns
containing the following information:
1. Track ID
2. Time step when track begins
3. Duration of the track in time steps
4. Code labeling the situation at the beginning of the track:
0: Track emerges by itself
1: Track is fragment of a splitting event
2: Track is result of merging event
-1: Track initiated by contact with missing values
5. Code labeling the situation at the end of the track:
0: Track dissipated
1: Track terminated by merging event
2: Track terminated by splitting event
-1: Track terminated by contact with missing values
The track body has one line for every time step of the track life time, with 12+3×n fields columns
containing the following information:
1. Track ID
2. Time step
3. Object ID1
4. Object ID2
5. Area of the object in grid points
6. Mean value of the tracked field, averaged over the object’s area. If n fields>0, then the next
n fields columns contain area-averages over the other input fields.
7
7. Minimum value of the tracked field within the object’s area. If n fields>0, then the next n fields
columns contain minimum values over the other input fields within the object.
8. Maximum value of the tracked field within the object’s area. If n fields>0, then the next n fields
columns contain maximum values over the other input fields within the object.
9. x coordinate of the weighted center of mass of the object
10. y coordinate of the weighted center of mass of the object
11. x component of the object’s estimated velocity given in grid points per time step. Missing value
if not detectable (usually at the end of the track).
12. y component of the object’s estimated velocity given in grid points per time step. Missing value
if not detectable (usually at the end of the track).
Mask files in SERVICE format
•The file irt objects mask.srv contains a mask of the identified objects and marks them with the
object ID1. Objects which are neglected because they are too small, or because they touch
missing values, are indicated by the value -1.
•The file irt tracks mask.srv constains a mask of all objects and marks them with the track ID.
Objects which belong to tracks that are neglected because they are only 1 time step long, or
because they touch missing values, are indicated by the value -1.
•The masks can be converted to NetCDF e.g. by the CDO command
cdo -f nc copy irt objects mask.srv irt objects mask.nc
cdo -f nc copy irt tracks mask.srv irt tracks mask.nc
8
