WaterSip: Difference between revisions

From gfi
No edit summary
 
(49 intermediate revisions by the same user not shown)
Line 1: Line 1:
===About WaterSip===
===About WaterSip===


WaterSip is a diagnostic software tool that identifies source, transport and arrival properties of atmospheric water vapour. It implements the moisture source diagnostic of Sodemann et al. (2008) for input data from either FLEXPART particle output or Lagranto trajectories.
WaterSip is a diagnostic software tool that identifies source, transport and arrival properties of atmospheric water vapour based on airmass backward trajectories. As a prerequisite, the backward trajectories for the analysis are to be obtained from a trajectory calculation tool, such as FLEXPART [[http://www.flexpart.eu]] or Lagranto [[http://www.lagranto.iac.ethz.ch]]. Moisture sources are then identified from changes in specific humidity interpolated to the air parcel trajectory per time step. The changes in specific humidity at each time step are set in relation with the current humidity of the air parcel. This allows to estimate the quantitative contribution of moisture to the air parcel at a specific location, a so-called moisture accounting. WaterSip identifies and aggregates further properties of the moisture source and during the moisture transport, such as temperature, pressure, latitude etc. The moisture source diagnostic is described in detail in [[Sodemann et al. (2008)]]. Publications using the WaterSip diagnostic are listed in section [[Bibliography]].


===Running the WaterSip diagnostic===
===Working principle===


The current version of WaterSip is V3.0.0. It is advised to create a link to the binary file of WaterSip in you /home/$USER/bin or project directory:
Explanation from Sodemann et al. 2008a


<pre>
Image from Läderach and Sodemann, 2016 or Sodemann et al., 2008a
mkdir ~/bin
ln -s /Data/gfi/met_backup/progs/WaterSip_tool/WaterSip3 ~/bin
</pre>


Adding <code>~/bin</code> to your path will make execution of WaterSip more comfortable. To start a diagnostic run, WaterSip needs to be called from the command line. This version reads one single input file during startup which contains all parameter settings required to execute a run (the examples below assume that you are in a working directory and WaterSip3 is at a location in your $PATH environment variable):
Moisture source information


<pre>
- Accounted fraction fa, fb, fa+fb
WaterSip3 <WATERSIP_parameter_file>
- adding below and above boundary layer or not, when
</pre>
- choosing threshold values for Arctic and other regions
- identifying moisture transport


====Input file conversion from V2====
Arrival information and Lagrangian forward projections


The input file format, described below, is quite different in V3 than in previous versions. To facilite transition from V2.x input files, there is an option execute WaterSip3 with the option -c to convert to the new V3 input file format:
- arrival parameters
- transport parameters
- source parameters
- averaging by contribution and amount


<pre>
Series information
WaterSip3 -c <WATERSIP_V2_parameter_file>
</pre>


This will create a new file named <WATERSIP_V2_parameter_file>V3 at the current directory. It is recommended to double check and edit the settings in the converted file before starting a simulation.
- sectorization (Sodemann and Zubler, 2010; definition table, code changes)
- weighted averaging: The averaging over time steps, as required by different grid files, is done by weighting each time step contribution with the corresponding precipitation estimate, and deviding by the total precipitation.


====Parallelization====
Averaged properties


WaterSip3 has been parallelized with OpenMP, which can significantly speed up calculation time. The number of processors to be used is specified in the input file (see below).
- histogram example and modification (code below)


If WaterSip3 is to be executed on the queue (this is imperative for all runs except for short tests), the following wrapper script can be used to start a run using 4 cores for parallel processing:
Trajectories


<pre>
- plotting/reading example (code below)
# start with sbatch NAME_OF_THIS_FILE directly on machine


#SBATCH --job-name=WaterSip3
Uncertainties
#SBATCH --workdir=/tmp/
#SBATCH --partition=priority
#SBATCH --output=WaterSip_job.%j.out
#SBATCH --error=WaterSip_job.%j.err
#SBATCH --mail-type=END
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4


cd /Data/gfi/met_backup/progs/WaterSip_tool/src3.0
===Example setups===
srun WaterSip3 INPUT_WATERSIP_global_1993
</pre>


Three examples with different purposes


=== Input file options ===
====Water vapour====


The WaterSip input file is a text file with options that are specified for different option groups. Option groups are identified by square brackets (e.g. <code>[Case]</code>). There are 7 option groups which can appear in random order in the input file:
- considerations and parameters


*Case: general settings related to the case to be extracted
====Extratropical precipitation====
*Grids: specification of different output grids
*Diagnostrics: parameters of the moisture diagnostic
*Output: general output settings
*Variables: selection of output variables
*Flexpart: options specific to runs using FLEXPART particle output
*Lagranto: options specific to runs using Lagranto trajectories


====Parameter set Case====
- considerations and parameters
- '''caseName (string):''' identifier for the run, prepended to all output files.
====High latitude precipitation====


<code>caseName = global_201002_relative</code>
- considerations and parameters


- '''inputDir (string):''' search path of the input files. The inputDir string ends with a placeholder for the files to be read in. For FLEXPART this will be either shortposit_ or partposit_. For Lagranto this will commonly be lsl_. The %s placeholder is completed by the currently read in date at runtime.
===Version history===


<code>inputDir = /Volumes/Data/global/shortposit_%s</code>
Version 2.1


- '''outputDir (string):''' path where the output files will be created.  
Version 2.2


<code>outputDir = /Volumes/Data/global/output/</code>
Version 2.3


- '''startDate (date string):''' inital date of the run, fixed format YYYYMMDD-HHMMSS. Start date is latest date of the run which moves backward in time.
Version 2.4


<code>startDate = 20100228-180000</code>
Version 2.5


- '''endDate (date string):''' final date of the run, fixed format YYYYMMDD-HHMMSS. End date is earliest date of the run.
Version 2.8


<code>endDate = 20100211-000000</code>
Version 2.8.1


- '''timeStep (integer):''' time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours))
Version 2.9


<code>timeStep = 6</code>
Version 2.9.1


- '''trajPoints (integer):''' number of trajectory points to be considered in a trajectory. For 5-day trajectories with a 6 hour time step, 5x4+1=21 trajPoints should be selected.
Version 2.9.2


<code>trajPoints = 21</code>
Version 2.9.3


- '''minTrajPoints (integer):''' minimum length of trajectories to be included in analysis. Parameter is only relevant for Lagranto simulations with uneven trajectory length.
Version 2.9.4


<code>minTrajPoints = 0</code>
Version 3.0.8


- '''sectorizeRegion (integer):''' region set used to divide moisture sources into different sectors (see [[Sectorization]])
Version 3.1


<code>sectorizeRegion = 0</code>
The current version of WaterSip is V3.1.0.


- '''filterBoxFile (string):''' path to the text file describing geographic boxes used to filter air parcels during transport (see [[Box filters]]).
===Running the WaterSip diagnostic===


<code>filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste</code>
It is advised to create a link to the binary file of WaterSip in your /home/$USER/bin or project directory:


- '''filterIndex (integer):''' used line from the filterBoxFile to select/deselect trajectories
<pre>
mkdir ~/bin
ln -s /Data/gfi/projects/isomet/progs/WaterSip_tool/WaterSip3 ~/bin
</pre>


<code>filterIndex = -1</code>
Adding <code>~/bin</code> to your path will make execution of WaterSip more comfortable. To start a diagnostic run, WaterSip needs to be called from the command line. This version reads one single input file during startup which contains all parameter settings required to execute a run (the examples below assume that you are in a working directory and WaterSip3 is at a location in your $PATH environment variable):


- '''orographyFile (string):''' path to the orography file used to select arrival based on underying topography, using the ETOPO2 topography. File in netcdf format.
<pre>
module load netCDF-C++
WaterSip3 <WATERSIP_parameter_file>
</pre>


<code>orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc"</code>
Note that the UiB hpc environment requires the above 'module load' command to be executed first.


- '''lsmFile (string):''' path to the file with global land-sea-mask, currently from ERA-Interim data. Domain must be global but is in principle arbitrary. File in netcdf format.
On cyclone.hpc.uib.no, a run script is available that makes repeated similar runs easier to manage. Only essential parameters have to be changed, such as the target coordinates and case name. These will then be replaced on a template INPUT_WATERSIP file, and then WaterSip will be started. The script and an input file template can be copied like this:


<code>lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/ERA_sea_mask_inv.nc"</code>
<pre>
cp /Data/gfi/projects/isomet/projects/watersip/Bergen_iso/run_watersip_template_Bergen_2018.sh .
cp /Data/gfi/projects/isomet/projects/watersip/Bergen_iso/INPUT_WATERSIP_template_Bergen_2018 .
</pre>


- '''maskFile (string):''' path to file with an arrival selection
====Input file conversion from V2====


<code>maskFile = " "</code>
The input file format, described below, is quite different in V3 than in previous versions. To facilite transition from V2.x input files, there is an option execute WaterSip3 with the option -c to convert to the new V3 input file format:


- '''useMask (boolean):''' use mask file (0=no, 1=yes).
<pre>
WaterSip3 -c <WATERSIP_V2_parameter_file>
</pre>


<code>useMask = 0</code>
This will create a new file named <WATERSIP_V2_parameter_file>V3 at the current directory. It is recommended to double check and edit the settings in the converted file before starting a simulation.


- '''ompThreads (integer):''' number of threads to be used with OpenMP parallelisation if compiled with flag -fopenmp (1=no parallelisation, >1 parallelisation activated.)
====Parallelization====


<code>ompThreads = 1</code>
WaterSip3 has been parallelized with OpenMP, which can significantly speed up calculation time. The number of processors to be used is specified in the input file (see below).


- '''showStats (boolean):''' print statistics about particle processing to the command line (0=off, 1=on).
If WaterSip3 is to be executed on a queue system (not applicable to cyclone.hpc.uib.no), the following wrapper script can be used to start a run using 4 cores for parallel processing:


<code>showStats = 0</code>
<pre>
# start with sbatch NAME_OF_THIS_FILE directly on machine


====Parameter set Grids====
#SBATCH --job-name=WaterSip3
- '''arrivalGridMinLon (float):''' minimum longitude of arrival (target region) grid box. Trajectories are traced backward from the arrival grid. Integrated source, transport and arrival parameters are put on the arrival grid, weighted by precipitation or water vapour of arriving air parcels.
#SBATCH --workdir=/tmp/
#SBATCH --partition=priority
#SBATCH --output=WaterSip_job.%j.out
#SBATCH --error=WaterSip_job.%j.err
#SBATCH --mail-type=END
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4


<code>arrivalGridMinLon = -180</code>
srun ./WaterSip3 INPUT_WATERSIP_global_1993
</pre>


- '''arrivalGridMaxLon (float):''' maximum longitude of arrival (target region) grid box
====Creating mask files====


<code>arrivalGridMaxLon = 180</code>
WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.


- '''arrivalGridMinLat (float):''' minimum latitude of arrival (target region) grid box
The procedure described here  uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.


<code>arrivalGridMinLat = -90</code>
Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]


- '''arrivalGridMaxLat (float):''' minimum latitude of arrival (target region) grid box
Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]


<code>arrivalGridMaxLat = 90</code>
[[File:watersip_mask-guide_cut.png|400px]]
Figure: Example for Scandinavia


- '''arrivalGridDx (float):''' longitude increment of arrival (target region) grid
''Basic principle:''


<code>arrivalGridDx = 1</code>
Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.


- '''arrivalGridDy (float):''' latitude increment of arrival (target region) grid
<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>


<code>arrivalGridDy = 1</code>
''Input:''


- '''arrivalGridRadius (float):''' gridding radius for information from arriving trajectories
list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.


<code>arrivalGridRadius = 200</code>
global meshgrid with a given resolution


- '''sourceGridMinLon (float):''' minimum longitude of moisture source grid box
''Output:''


<code>sourceGridMinLon = -180</code>
Boolean mask of False and True in the shape of the meshgrid lat-lon


- '''sourceGridMaxLon (float):''' maximum longitude of moisture source grid box
After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:


<code>sourceGridMaxLon = 180</code>
<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>


- '''sourceGridMinLat (float):''' minimum latitude of moisture source grid box
For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]


<code>sourceGridMinLat = -90</code>
[[MaskCode|Python program code available here|]]


- '''sourceGridMaxLat (float):''' maximum latitude of moisture source grid box
=== Input file options ===


<code>sourceGridMaxLat = 90</code>  
The WaterSip input file is a text file with options that are specified for different option groups. Option groups are identified by square brackets (e.g. <code>[Case]</code>). There are 7 option groups which can appear in random order in the input file:


- '''sourceGridDx (float):''' longitude increment of moisture source grid box
*Case: general settings related to the case to be extracted
*Grids: specification of different output grids
*Diagnostrics: parameters of the moisture diagnostic
*Output: general output settings
*Variables: selection of output variables
*Flexpart: options specific to runs using FLEXPART particle output
*Lagranto: options specific to runs using Lagranto trajectories


<code>sourceGridDx = 1</code>
====Parameter set Case====


- '''sourceGridDy (float):''' latitude increment of moisture source grid box
The settings in this parameter category describe the basic conditions of the diagnostic run.


<code>sourceGridDy = 1</code>
;caseName (string)
: identifier for the run, prepended to all output files. Example: <code>caseName = global_201002_relative</code>


- '''sourceGridRadius (float):''' longitude increment of moisture source grid box
;inputDir (string)
: search path of the input files. The inputDir string ends with a placeholder for the files to be read in. For FLEXPART this will be either shortposit_ or partposit_. For Lagranto this will commonly be lsl_. The %s placeholder is completed by the currently read in date at runtime. Example: <code>inputDir = /Volumes/Data/global/shortposit_%s</code>


<code>sourceGridRadius = 200</code>
;outputDir (string)
: path where the output files will be created. Example: <code>outputDir = /Volumes/Data/global/output/</code>


- '''griddingType (integer):''' select [[gridding algorithm]] (1: fast and simple gridding, 2: improved but slower gridding)
;startDate (date string)
: inital date of the run, fixed format YYYYMMDD-HHMMSS. Start date is latest date of the run which moves backward in time. Example: <code>startDate = 20100228-180000</code>


<code>griddingType = 2</code>
;endDate (date string)
: final date of the run, fixed format YYYYMMDD-HHMMSS. End date is earliest date of the run. Example: <code>endDate = 20100211-000000</code>


====Parameter set Diagnostics====
;timeStep (integer)
- '''uptakeThreshold (float):''' Threshold value for specific humidity increases per time step in air parcels to be considered as due to physical processes (evaporation), in g per kg. If the parameter reativeThresholds is set to true, the uptakeThreshold is specified as percent increase relative to the current specific humidity of an air parcel. Value is positive because of an air-parcel relative perspective. Default absolute values are 0.1 to 0.2 for 3h and 6h time steps.
: time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours)). Example: <code>timeStep = 6</code>


<code>uptakeThreshold = 0.2</code>
;trajPoints (integer)
: number of trajectory points to be considered in a trajectory. For 5-day trajectories with a 6 hour time step, 5x4+1=21 trajPoints should be selected. Example: <code>trajPoints = 21</code>


- '''precipThreshold (float):''' Threshold value for specific humidity decreases per time step in air parcels to be considered as due to physical processes (precipitation), in g per kg. Value is negative because of an air-parcel relative perspective. If the parameter reativeThresholds is set to true, the uptakeThreshold is specified as percent increase relative to the current specific humidity of an air parcel. Then the value is positive. Default absolute values are -0.1 to -0.2 for 3h and 6h time steps.
;minTrajPoints (integer)
: minimum length of trajectories to be included in analysis. Parameter is only relevant for Lagranto simulations with uneven trajectory length. Example: <code>minTrajPoints = 0</code>


<code>precipThreshold = -0.2</code>
;sectorizeRegion (integer)
: region set used to divide moisture sources into different sectors (see [[#sectorization]]). Example: <code>sectorizeRegion = 0</code>


- '''blhScale (float):''' Scaling factor to decide for air parcels to be close enough to the boundary layer to consider moisture increases to evaporation to be likely due to surface evaporation below. A factor of 1.5 will assign all moisture increases within 1.5x the current boundary layer height to the category 'moisture sources boundary-layer', all others to the category 'moisture sources free troposphere'. Default value is 1.5.
;filterBoxFile (string)
: path to the text file describing geographic boxes used to filter air parcels during transport (see [[#box filters]]). Example: <code>filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste</code>


<code>blhScale = 1.5</code>
;filterIndex (integer)
: used line from the filterBoxFile to select/deselect trajectories. Example: <code>filterIndex = -1</code>


- '''arrivalPrecipMin (float):'''
;orographyFile (string)
: path to the orography file used to select arrival based on underying topography, using the ETOPO2 topography. File in netcdf format. Example: <code>orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc"</code>


<code>arrivalPrecipMin = 0.05</code>
;lsmFile (string)
: path to the file with global land-sea-mask, currently from ERA-Interim data. Domain must be global but is in principle arbitrary. File in netcdf format. Example: <code>lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/ERA_sea_mask_inv.nc"</code>


- '''arrivalPrecipMax (float):'''
;maskFile (string)
: path to file with an arrival selection. Example: <code>maskFile = " "</code>


<code>arrivalPrecipMax = 1.0</code>
;useMask (boolean)
: use mask file (0=no, 1=yes). Example: <code>useMask = 0</code>


- '''arrivalRHMin (float):'''
;ompThreads (integer)
: number of threads to be used with OpenMP parallelisation if compiled with flag -fopenmp (1=no parallelisation, >1 parallelisation activated.). Example: <code>ompThreads = 1</code>


<code>arrivalRHMin = 80</code>
;showStats (boolean)
: print statistics about particle processing to the command line (0=off, 1=on). Example: <code>showStats = 0</code>


- '''arrivalRHMax (float):'''
----


<code>arrivalRHMax = 110</code>
====Parameter set Grids====


- '''arrivalOroMin (float):'''
The parameters in this category specify the different output grids and the gridding method


<code>arrivalOroMin = -100</code>
;arrivalGridMinLon (float)
: minimum longitude of arrival (target region) grid box. Trajectories are traced backward from the arrival grid. Integrated source, transport and arrival parameters are put on the arrival grid, weighted by precipitation or water vapour of arriving air parcels. Example: <code>arrivalGridMinLon = -180</code>


- '''arrivalOroMax (float):'''
;arrivalGridMaxLon (float)
: maximum longitude of arrival (target region) grid box. Example: <code>arrivalgridmaxlon = 180</code>


<code>arrivalOroMax = 12000</code>
;arrivalGridMinLat (float)
: minimum latitude of arrival (target region) grid box. Example: <code>arrivalGridMinLat = -90</code>


- '''arrivalAltMin (float):'''
;arrivalGridMaxLat (float)
: minimum latitude of arrival (target region) grid box. Example: <code>arrivalGridMaxLat = 90</code>


<code>arrivalAltMin = -100</code>
;arrivalGridDx (float)
: longitude increment of arrival (target region) grid. Example: <code>arrivalGridDx = 1</code>


- '''arrivalAltMax (float):'''
;arrivalGridDy (float)
: latitude increment of arrival (target region) grid. Example: <code>arrivalGridDy = 1</code>


<code>arrivalAltMax = 12000</code>
;arrivalGridRadius (float)
: gridding radius for information from arriving trajectories. Example: <code>arrivalGridRadius = 200</code>


- '''analyzeVapour (boolean):'''
;sourceGridMinLon (float)
: minimum longitude of moisture source grid box. Example: <code>sourceGridMinLon = -180</code>


<code>analyzeVapour = 0</code>
;sourceGridMaxLon (float)
: maximum longitude of moisture source grid box. Example: <code>sourceGridMaxLon = 180</code>


- '''assignToUptake (boolean):'''
;sourceGridMinLat (float)
: minimum latitude of moisture source grid box. Example: <code>sourceGridMinLat = -90</code>


<code>assignToUptake = 0</code>
;sourceGridMaxLat (float)
: maximum latitude of moisture source grid box. Example: <code>sourceGridMaxLat = 90</code>  


- '''forwardProjectionMode (integer):'''
;sourceGridDx (float)
: longitude increment of moisture source grid box. Example: <code>sourceGridDx = 1</code>


<code>forwardProjectionMode = 3</code>
;sourceGridDy (float)
: latitude increment of moisture source grid box. Example: <code>sourceGridDy = 1</code>


- '''relativeThreshold (boolean):'''
;sourceGridRadius (float)
: longitude increment of moisture source grid box. Example: <code>sourceGridRadius = 200</code>


<code>relativeThreshold = 1</code>
;griddingType (integer)
: select [[#gridding algorithm]] (1: fast and simple gridding, 2: improved but slower gridding). Example: <code>griddingType = 2</code>


====Parameter set Output====
----
- '''stepFile (boolean):''' write parameters on grid and series files for each time step


<code>stepFile = 1</code>
====Parameter set Diagnostics====


- '''dayFile (boolean):''' write parameters on grid and series files averaged/accumulated for each day
The parameters in this category control the way how the diagnostic works, and which trajectories should be considered in the run.


<code>dayFile = 1</code>
;uptakeThreshold (float)
: Threshold value for specific humidity increases per time step in air parcels to be considered as due to physical processes (evaporation), in g per kg. If the parameter reativeThresholds is set to true, the uptakeThreshold is specified as percent increase relative to the current specific humidity of an air parcel. Value is positive because of an air-parcel relative perspective. Default absolute values are 0.1 to 0.2 for 3h and 6h time steps. Example: <code>uptakeThreshold = 0.2</code>


- '''monthFile (boolean):''' write parameters on grid and series files averaged/accumulated for each month
;precipThreshold (float)
: Threshold value for specific humidity decreases per time step in air parcels to be considered as due to physical processes (precipitation), in g per kg. Value is negative because of an air-parcel relative perspective. If the parameter reativeThresholds is set to true, the precipThreshold is specified as percent decrease relative to the current specific humidity of an air parcel. Then the value is negative. Default absolute values are -0.1 to -0.2 for 3h and 6h time steps. Example: <code>precipThreshold = -0.2</code>


<code>monthFile = 1</code>
;relativeThreshold (boolean)
: determines whether absolute threshold values or relative threshold values are specified (0: absolute, 1: relative threshold values). Example: <code>relativeThreshold = 1</code>


- '''yearFile (boolean):''' write parameters on grid and series files averaged/accumulated for each year
;arrivalPrecipMin (float)
: Threshold value to consider precipitation events with a specific humidity decrease larger than the value given by <code>arrivalPrecipMin</code>. Units are g per kg when relativeThresholds is set to false, and fractional specific humidity decrease otherwise. For consistency, it is recommended to set the values for <code>precipitationThreshold</code> and <code>arrivalPrecipMin</code> to the same number. Example: <code>arrivalPrecipMin = -0.2</code>


<code>yearFile = 1</code>
;arrivalPrecipMax (float)
: Threshold value to consider precipitation events with a specific humidity decrease of up to the value given by <code>arrivalprecipMin</code>. Units are g per kg when relativeThresholds is set to false, and fractional specific humidity decrease otherwise. To include all precipitation events with a 6h time step, a value of -100.0 or lower can be chosen if <code>relativeThresholds</code> is set to false, or a value of 1.0 otherwise. The combination of the <code>arrivalPrecipMin/Max</code> parameters allows to focus on heavy and weak precipitation events only. Example: <code>arrivalPrecipMax = -100.0</code>


- '''allFile (boolean):''' write parameters on grid and series files averaged/accumulated for all time steps
;arrivalRHMin (float)
: Threshold value to consider precipitation events when relative humidity at the arrival location is larger than the value given by . Example: <code>arrivalRHMin</code>. Units are %. Large-scale condensation can be assumed to occur above 80% relative humidity, to include convective cloud processes a lower threshold value may be required. Example: <code>arrivalRHMin = 80</code>


<code>allFile = 1</code>
;arrivalRHMax (float)
: Threshold value to consider precipitation events when relative humidity at the arrival location is less than the value given by . Example: <code>arrivalRHMax</code>. Units are %. This parameter in combination with <code>arrivalRHMin</code> can be used to focus on condensation/no condensation cases when the parameter <code>analyzeVapour</code> is set to true. Example: <code>arrivalRHMax = 110</code>


- '''staticFields (boolean):''' write static fields (land-sea mask and topography) onto grid files
;arrivalOroMin (float)
: Threshold value to consider only arrival locations where the ETOPO2 topography exceeds the given value (in m). Use negative value to include all global locations, including ocean areas, Bangladesh and Death Valley. Example: <code>arrivalOroMin = -100</code>


<code>staticFields = 1</code>
;arrivalOroMax (float)
: Threshold value to consider only arrival locations where the ETOPO2 topography does not exceed the given value (in m). In combination with . Example: <code>arrivalOroMin</code>, regions with a complex shape but common elevation can be selected easily. Example: <code>arrivalOroMax = 12000</code>


- '''saveTraj (integer):''' write particle trajectories to [[traj files]] at each time step (1) or each month (2). Option 0 disables trajectory output.
;arrivalAltMin (float)
: Threshold value to consider only arrival locations where the air parcels are above at the given altitude (in m above sea level). Example: <code>arrivalAltMin = -100</code>


<code>saveTraj = 0</code>
;arrivalAltMax (float)
: Threshold value to consider only arrival locations where the air parcels are below the given altitude (in m above sea level). The parameters <code>arrivalAltMin/Max</code> can be used to conduct vertically stratified analyses.Example: <code>arrivalAltMax = 12000</code>


- '''skipTraj (boolean):''' write every nth trajectory to reduce traj file size (0 or 1:disabled, >=2: stride size)
;blhScale (float)
: Scaling factor to decide for air parcels to be close enough to the boundary layer to consider moisture increases to evaporation to be likely due to surface evaporation below. A factor of 1.5 will assign all moisture increases within 1.5x the current boundary layer height to the category 'moisture sources boundary-layer', all others to the category 'moisture sources free troposphere'. Default value is 1.5. Example: <code>blhScale = 1.5</code>


<code>skipTraj = 0</code>
;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is set to false, the weighting of source, transport and arrival properties is done using the precipitation estimate calculated from the specific humidity change during arrival. Otherwise, the weight is provided by the arrival specific humidity. Example: <code>analyzeVapour = 1</code>


- '''saveHistogram (boolean):''' write histogram for selected parameters to a [[histogram file]] (0: disabled, 1:enabled)
;assignToUptake (boolean)
: Parameter determining the assignment of moisture uptake events to arrival time (0: disabled) or to uptake time step grid (1: enabled). The effect of this parameter will most clearly be visible on stepwise and daily output files. It can be used to relate evaporation events to the concurrent meteorological situation. Example: <code>assignToUptake = 0</code>


<code>saveHistogram = 0</code>
;forwardProjectionMode (integer)
: Parameter determining how the Lagrangian forward projection of [[#moisture source and moisture transport properties]] are calculated (1: only consider boundary-layer moisture uptakes, 2: only consider free-troposphere uptakes, 3: consider both uptakes in combination). The default value is 3 (both, boundary layer and free-troposphere uptakes). Example: <code>forwardProjectionMode = 3</code>


- '''saveMean (boolean):''' write means, minimum, maximum and standard deviation to [[mean file]]. This is duplicate information with the series files but available for historical reasons. The option will be removed in a forthcoming version (0: disabled, 1:enabled).
----


<code>saveMean = 0</code>
====Parameter set Output====


The parameters in this category determine which output files should be created.


====Parameter set Variables====
;stepFile (boolean)
: write parameters on [[#Grid files]] and [[#Series files]] for each time step. Example: <code>stepFile = 1</code>


- '''sourcesBoundaryLayer (boolean):'''
;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>


<code>sourcesBoundaryLayer = 1</code>
;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>


- '''sourcesFreeTroposphere (boolean):'''
;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>


<code>sourcesFreeTroposphere = 1</code>
;allFile (boolean)
: write parameters on grid and series files averaged/accumulated for all time steps. Example: <code>allFile = 1</code>


- '''evaporationMinusPrecipitation (boolean):'''
;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</code>


<code>evaporationMinusPrecipitation = 1</code>
;saveTraj (integer)
: write particle trajectories to [[#Trajectory files]] at each time step (1) or each month (2). Option 0 disables trajectory output. Example: <code>saveTraj = 0</code>


- '''moistureTransport (boolean):'''
;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>


<code>moistureTransport = 1</code>
;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <code>saveHistogram = 0</code>


- '''trajectoryLocations (boolean):'''
;saveMean (boolean)
: write means, minimum, maximum and standard deviation to [[#Mean file]]. This is duplicate information with the series files but available for historical reasons. The option will be removed in a forthcoming version (0: disabled, 1:enabled). Example: <code>saveMean = 0</code>


<code>trajectoryLocations = 1</code>
----


- '''precipitationEstimate (boolean):'''
====Parameter set Variables====


<code>precipitationEstimate = 1</code>
The parameters in this category allow to include or exclude specific variables from the output files. Setting the output for unused variables to 0 (disabled) will speed up computation time, reduce the memory footprint, and reduce the output file size. Only parameters that are really required from a run should therefore selected as enabled.


- '''sourceLongitude (boolean):'''
;sourcesBoundaryLayer (boolean)
: write accounted moisture uptakes in the boundary layer to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: <code>sourcesBoundaryLayer = 1</code>


<code>sourceLongitude = 1</code>
;sourcesFreeTroposphere (boolean)
: write accounted moisture uptakes in the free troposphere to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: <code>sourcesFreeTroposphere = 1</code>


- '''sourceLatitude (boolean):'''
;evaporationMinusPrecipitation (boolean)
: write unweighted evaporation minus precipitation along entire trajectory length to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: <code>evaporationMinusPrecipitation = 1</code>


<code>sourceLatitude = 1</code>
;moistureTransport (boolean)
: write weighted moisture transport along trajectories to grid and series output files (0: disabled, 1: enabled). Units are mm. Example: <code>moistureTransport = 1</code>


- '''convectionCount (boolean):'''
;trajectoryLocations (boolean)
: write trajectory locations to grid and series output files (0: disabled, 1: enabled). Units are counts per km<sup>2</sup>. Example: <code>trajectoryLocations = 1</code>


<code>convectionCount = 0</code>
;precipitationEstimate (boolean)
: write precipitation estimate at arrival to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: <code>precipitationEstimate = 1</code>


- '''convectionHeight (boolean):'''
;sourceLongitude (boolean)
: write weighted moisture source longitude projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are degrees longitude. Example: <code>sourceLongitude = 1</code>


<code>convectionHeight = 0</code>
;sourceLatitude (boolean)
: write moisture source latitude projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are degrees latitude. Example: <code>sourceLatitude = 1</code>


- '''landFraction (boolean):'''
;convectionCount (boolean)
: write convection count projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are counts per km<sup>2</sup>. Convection count can be written to the FLEXPART particle files with a special version of FLEXPART_WATER. convectionCount is not on the ERA-Interim climatology run. The counter is increased each time the particles passes the convection scheme upwards. Example: <code>convectionCount = 0</code>


<code>landFraction = 1</code>
;convectionHeight (boolean)
: write convection height projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Convection height can be written to the FLEXPART particle files with a special version of FLEXPART_WATER. convectionHeight is not on the ERA-Interim climatology run. The value gives an average height of vertical displacement when the particles passes the convection scheme. Example: <code>convectionHeight = 0</code>


- '''boundaryLayerFraction (boolean):'''
;landFraction (boolean)
: write fraction of moisture sources over land projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: <code>landFraction = 1</code>


<code>boundaryLayerFraction = 1</code>
;boundaryLayerFraction (boolean)
: write accounted fraction of boundary layer uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: <code>boundaryLayerFraction = 1</code>


- '''freeTroposphereFraction (boolean):'''
;freeTroposphereFraction (boolean)
: write accounted fraction of free troposphere uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: <code>freeTroposphereFraction = 1</code>


<code>freeTroposphereFraction = 1</code>
;combinedFraction (boolean)
: write accounted fraction of boundary layer and free troposphere uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). This is the sum of the two previous variables. Example: <code>combinedFraction = 0</code>


- '''combinedFraction (boolean):'''
;transportTime (boolean)
: write moisture transport time projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are hours. Example: <code>transportTime = 1</code>


<code>combinedFraction = 0</code>
;sourceSkinTemperature (boolean)
: write skin temperature at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that skin temperature is a variable on the particle or trajectory files. Example: <code>sourceSkinTemperature = 1</code>


- '''transportTime (boolean):'''
;sourceSpecificHumidity (boolean)
: write surface specific humidity at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are g per kg. Requires that source specific humidity is a variable on the particle or trajectory files. Example: <code>sourceSpecificHumidity = 0</code>


<code>transportTime = 1</code>
;transportDistance (boolean)
: write transport distance projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Transport distance is the length of the actual travel path along the trajectories from moisture source to the arrival region. Example: <code>transportDistance = 1</code>


- '''sourceSkinTemperature (boolean):'''
;sourceDistance (boolean)
: write source distance projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Source distance is the shortest distance between the moisture source and the arrival region. Example: <code>sourceDistance = 1</code>


<code>sourceSkinTemperature = 1</code>
;source2mTemperature (boolean)
: write 2m temperature at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Example: <code>source2mTemperature = 0</code>


- '''sourceSpecificHumidity (boolean):'''
;sourceDeuteriumExcess (boolean)
: write deuterium excess projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are permil. Deuterium excess is calculated from the relative humidity with respect to SST and the relationship from Pfahl and Sodemann (2014). Requires that source specific humidity is a variable on the particle or trajectory files. Example: <code>sourceDeuteriumExcess = 1</code>


<code>sourceSpecificHumidity = 0</code>
;transportTemperature (boolean)
: write moisture-weighted temperature during transport projected to arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Example: <code>transportTemperature = 1</code>


- '''transportDistance (boolean):'''
;transportPressure (boolean)
: write moisture-weighted pressure during transport projected to arrival region to grid and series output files (0: disabled, 1: enabled). Units are hPa. Example: <code>transportPressure = 1</code>


<code>transportDistance = 1</code>
;condensationTemperature (boolean)
: write moisture-weighted temperatures where RH<sub>liquid</sub> exceeds 80% to grid and series output files (0: disabled, 1: enabled). Units are K. Example: <code>condensationTemperature = 1</code>


- '''sourceDistance (boolean):'''
;arrivalTemperature (boolean)
: write temperature during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Example: <code>arrivalTemperature = 1</code>


<code>sourceDistance = 1</code>
;arrivalPressure (boolean)
: write pressure during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are hPa. Example: <code>arrivalPressure = 1</code>


- '''source2mTemperature (boolean):'''
;arrival2mTemperature (boolean)
: write temperature at 2m during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that 2m temperature is a variable on the particle or trajectory files. Example: <code>arrival2mTemperature = 0</code>


<code>source2mTemperature = 0</code>
;arrivalSkinTemperature (boolean)
: write skin temperature during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that skin temperature is a variable on the particle or trajectory files. Example: <code>arrivalSkinTemperature = 1</code>


- '''sourceDeuteriumExcess (boolean):'''
----


<code>sourceDeuteriumExcess = 1</code>
====Parameter set Flexpart====


- '''transportTemperature (boolean):'''
The parameters in this category describe the properties specific to FLEXPART input files.


<code>transportTemperature = 1</code>
;inputFormat (integer)
: file format of FLEXPART particle position output files. 0: regional long output format, 1: global analysis data output format, 2: regional short format, 3: global reanalysis/NorESM data short format, 4: global reanalysis data long format, 5 regional reanalysis/NorESM data short format. Example: <code>inputFormat = 3</code>


- '''transportPressure (boolean):'''
;maxPart (integer)
: number of particles contained in a single FLEXPART partposit or shortposit file. Example: <code>maxPart = 5000000</code>


<code>transportPressure = 1</code>
;partMass (float)
: atmospheric mass represented by each particle in kilogramms. Parameter is written out by specific version of FLEXPART to create WaterSip output data. Example: <code>partMass = 1.01943e+12</code>


- '''condensationTemperature (boolean):'''
;partStride (integer)
: number of particles to skip during processing to speed up calculations (1: use every particle, >=2: use every 2nd particle, etc). Example: <code>partStride = 10</code>


<code>condensationTemperature = 1</code>
;allowReenter (boolean): needs to be enabled for global simulations, and disabled for regional domain-filling runs to avoid double accounting of air parcels (0: disabled, 1: enabled). Example: <code>allowReenter = 1</code>


- '''arrivalTemperature (boolean):'''
----


<code>arrivalTemperature = 1</code>
====Parameter set Lagranto====


- '''arrivalPressure (boolean):'''
The parameters in this category describe the properties specific to FLEXPART input files.


<code>arrivalPressure = 1</code>
;partMass (float)
: atmospheric mass represented by each particle in kilogramms. The value for partMass depends on how the trajectories are arriving. They should be arriving on a regular starting grid (fixed horizontal distance), and fixed vertical distance (in delta p). Then one can calculate the value for partMass as dx*dy*dp with dx and dy in km, and dp in Pa. Internally, this number will then be multiplied with 1e6/g to obtain kg. (In a later version, this will change this so one directly specifies the partMass in kg). Example: <code>partMass = 1.01943e+12</code>


- '''arrival2mTemperature (boolean):'''
----
 
<code>arrival2mTemperature = 0</code>
 
- '''arrivalSkinTemperature (boolean):'''
 
<code>arrivalSkinTemperature = 1</code>
 
====Parameter set Flexpart====
 
- '''inputFormat (integer):''' file format of FLEXPART particle position output files. 0: regional long output format, 1: global analysis data output format, 2: regional short format, 3: global reanalysis data short format
 
<code>inputFormat = 3</code>
 
- '''maxPart (integer):''' number of particles contained in a single FLEXPART partposit or shortposit file
 
<code>maxPart = 5000000</code>
 
- '''partMass (float):''' atmospheric mass represented by each particle in kilogramms. Parameter is written out by specific version of FLEXPART to create WaterSip output data.
 
<code>partMass = 1.01943e+12</code>
 
- '''partStride (integer):''' number of particles to skip during processing to speed up calculations (1: use every particle, >=2: use every 2nd particle, etc).
 
<code>partStride = 10</code>
 
- '''allowReenter (boolean):''' needs to be enabled for global simulations, and disabled for regional domain-filling runs to avoid double accounting of air parcels (0: disabled, 1: enabled).
 
<code>allowReenter = 1</code>


===Full example for a FLEXPART run input file:===
===Full example for a FLEXPART run input file:===
Line 437: Line 519:
[Case]
[Case]
caseName = global_201002_final_relativex
caseName = global_201002_final_relativex
inputDir = /Volumes/Data_B/flexpart/global/shortposit_%s
inputDir = /home/data/flexpart/global/shortposit_%s
outputDir=/Volumes/Data_B/watersip/global_201002_V3/
outputDir=/home/data/watersip/global_201002_V3/
startDate = 20100228-180000
startDate = 20100228-180000
endDate = 20100211-000000
endDate = 20100211-000000
timeStep = 6
timeStep = 6
sectorizeRegion = 0
sectorizeRegion = 0
filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
filterBoxFile = /home/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
filterIndex = -1
filterIndex = -1
orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc"
orographyFile = "/home/projects/WaterSip_tool/etopo5.nc"
lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/ERA_sea_mask_inv.nc"
lsmFile = "/home/projects/WaterSip_tool/ERA_sea_mask_inv.nc"
maskFile = " "
maskFile = " "
useMask = 0
useMask = 0
Line 537: Line 619:
allowReenter = 1
allowReenter = 1
</pre>
</pre>
===Output file formats===
The results from the WaterSip diagnostic are written to a set of output files in different format. The main output files are created in netCDF with detailed metadata information, including the parameter settings of the run for automated documentation. The creation of different output files can be adapted by parameter settings in parameter set *Output* and the contained variables with settings in parameter set *Variables*. Spatial fields at different time intervals are written to so-called grid files in [[netCDF]] format, time series of averaged quantities at different time intervals are written to so-called Series files in netCDF format, histograms of selected quantities identified during the processing for each time step and each trajectory are written to Histogram files in ASCII format, and trajectories are written to Trajectory files in either the binary format traj or the Lagranto ASCII format. Earlier versions than V3 reported output in so-called Mean files in an ASCII format. That format is documented here but no longer in use in current versions of WaterSip.
The time unit has changed in Version 3.1. Previously, the unit was set to "days since 0000-01-02 00:00:00" to allow matlab-compatible values for time that could directly be utilized with the datenum() commands. In order to confirm to netCDF-CF standards, where no calendar year 0000 exists, the time unit is now "days since 0001-01-01 00:00:00". This provides the ability to open and visualize netCDF output files directly with tools such as ncview and panoply. To convert the time values into a matlab datenum compatible value, the following commands have to be used:
<pre>
ncid=netcdf.open(filename,"noclobber");
tim=(float)netcdf.getVar(ncid,"time");
tim=tim-datenum(1,0,1);
datestr(tim)
</pre>
The table below summarizes the available output files:
{| class="wikitable"
! Name !! Content !! Format !! Filename
|-
| Grid files || Spatial properties of moisture sources and arrival regios || netCDF || CASE_grd_all/year/month/day/step.nc
|-
| Series files || Mean/min/max/std of regionally and globally averaged moisture source and arrival region properties || netCDF || CASE_ser_all/year/month/day/step.nc
|-
| Histogram files || Histograms of quantities identified for each timestep along each trajectory || ASCII || CASE_hst_steps
|-
| Trajectory files || Trajectories for identified precipitation events || ASCII/binary traj || CASE_DATE.traj/CASE_DATE_lsl
|}
====Grid files====
Grid file variables are separated into immediate source and transport variables, typically on a coarser, global grid, and arrival and forward-projected variables on the (typically finer-scale) arrival grid. The grid settings are determined by the corresponding parameters in parameter set *Grid*. All variables are of type float, and the fill value (netCDF property _FillValue) is -999.99. The averaging over time steps, as required by different grid files, is done by weighting each time step contribution with the corresponding precipitation estimate, and dividing by the total precipitation (as described above).
**Moisture source and transport properties**
Variables related to immediate moisture source and transport properties (not forward projected) have dimension of variables time, global_latitude, global_longitude, as defined by input file parameters *sourceGridMinLon,sourceGridMaxLon, sourceGridMinLat, sourceGridMaxLat, sourceGridDx, sourceGridDy, sourceGridRadius*.
The moisture sources are contained in the variables "moisture_uptakes_boundary_layer" and "moisture_uptakes_free_troposphere". The "moisture_transport" variable is a gridded map of the water vapour traced to the target region, and can help you identify transport pathways (weighted by humidity). The "trajectory_location" is a gridded map of all trajectory points, regardless of the air parcel humidity. In most current analyses, it is recommended to sum the two moisture_uptake_xx variables, except when one wants to distinguish the influence from convection on the moisture source diagnostic.
{| class="wikitable"
! Name !! Symbol !! Units !! Description
|-
| moisture_uptakes_boundary_layer || E_s^BL || mm (step)h^-1 or mm 24h^-1 || text
|-
| moisture_uptakes_free_troposphere || E_s^FT || mm (step)h^-1 or mm 24h^-1 || text
|-
| evaporation_minus_precipitation || E-P || mm (step)h^-1 or mm 24h^-1 || text
|-
| moisture_transport || Q_t || mm ||  text
|-
| trajectory_location || N_t || counts km^-2 || text
|}
**Arrival properties and Lagrangian forward projections**
The variables contained in these files have the dimensions time (days since 0001-01-01 00:00:00), latitude (degrees_north), and longitude (degrees_east) as defined by input file parameters *arrivalGridMinLon, arrivalGridMaxLon, arrivalGridMinLat, arrivalGridMaxLat, arrivalGridDx, arrivalGridDy, arrival | source | text |GridRadius*.
{| class="wikitable"
! Name !! Symbol !! Unit !! Property !! Description
|-
| precipitation_estimate || PE || mm day^-1 or mm step^-1 || arrival || precipitation at arrival location estimated from change in specific humidity during last time step
|-
| arrival_temperature || T_a || K || arrival || PE-weighted temperature at trajectory location and elevation during arrival
|-
| arrival_pressure || p_a || hPa || arrival || PE-weighted pressure at trajectory location and elevation during arrival
|-
| arrival_skin_temperature || SKT_a || K || arrival || PE-weighted SKT below trajectory location during arrival
|-
| accounted_fraction_boundary_layer || f_BL || fraction || arrival || fractional contribution of BL moisture sources to PE
|-
| accounted_fraction_free_troposphere || f_FT || fraction || arrival || fractional contribution of FT moisture sources to PE
|-
| precipitation_lifetime || \tau_t || h || transport || contribution and precipitation-weighted precipitation life time
|-
| transport_distance || \Delta_t || km || transport || contribution and precipitation-weighted transport distance along trajectory
|-
| moisture_transport_temperature || T_t || K || transport || contribution and precipitation-weighted temperature during moisture transport
|-
| moisture_transport_pressure || p_t || hPa || transport || contribution and precipitation-weighted pressure during moisture transport
|-
| condensation_temperature || T_c || K || transport || contribution and precipitation-weighted temperature when RH>80% during transport
|-
| source_longitude || \lambda_s || degrees_east || source || contribution and precipitation-weighted latitude of the moisture source
|-
| source_latitude || \phi_s || degrees_north || source || contribution and precipitation-weighted longitude of the moisture source
|-
| land_fraction || f_l || fraction || source || contribution and precipitation-weighted fraction of moisture sources over land
|-
| source_skin_temperature || SKT_s || K || source || contribution and precipitation-weighted SKT at the moisture source
|-
| source_distance || \Delta_s || km || source || contribution and precipitation-weighted direct distance between the moisture source and arrival location
|-
| deuterium_excess || d_s || permil || source || contribution and precipitation-weighted estimate of deuterium excess at the source from RH and T using the Pfahl and Sodemann (2013) relation
|}
**Global attributes**
The netCDF grid files contain a range of essential parameters as global attributes. These parameters allow to fully characterise the result of the WaterSip run as required for the interpretation of the results. A number of run parameters are omitted, that concern logistical settings, or that are self-evident from the content of the the output files. The table below gives an example for a WaterSip run:
{| class="wikitable"
! Parameter !! Example !! Type
|-
| startDate || "2010-02-28 00:00:00 +0000" || string
|-
| endingDate || "2010-01-11 00:00:00 +0000" || string
|-
| analysisRegion || "NEEM" || string
|-
| maxPart || 5000001  || int
|-
| caseName || "global_201002_V3_stride" || string
|-
| trajPoints || 61  || int
|-
| timeStep || 6  || in float
|-
| partMass || 2.03885996E12  ||  float
|-
| dryLevel || 0.01  || float
|-
| blhScale || 1.5  ||  float
|-
| rhMin || 80.0  ||  float
|-
| rhMax || 110.0  ||  float
|-
| uptakeThreshold || 0.2  ||  float
|-
| precipThreshold || -0.2  || float
|-
| arrPrecipMin || -0.2  || float
|-
| arrPrecipMax || -120.0  || float
|-
| arrOroMin || 0.0  || float
|-
| arrOroMax || 9000.0  || float
|-
| arrAltMin || 0.0  || float
|-
| arrAltMax || 9000.0  || float
|-
| anaVapour || 0  || int
|-
| filterIndex || -1  || int
|}
====Series files====
The netCDF series files contain two sets of information. The so-called sectorization output provides time series of the moisture source information seperated into relative contributions from predefined geographical areas. Furthermore, the series files contains weighted averages and further statistical properties of all quantities in the grid files.
**Sectorisation output**
A set of sectorisations is chosen by the parameter *sectorizeRegion*. The currently available options are listed in the table below. New sectorisations can be defined by changing the code in routine <code>Sectors.cpp/Sectors.h</code>. This requires defining a new name and new decision tree that provides a unique number for any lat/lon value between -180E to 180E and -90 to 90N. See comments in the code.
For each of the predefined areas, the relative contributions are subdivided into land and sea covered areas. Time series of the contributions are of dimension time and sector. Thereby, the sector numbers correspond to the sector numbers defined in the program code. The area of the sectors is calculated automatically within WaterSip. As noted above for the grid files, the time unit has been changed starting from Version 3.1.
{| class="wikitable"
! Variable !! Symbol !! Unit !! Description
|-
| time || t || days since 0001-01-01 00:00:00 || text
|-
| sector || s || sector number || text
|-
| sector_area || A_s || km^2 || text
|-
| land_fraction_moisture_uptakes_boundary_layer || f_l^BL || percent || text
|-
| sea_fraction_moisture_uptakes_boundary_layer || f_s^BL || percent || text
|-
| land_fraction_moisture_uptakes_free_troposphere || f_l^FT || percent || text
|-
| sea_fraction_moisture_uptakes_free_troposphere || f_s^FT || percent || text
|-
| land_fraction_trajectory_location || f_l^N || percent || text
|-
| sea_fraction_trajectory_location || f_s^N || percent || text
|-
| land_fraction_moisture_transport || f_l^Q || percent || text
|-
| sea_fraction_moisture_transport || f_s^Q || percent || text
|-
| land_fraction_evaporation_minus_precipitation || f_l^EP || percent || text
|-
| sea_fraction_evaporation_minus_precipitation | f_s^EP | percent | text
|}
**Time-series output**
For immediate quantities, a time series of the total field sum is recorded in the series file. In order to obtain an area average, one needs to divide the sum by the surface of the earth (x km^2). The unit for moisture uptakes, E-P and precipitation estimate is mm step^-1 for step series files, and mm 24h^-1 for all other averaging series files. In addition to sums, the files contain time series of the minimum, maximum and standard deviation of the grid field at each time instance. For all forward-projected and arrival quantities, the average rather than the sum is calculated on the arrival grid locations. When averaging from step output to larger time intervals, the quantities are weighted with the corresponding PE at each grid point.
In addition, series files contain the same set of global attributes as described in Grid files to enable interpretation without additional documentation of the run setup.
*Immediate quantities*
{| class="wikitable"
! Variable !! Symbol  !! Unit
|-
| moisture_uptakes_boundary_layer_min || x  || mm (step or 24h)^-1
|-
| moisture_uptakes_boundary_layer_sum || x  || mm (step or 24h)^-1
|-
| moisture_uptakes_boundary_layer_max || x  || mm (step or 24h)^-1
|-
| moisture_uptakes_free_troposphere_min || x  || mm (step or 24h)^-1
|-
| moisture_uptakes_free_troposphere_sum || x  || mm (step or 24h)^-1
|-
| moisture_uptakes_free_troposphere_max || x  || mm (step or 24h)^-1
|-
| evaporation_minus_precipitation_min || x  || mm (step or 24h)^-1
|-
| evaporation_minus_precipitation_sum || x  || mm (step or 24h)^-1
|-
| evaporation_minus_precipitation_max || x  || mm (step or 24h)^-1
|-
| moisture_transport_min || x  || mm
|-
| moisture_transport_sum || x  || mm
|-
| moisture_transport_max || x  || mm
|-
| trajectory_location_min || x  || counts km^-2
|-
| trajectory_location_sum || x  || counts km^-2
|-
| trajectory_location_max || x  || counts km^-2
|-
| precipitation_estimate_min || x  || mm (step or 24h)^-1
|-
| precipitation_estimate_sum || x  || mm (step or 24h)^-1
|-
| precipitation_estimate_max || x  || mm (step or 24h)^-1
|}
*Arrival and forward-projected quantities*
{| class="wikitable"
! Variable !! Symbol  !! Unit
|-
| source_longitude_min || x  || degrees_east
|-
| source_longitude_avg || x  || degrees_east
|-
| source_longitude_max || x  || degrees_east
|-
| source_latitude_min || x  || degrees_north
|-
| source_latitude_avg || x  || degrees_north
|-
| source_latitude_max || x  || degrees_north
|-
| land_fraction_min || x  || fraction
|-
| land_fraction_avg || x  || fraction
|-
| land_fraction_max || x  || fraction
|-
| accounted_fraction_boundary_layer_min || x  || fraction
|-
| accounted_fraction_boundary_layer_avg || x  || fraction
|-
| accounted_fraction_boundary_layer_max || x  || fraction
|-
| accounted_fraction_free_troposphere_min || x  || fraction
|-
| accounted_fraction_free_troposphere_avg || x  || fraction
|-
| accounted_fraction_free_troposphere_max || x  || fraction
|-
| transport_time_min || x  || hours_before_arrival
|-
| transport_time_avg || x  || hours_before_arrival
|-
| transport_time_max || x  || hours_before_arrival
|-
| source_skin_temperature_min || x  || K
|-
| source_skin_temperature_avg || x  || K
|-
| source_skin_temperature_max || x  || K
|-
| transport_distance_min || x  || km
|-
| transport_distance_avg || x  || km
|-
| transport_distance_max || x  || km
|-
| source_distance_min || x  || km
|-
| source_distance_avg || x  || km
|-
| source_distance_max || x  || km
|-
| deuterium_excess_min || x  || permil
|-
| deuterium_excess_avg || x  || permil
|-
| deuterium_excess_max || x  || permil
|-
| moisture_transport_temperature_min || x  || K
|-
| moisture_transport_temperature_avg || x  || K
|-
| moisture_transport_temperature_max || x  || K
|-
| moisture_transport_pressure_min || x  || hPa
|-
| moisture_transport_pressure_avg || x  || hPa
|-
| moisture_transport_pressure_max || x  || hPa
|-
| condensation_temperature_min || x  || K
|-
| condensation_temperature_avg || x  || K
|-
| condensation_temperature_max || x  || K
|-
| arrival_temperature_min || x  || K
|-
| arrival_temperature_avg || x  || K
|-
| arrival_temperature_max || x  || K
|-
| arrival_pressure_min || x  || hPa
|-
| arrival_pressure_avg || x  || hPa
|-
| arrival_pressure_max || x  || hPa
|-
| arrival_skin_temperature_min || x  || K
|-
| arrival_skin_temperature_avg || x  || K
|-
| arrival_skin_temperature_max || x || K
|}
====Histogram files====
* Bounds freq (1 to n categories), (1 to m variables)
* Main variables time, dq, conv
* where to implement
<pre>
20.71  46.56  8.1351e+05  -1.0000e+00
21.22  45.90  1.1314e+06  -1.0000e+00
22.03  45.24  4.1929e+05  -1.0000e+00
21.19  45.35  1.0639e+06  -1.0000e+00
20.71  46.50  5.0963e+05  -1.0000e+00
21.07  47.51  2.8182e+05  -1.0000e+00
21.71  48.67  9.3088e+05  -1.0000e+00
22.14  51.47  2.3634e+05  -1.0000e+00
22.14  52.49  8.0048e+05  -1.0000e+00
22.34  53.76  7.3297e+05  -1.0000e+00
23.17  54.41  4.1516e+05  -1.0000e+00
23.56  54.54  2.7414e+05  -1.0000e+00
24.39  54.55  5.0017e+05  -1.0000e+00
26.89  54.42  2.8215e+05  -1.0000e+00
28.18  54.40  3.9987e+05  -1.0000e+00
29.80  54.25  3.6020e+05  -1.0000e+00
</pre>
====Trajectory files====
**LSL format**
* As documented elsewhere
* only some variables
* Code location
<pre>
example
</pre>
**Traj format**
* Binary format, only some variables
* Code location
* reading in and plotting traj files
<pre>
example
</pre>
====Mean file====
Legacy format, global_201002_V3_avg_steps
<pre>
20100228_00 13795.603  0.001 7994.128  0.001 722561152.000 1977998.875  -0.081  -3.124    0.007  -0.080  -1.347  0.003  0.181  0.000  0.001  0.711  0.006  0.001  0.242  0.000  0.001 -999.990 -999.990 -999.990  -83.283 -340.404    0.153  288.231  242.846    0.050 -999.990 -999.990 -999.990  2828.54    120.41      7.50
</pre>
===Annotated bibliography===
There are to date (Oct 2019) 25 publications involving the WaterSip method in one way or another. The versatility of WaterSip ranges from weather events to climatological studies, and from process understanding to paleoclimate proxy interpretation. This documentation can only provide initial guidance in applying WaterSip to new research plans. The annotated bibliography below provides an overview over the relevant studies, ordered by topic and the respective climatic zone.
{| class="wikitable"
! Topic !! Time perspective !! Climate zone !! Region !! Reference
|-
| Method description || - || High latitudes || Greenland || Sodemann et al., 2008a
|-
| Precipitation extremes || Climatology || Subtropics || Mediterranean || Winschall et al., 2014a
|-
| Method evaluation || Weather event || Subtropics || Mediterranean || Winschall et al., 2014b
|-
| Lifetime of precipitation || Climatology || Global || Global || Läderach and Sodemann, 2016
|-
| Climate proxy interpretation || Climatology || High latitudes || Greenland || Sodemann et al., 2008b
|-
| Climate characteristics || Climatology || Mid latitudes || Europe || Sodemann and Zubler, 2010
|-
| Climate proxy interpretation || Climatology || Tropics || Belize || Kenneth et al.,
|-
| Climate proxy interpretation || Climatology || Mid latitudes || China || Baker et al., Luetscher et al.
|}
===References===
* Thurnherr, I., Kozachek, A., Graf, P., Weng, Y., Bolshiyanov, D., Landwehr, S., Pfahl, S., Schmale, J., Sodemann, H., Steen-Larsen, H. C., Toffoli, A., Wernli, H., and Aemisegger, F., 2019: Meridional and vertical variations of the water vapour isotopic composition in the marine boundary layer over the Atlantic and Southern Ocean, Atmos. Chem. Phys. Discuss., doi: 10.5194/acp-2019-782.
* Fremme, A. and Sodemann, H., 2019: The role of land and ocean evaporation on the variability of precipitation in the Yangtze River valley, Hydrol. Earth Syst. Sci., 23, 2525–2540, doi: 10.5194/hess-23-2525-2019.
* Huang, R, Zhu, H, Liang, E., Grießinger, J, Wernicke, J., Yu, W., Hochreuther, P., Risi, C., Zeng, Y., Fremme, A., Sodemann, H., Bräuning, A., 2019: Temperature signals in tree-ring oxygen isotope series from the northern slope of the Himalaya, EPSL 506: 455-465.
* Buizert, Christo; Sigl, Michael; Severi, Mirko; Markle, Bradley; Wettstein, Justin; McConnell, J; Pedro, Joel; Sodemann, H.; Goto-Azuma, Kumiko; Kawamura, Kenji; Fujita, Shuji; Motoyama, Hideaki; Hirabayashi, Motohiro; Uemura, Ryu; Stenni, Barbara; Parrenin, Frederic; He, Feng; Fudge, T.J.; Steig, Eric J., 2018: Abrupt ice-age shifts in southern westerly winds and Antarctic climate forced from the north, Nature 563: 681-685.
* Bohlinger, P., Sorteberg, A., Liu, C., Rasmussen, R., Sodemann, H., Ogawa, F., 2018: Multiscale characteristics of an extreme precipitation event over Nepal. QJRMS:1-18, doi:10.1002/qj.3418.
* Bohlinger, P., Sorteberg, A., and Sodemann, H., 2017: Synoptic conditions and moisture sources actuating extreme precipitation in Nepal. Journal of Geophysical Research: Atmospheres, 122, 12,653–12,671. https://doi.org/10.1002/2017JD027543.
* Blazina, T., A. Läderach, G. D. Jones, H. Sodemann, H. Wernli, J. W. Kirchner and L. H. E. Winkel, 2016: Marine primary productivity as a potential source of selenium and other trace elements in atmospheric deposition, Environ. Sci. Technol. 2017, 51, 108−118, doi: 10.1021/acs.est.6b03063.
* Läderach, A. andSodemann, H., 2016: A revised picture of the atmospheric moisture residence time, Geophys. Res. Lett., 43, doi:10.1002/2015GL067449.
* Baker, A., Sodemann, H., Baldini, J. U. L., Breitenbach, S. F. M., Johnson, K. R., van Hunen, J., and Pingzhong, Z., 2015: Seasonality of westerly moisture transport in the East Asian Summer Monsoon and its implications for interpreting precipitation d18O, J. Geophys. Res., 120,  doi:10.1002/2014JD022919.
* Steen-Larsen, H. C., Sveinbjörnsdottir, A. E., Jonsson, T., Ritter, F., Bonne, J.-L., Masson-Delmotte, V., Sodemann, H., Blunier, T., Dahl-Jensen, D., Vinther, B. M., 2015: Moisture sources and synoptic to seasonal variability of North Atlantic water vapor isotopic composition, J. Geophys. Res., 120, 5757–5774, doi:10.1002/ 2015JD023234.
* Bonne, J.-L., Steen-Larsen, H. C., Risi, C., Werner, M., Sodemann, H., Lacour, J.-L., Fettweis, X., Cesana, G., Delmotte, M., Cattani, O., Vallelonga, P., Kjær, H. A., Clerbaux, C., Sveinbjörnsdóttir, A. E., and Masson-Delmotte, V., 2015: The summer 2012 Greenland heat wave: In situ and remote sensing observations of water vapor isotopic composition during an atmospheric river event, J. Geophys. Res., 120, 2970-2989, doi:10.1002/2014JD022602.
* Luetscher, M., Boch, R., Sodemann, H., Spoetl, C., Cheng, H., Edwards, R. L., Frisia, S., Hof, F., Mueller, W., 2015: North Atlantic storm track changes during the Last Glacial Maximum recorded by Alpine speleothems, Nature Comm. 6: 6344, doi:10.1038/ncomms7344.
* Winschall, A., Sodemann, H.,Pfahl, S. and Wernli, H., 2014: How important is intensified evaporation for Mediterranean precipitation extremes?, J. Geophys. Res., 119: 5240–5256, doi:10.1002/2013JD021175
* Winschall, A., Pfahl, S., Sodemann, H.and Wernli, H.. 2014. Comparison of Eulerian and Lagrangian moisture source diagnostics - the flood event in eastern Europe in May 2010, Atmos. Chem. Phys. 14: 6605–6619, doi:10.5194/acp-14-6605-2014.
* Aemisegger, F., Pfahl, S., Sodemann, H., Lehner, I., Seneviratne, S. I., and Wernli, H., 2014: Deuterium excess as a proxy for continental moisture recycling and plant transpiration, Atmos. Chem. Phys., 14: 4029–4054, doi:10.5194/acp-14-4029-2014.
* Bonne, J. L., Masson-Delmotte, V., Cattani, O., Delmotte, M., Risi, C., Sodemann, H., and Steen-Larsen, H. C., 2014:The isotopic composition of water vapour and precipitation in Ivittuut, southern Greenland, Atmos. Chem. Phys. 14: 4419–4439, doi:10.5194/acp-14-4419-2014.
* Wang, Y., Sodemann, H., Hou, S., Masson-Delmotte, V. Jouzel, J. and Pang, H., 2013: Snow accumulation and its moisture origin over Dome Argus, Antarctica. Clim. Dyn., 40:731-742, doi: 10.1007/s00382-012-1398-9.
* Martius, O., Sodemann, H., Joos, H., Pfahl, S., Winschall, A., Croci-Maspoli, M., Graf, M., Madonna, E., Mueller, B., Schemm, S., Sedlacek, J., Sprenger, M. and Wernli, H., 2012: The role of upper-level dynamics and surface processes for the Pakistan flood in July 2010. Quart. J. Royal Meteorol. Soc., published online, doi: 10.1002/qj.2082.
* Kennett, D. J., Breitenbach, S. F. M., Aquino, V. V., Asmerom, Y., Awe, J., Baldini, J. U. L., Bartlein, P., Culleton, B. J., Ebert, C., Jazwa, C., Macri, M. J., Marwan, N., Polyak, V., Prufer, K. M., Ridley, H. E., Sodemann, H., Winterhalder, B. and Haug, G. H., 2012: Development and Disintegration of Maya Political Systems in Response to Climate Change. Science, 338: 788-791, doi: 10.1126/science.1226299.
* Winkler, R., Landais, A., Sodemann, H., Dümbgen, L., Priéa, F., Masson-Delmotte, V., Stenni, B., and Jouzel, J., 2012: Deglaciation records of 17O-excess in East Antarctica: reliable reconstruction of oceanic relative humidity from coastal sites. Clim. Past 8, 1-16.
* Masson-Delmotte, V., Buiron, D., Ekaykin, A., Frezzotti, M., Gallée, H., Jouzel, J., Krinner, G., Landais, A., Motoyama, A., Oerter, H., Pol, K., Pollard, D., Ritz, C., Schlosser, E., Sime, L. C., Sodemann, H., Stenni, B., Uemura R., and Vimeux, F., 2011: A comparison of the present and last interglacial periods in six Antarctic ice cores Clim. Past, 7, 397-423.
* Sodemann, H.and Zubler, E., 2010: Seasonality and inter-annual variability of the moisture sources for Alpine precipitation during 1995-2002, Int. J. Climatol., 30: 947-961, doi:10.1002/joc.1932.
* Sodemann, H., and Stohl, A., 2009: Asymmetries in the moisture origin of Antarctic precipitation, Geophys. Res. Lett., 36, L22803, doi:10.1029/2009GL040242.
* Sodemann, H., Masson-Delmotte, V., Schwierz, C., Vinther, B. M. and Wernli, H., 2008: Inter-annual variability of Greenland winter precipitation sources. Part II: Effects of North Atlantic Oscillation variability on stable isotopes in precipitation, J. Geophys. Res., 113, D12111, doi:10.1029/2007JD009416.
* Sodemann, H., Schwierz, C., and Wernli, H., 2008: Inter-annual variability of Greenland winter precipitation sources. Lagrangian moisture diagnostic and North Atlantic Oscillation influence, J. Geophys. Res.,113, D03107, doi:10.1029/2007JD008503.

Latest revision as of 11:10, 7 March 2022

About WaterSip

WaterSip is a diagnostic software tool that identifies source, transport and arrival properties of atmospheric water vapour based on airmass backward trajectories. As a prerequisite, the backward trajectories for the analysis are to be obtained from a trajectory calculation tool, such as FLEXPART [[1]] or Lagranto [[2]]. Moisture sources are then identified from changes in specific humidity interpolated to the air parcel trajectory per time step. The changes in specific humidity at each time step are set in relation with the current humidity of the air parcel. This allows to estimate the quantitative contribution of moisture to the air parcel at a specific location, a so-called moisture accounting. WaterSip identifies and aggregates further properties of the moisture source and during the moisture transport, such as temperature, pressure, latitude etc. The moisture source diagnostic is described in detail in Sodemann et al. (2008). Publications using the WaterSip diagnostic are listed in section Bibliography.

Working principle

Explanation from Sodemann et al. 2008a

Image from Läderach and Sodemann, 2016 or Sodemann et al., 2008a

Moisture source information

- Accounted fraction fa, fb, fa+fb - adding below and above boundary layer or not, when - choosing threshold values for Arctic and other regions - identifying moisture transport

Arrival information and Lagrangian forward projections

- arrival parameters - transport parameters - source parameters - averaging by contribution and amount

Series information

- sectorization (Sodemann and Zubler, 2010; definition table, code changes) - weighted averaging: The averaging over time steps, as required by different grid files, is done by weighting each time step contribution with the corresponding precipitation estimate, and deviding by the total precipitation.

Averaged properties

- histogram example and modification (code below)

Trajectories

- plotting/reading example (code below)

Uncertainties

Example setups

Three examples with different purposes

Water vapour

- considerations and parameters

Extratropical precipitation

- considerations and parameters

High latitude precipitation

- considerations and parameters

Version history

Version 2.1

Version 2.2

Version 2.3

Version 2.4

Version 2.5

Version 2.8

Version 2.8.1

Version 2.9

Version 2.9.1

Version 2.9.2

Version 2.9.3

Version 2.9.4

Version 3.0.8

Version 3.1

The current version of WaterSip is V3.1.0.

Running the WaterSip diagnostic

It is advised to create a link to the binary file of WaterSip in your /home/$USER/bin or project directory:

mkdir ~/bin
ln -s /Data/gfi/projects/isomet/progs/WaterSip_tool/WaterSip3 ~/bin

Adding ~/bin to your path will make execution of WaterSip more comfortable. To start a diagnostic run, WaterSip needs to be called from the command line. This version reads one single input file during startup which contains all parameter settings required to execute a run (the examples below assume that you are in a working directory and WaterSip3 is at a location in your $PATH environment variable):

module load netCDF-C++
WaterSip3 <WATERSIP_parameter_file>

Note that the UiB hpc environment requires the above 'module load' command to be executed first.

On cyclone.hpc.uib.no, a run script is available that makes repeated similar runs easier to manage. Only essential parameters have to be changed, such as the target coordinates and case name. These will then be replaced on a template INPUT_WATERSIP file, and then WaterSip will be started. The script and an input file template can be copied like this:

cp /Data/gfi/projects/isomet/projects/watersip/Bergen_iso/run_watersip_template_Bergen_2018.sh .
cp /Data/gfi/projects/isomet/projects/watersip/Bergen_iso/INPUT_WATERSIP_template_Bergen_2018 .

Input file conversion from V2

The input file format, described below, is quite different in V3 than in previous versions. To facilite transition from V2.x input files, there is an option execute WaterSip3 with the option -c to convert to the new V3 input file format:

WaterSip3 -c <WATERSIP_V2_parameter_file>

This will create a new file named <WATERSIP_V2_parameter_file>V3 at the current directory. It is recommended to double check and edit the settings in the converted file before starting a simulation.

Parallelization

WaterSip3 has been parallelized with OpenMP, which can significantly speed up calculation time. The number of processors to be used is specified in the input file (see below).

If WaterSip3 is to be executed on a queue system (not applicable to cyclone.hpc.uib.no), the following wrapper script can be used to start a run using 4 cores for parallel processing:

# start with sbatch NAME_OF_THIS_FILE directly on machine

#SBATCH --job-name=WaterSip3
#SBATCH --workdir=/tmp/
#SBATCH --partition=priority
#SBATCH --output=WaterSip_job.%j.out
#SBATCH --error=WaterSip_job.%j.err
#SBATCH --mail-type=END
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4

srun ./WaterSip3 INPUT_WATERSIP_global_1993

Creating mask files

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]

Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]

Watersip mask-guide cut.png Figure: Example for Scandinavia

Basic principle:

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed). This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points). After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.

Input:

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

Output:

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to [[3]]

Python program code available here|

Input file options

The WaterSip input file is a text file with options that are specified for different option groups. Option groups are identified by square brackets (e.g. [Case]). There are 7 option groups which can appear in random order in the input file:

  • Case: general settings related to the case to be extracted
  • Grids: specification of different output grids
  • Diagnostrics: parameters of the moisture diagnostic
  • Output: general output settings
  • Variables: selection of output variables
  • Flexpart: options specific to runs using FLEXPART particle output
  • Lagranto: options specific to runs using Lagranto trajectories

Parameter set Case

The settings in this parameter category describe the basic conditions of the diagnostic run.

caseName (string)
identifier for the run, prepended to all output files. Example: caseName = global_201002_relative
inputDir (string)
search path of the input files. The inputDir string ends with a placeholder for the files to be read in. For FLEXPART this will be either shortposit_ or partposit_. For Lagranto this will commonly be lsl_. The %s placeholder is completed by the currently read in date at runtime. Example: inputDir = /Volumes/Data/global/shortposit_%s
outputDir (string)
path where the output files will be created. Example: outputDir = /Volumes/Data/global/output/
startDate (date string)
inital date of the run, fixed format YYYYMMDD-HHMMSS. Start date is latest date of the run which moves backward in time. Example: startDate = 20100228-180000
endDate (date string)
final date of the run, fixed format YYYYMMDD-HHMMSS. End date is earliest date of the run. Example: endDate = 20100211-000000
timeStep (integer)
time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours)). Example: timeStep = 6
trajPoints (integer)
number of trajectory points to be considered in a trajectory. For 5-day trajectories with a 6 hour time step, 5x4+1=21 trajPoints should be selected. Example: trajPoints = 21
minTrajPoints (integer)
minimum length of trajectories to be included in analysis. Parameter is only relevant for Lagranto simulations with uneven trajectory length. Example: minTrajPoints = 0
sectorizeRegion (integer)
region set used to divide moisture sources into different sectors (see #sectorization). Example: sectorizeRegion = 0
filterBoxFile (string)
path to the text file describing geographic boxes used to filter air parcels during transport (see #box filters). Example: filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
filterIndex (integer)
used line from the filterBoxFile to select/deselect trajectories. Example: filterIndex = -1
orographyFile (string)
path to the orography file used to select arrival based on underying topography, using the ETOPO2 topography. File in netcdf format. Example: orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc"
lsmFile (string)
path to the file with global land-sea-mask, currently from ERA-Interim data. Domain must be global but is in principle arbitrary. File in netcdf format. Example: lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/ERA_sea_mask_inv.nc"
maskFile (string)
path to file with an arrival selection. Example: maskFile = " "
useMask (boolean)
use mask file (0=no, 1=yes). Example: useMask = 0
ompThreads (integer)
number of threads to be used with OpenMP parallelisation if compiled with flag -fopenmp (1=no parallelisation, >1 parallelisation activated.). Example: ompThreads = 1
showStats (boolean)
print statistics about particle processing to the command line (0=off, 1=on). Example: showStats = 0

Parameter set Grids

The parameters in this category specify the different output grids and the gridding method

arrivalGridMinLon (float)
minimum longitude of arrival (target region) grid box. Trajectories are traced backward from the arrival grid. Integrated source, transport and arrival parameters are put on the arrival grid, weighted by precipitation or water vapour of arriving air parcels. Example: arrivalGridMinLon = -180
arrivalGridMaxLon (float)
maximum longitude of arrival (target region) grid box. Example: arrivalgridmaxlon = 180
arrivalGridMinLat (float)
minimum latitude of arrival (target region) grid box. Example: arrivalGridMinLat = -90
arrivalGridMaxLat (float)
minimum latitude of arrival (target region) grid box. Example: arrivalGridMaxLat = 90
arrivalGridDx (float)
longitude increment of arrival (target region) grid. Example: arrivalGridDx = 1
arrivalGridDy (float)
latitude increment of arrival (target region) grid. Example: arrivalGridDy = 1
arrivalGridRadius (float)
gridding radius for information from arriving trajectories. Example: arrivalGridRadius = 200
sourceGridMinLon (float)
minimum longitude of moisture source grid box. Example: sourceGridMinLon = -180
sourceGridMaxLon (float)
maximum longitude of moisture source grid box. Example: sourceGridMaxLon = 180
sourceGridMinLat (float)
minimum latitude of moisture source grid box. Example: sourceGridMinLat = -90
sourceGridMaxLat (float)
maximum latitude of moisture source grid box. Example: sourceGridMaxLat = 90
sourceGridDx (float)
longitude increment of moisture source grid box. Example: sourceGridDx = 1
sourceGridDy (float)
latitude increment of moisture source grid box. Example: sourceGridDy = 1
sourceGridRadius (float)
longitude increment of moisture source grid box. Example: sourceGridRadius = 200
griddingType (integer)
select #gridding algorithm (1: fast and simple gridding, 2: improved but slower gridding). Example: griddingType = 2

Parameter set Diagnostics

The parameters in this category control the way how the diagnostic works, and which trajectories should be considered in the run.

uptakeThreshold (float)
Threshold value for specific humidity increases per time step in air parcels to be considered as due to physical processes (evaporation), in g per kg. If the parameter reativeThresholds is set to true, the uptakeThreshold is specified as percent increase relative to the current specific humidity of an air parcel. Value is positive because of an air-parcel relative perspective. Default absolute values are 0.1 to 0.2 for 3h and 6h time steps. Example: uptakeThreshold = 0.2
precipThreshold (float)
Threshold value for specific humidity decreases per time step in air parcels to be considered as due to physical processes (precipitation), in g per kg. Value is negative because of an air-parcel relative perspective. If the parameter reativeThresholds is set to true, the precipThreshold is specified as percent decrease relative to the current specific humidity of an air parcel. Then the value is negative. Default absolute values are -0.1 to -0.2 for 3h and 6h time steps. Example: precipThreshold = -0.2
relativeThreshold (boolean)
determines whether absolute threshold values or relative threshold values are specified (0: absolute, 1: relative threshold values). Example: relativeThreshold = 1
arrivalPrecipMin (float)
Threshold value to consider precipitation events with a specific humidity decrease larger than the value given by arrivalPrecipMin. Units are g per kg when relativeThresholds is set to false, and fractional specific humidity decrease otherwise. For consistency, it is recommended to set the values for precipitationThreshold and arrivalPrecipMin to the same number. Example: arrivalPrecipMin = -0.2
arrivalPrecipMax (float)
Threshold value to consider precipitation events with a specific humidity decrease of up to the value given by arrivalprecipMin. Units are g per kg when relativeThresholds is set to false, and fractional specific humidity decrease otherwise. To include all precipitation events with a 6h time step, a value of -100.0 or lower can be chosen if relativeThresholds is set to false, or a value of 1.0 otherwise. The combination of the arrivalPrecipMin/Max parameters allows to focus on heavy and weak precipitation events only. Example: arrivalPrecipMax = -100.0
arrivalRHMin (float)
Threshold value to consider precipitation events when relative humidity at the arrival location is larger than the value given by . Example: arrivalRHMin. Units are %. Large-scale condensation can be assumed to occur above 80% relative humidity, to include convective cloud processes a lower threshold value may be required. Example: arrivalRHMin = 80
arrivalRHMax (float)
Threshold value to consider precipitation events when relative humidity at the arrival location is less than the value given by . Example: arrivalRHMax. Units are %. This parameter in combination with arrivalRHMin can be used to focus on condensation/no condensation cases when the parameter analyzeVapour is set to true. Example: arrivalRHMax = 110
arrivalOroMin (float)
Threshold value to consider only arrival locations where the ETOPO2 topography exceeds the given value (in m). Use negative value to include all global locations, including ocean areas, Bangladesh and Death Valley. Example: arrivalOroMin = -100
arrivalOroMax (float)
Threshold value to consider only arrival locations where the ETOPO2 topography does not exceed the given value (in m). In combination with . Example: arrivalOroMin, regions with a complex shape but common elevation can be selected easily. Example: arrivalOroMax = 12000
arrivalAltMin (float)
Threshold value to consider only arrival locations where the air parcels are above at the given altitude (in m above sea level). Example: arrivalAltMin = -100
arrivalAltMax (float)
Threshold value to consider only arrival locations where the air parcels are below the given altitude (in m above sea level). The parameters arrivalAltMin/Max can be used to conduct vertically stratified analyses.Example: arrivalAltMax = 12000
blhScale (float)
Scaling factor to decide for air parcels to be close enough to the boundary layer to consider moisture increases to evaporation to be likely due to surface evaporation below. A factor of 1.5 will assign all moisture increases within 1.5x the current boundary layer height to the category 'moisture sources boundary-layer', all others to the category 'moisture sources free troposphere'. Default value is 1.5. Example: blhScale = 1.5
analyzeVapour (boolean)
Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the precipitationThreshold and arrivalRHMin/Max parameters also need modification. Typically, one will set the precipitation threshold to a small or even positive number, and the arrivalRHMin to 0 and arrivalRHMax to 110 to include all arriving trajectories. It is often preferrable then to set the arrivalAltMax to values of around 1000m for surface station measurements, for example. If analyzeVapour is set to false, the weighting of source, transport and arrival properties is done using the precipitation estimate calculated from the specific humidity change during arrival. Otherwise, the weight is provided by the arrival specific humidity. Example: analyzeVapour = 1
assignToUptake (boolean)
Parameter determining the assignment of moisture uptake events to arrival time (0: disabled) or to uptake time step grid (1: enabled). The effect of this parameter will most clearly be visible on stepwise and daily output files. It can be used to relate evaporation events to the concurrent meteorological situation. Example: assignToUptake = 0
forwardProjectionMode (integer)
Parameter determining how the Lagrangian forward projection of #moisture source and moisture transport properties are calculated (1: only consider boundary-layer moisture uptakes, 2: only consider free-troposphere uptakes, 3: consider both uptakes in combination). The default value is 3 (both, boundary layer and free-troposphere uptakes). Example: forwardProjectionMode = 3

Parameter set Output

The parameters in this category determine which output files should be created.

stepFile (boolean)
write parameters on #Grid files and #Series files for each time step. Example: stepFile = 1
dayFile (boolean)
write parameters on grid and series files averaged/accumulated for each day. Example: dayFile = 1
monthFile (boolean)
write parameters on grid and series files averaged/accumulated for each month. Example: monthFile = 1
yearFile (boolean)
write parameters on grid and series files averaged/accumulated for each year. Example: yearFile = 1
allFile (boolean)
write parameters on grid and series files averaged/accumulated for all time steps. Example: allFile = 1
staticFields (boolean)
write static fields (land-sea mask and topography) onto grid files. Example: staticFields = 1
saveTraj (integer)
write particle trajectories to #Trajectory files at each time step (1) or each month (2). Option 0 disables trajectory output. Example: saveTraj = 0
skipTraj (boolean)
write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: skipTraj = 1
saveHistogram (boolean)
write histogram for selected parameters to a #Histogram files (0: disabled, 1:enabled). Example: saveHistogram = 0
saveMean (boolean)
write means, minimum, maximum and standard deviation to #Mean file. This is duplicate information with the series files but available for historical reasons. The option will be removed in a forthcoming version (0: disabled, 1:enabled). Example: saveMean = 0

Parameter set Variables

The parameters in this category allow to include or exclude specific variables from the output files. Setting the output for unused variables to 0 (disabled) will speed up computation time, reduce the memory footprint, and reduce the output file size. Only parameters that are really required from a run should therefore selected as enabled.

sourcesBoundaryLayer (boolean)
write accounted moisture uptakes in the boundary layer to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: sourcesBoundaryLayer = 1
sourcesFreeTroposphere (boolean)
write accounted moisture uptakes in the free troposphere to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: sourcesFreeTroposphere = 1
evaporationMinusPrecipitation (boolean)
write unweighted evaporation minus precipitation along entire trajectory length to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: evaporationMinusPrecipitation = 1
moistureTransport (boolean)
write weighted moisture transport along trajectories to grid and series output files (0: disabled, 1: enabled). Units are mm. Example: moistureTransport = 1
trajectoryLocations (boolean)
write trajectory locations to grid and series output files (0: disabled, 1: enabled). Units are counts per km2. Example: trajectoryLocations = 1
precipitationEstimate (boolean)
write precipitation estimate at arrival to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: precipitationEstimate = 1
sourceLongitude (boolean)
write weighted moisture source longitude projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are degrees longitude. Example: sourceLongitude = 1
sourceLatitude (boolean)
write moisture source latitude projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are degrees latitude. Example: sourceLatitude = 1
convectionCount (boolean)
write convection count projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are counts per km2. Convection count can be written to the FLEXPART particle files with a special version of FLEXPART_WATER. convectionCount is not on the ERA-Interim climatology run. The counter is increased each time the particles passes the convection scheme upwards. Example: convectionCount = 0
convectionHeight (boolean)
write convection height projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Convection height can be written to the FLEXPART particle files with a special version of FLEXPART_WATER. convectionHeight is not on the ERA-Interim climatology run. The value gives an average height of vertical displacement when the particles passes the convection scheme. Example: convectionHeight = 0
landFraction (boolean)
write fraction of moisture sources over land projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: landFraction = 1
boundaryLayerFraction (boolean)
write accounted fraction of boundary layer uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: boundaryLayerFraction = 1
freeTroposphereFraction (boolean)
write accounted fraction of free troposphere uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: freeTroposphereFraction = 1
combinedFraction (boolean)
write accounted fraction of boundary layer and free troposphere uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). This is the sum of the two previous variables. Example: combinedFraction = 0
transportTime (boolean)
write moisture transport time projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are hours. Example: transportTime = 1
sourceSkinTemperature (boolean)
write skin temperature at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that skin temperature is a variable on the particle or trajectory files. Example: sourceSkinTemperature = 1
sourceSpecificHumidity (boolean)
write surface specific humidity at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are g per kg. Requires that source specific humidity is a variable on the particle or trajectory files. Example: sourceSpecificHumidity = 0
transportDistance (boolean)
write transport distance projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Transport distance is the length of the actual travel path along the trajectories from moisture source to the arrival region. Example: transportDistance = 1
sourceDistance (boolean)
write source distance projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Source distance is the shortest distance between the moisture source and the arrival region. Example: sourceDistance = 1
source2mTemperature (boolean)
write 2m temperature at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Example: source2mTemperature = 0
sourceDeuteriumExcess (boolean)
write deuterium excess projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are permil. Deuterium excess is calculated from the relative humidity with respect to SST and the relationship from Pfahl and Sodemann (2014). Requires that source specific humidity is a variable on the particle or trajectory files. Example: sourceDeuteriumExcess = 1
transportTemperature (boolean)
write moisture-weighted temperature during transport projected to arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Example: transportTemperature = 1
transportPressure (boolean)
write moisture-weighted pressure during transport projected to arrival region to grid and series output files (0: disabled, 1: enabled). Units are hPa. Example: transportPressure = 1
condensationTemperature (boolean)
write moisture-weighted temperatures where RHliquid exceeds 80% to grid and series output files (0: disabled, 1: enabled). Units are K. Example: condensationTemperature = 1
arrivalTemperature (boolean)
write temperature during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Example: arrivalTemperature = 1
arrivalPressure (boolean)
write pressure during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are hPa. Example: arrivalPressure = 1
arrival2mTemperature (boolean)
write temperature at 2m during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that 2m temperature is a variable on the particle or trajectory files. Example: arrival2mTemperature = 0
arrivalSkinTemperature (boolean)
write skin temperature during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that skin temperature is a variable on the particle or trajectory files. Example: arrivalSkinTemperature = 1

Parameter set Flexpart

The parameters in this category describe the properties specific to FLEXPART input files.

inputFormat (integer)
file format of FLEXPART particle position output files. 0: regional long output format, 1: global analysis data output format, 2: regional short format, 3: global reanalysis/NorESM data short format, 4: global reanalysis data long format, 5 regional reanalysis/NorESM data short format. Example: inputFormat = 3
maxPart (integer)
number of particles contained in a single FLEXPART partposit or shortposit file. Example: maxPart = 5000000
partMass (float)
atmospheric mass represented by each particle in kilogramms. Parameter is written out by specific version of FLEXPART to create WaterSip output data. Example: partMass = 1.01943e+12
partStride (integer)
number of particles to skip during processing to speed up calculations (1: use every particle, >=2: use every 2nd particle, etc). Example: partStride = 10
allowReenter (boolean)
needs to be enabled for global simulations, and disabled for regional domain-filling runs to avoid double accounting of air parcels (0: disabled, 1: enabled). Example: allowReenter = 1

Parameter set Lagranto

The parameters in this category describe the properties specific to FLEXPART input files.

partMass (float)
atmospheric mass represented by each particle in kilogramms. The value for partMass depends on how the trajectories are arriving. They should be arriving on a regular starting grid (fixed horizontal distance), and fixed vertical distance (in delta p). Then one can calculate the value for partMass as dx*dy*dp with dx and dy in km, and dp in Pa. Internally, this number will then be multiplied with 1e6/g to obtain kg. (In a later version, this will change this so one directly specifies the partMass in kg). Example: partMass = 1.01943e+12

Full example for a FLEXPART run input file:

[Case]
caseName = global_201002_final_relativex
inputDir = /home/data/flexpart/global/shortposit_%s
outputDir=/home/data/watersip/global_201002_V3/
startDate = 20100228-180000
endDate = 20100211-000000
timeStep = 6
sectorizeRegion = 0
filterBoxFile = /home/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
filterIndex = -1
orographyFile = "/home/projects/WaterSip_tool/etopo5.nc"
lsmFile = "/home/projects/WaterSip_tool/ERA_sea_mask_inv.nc"
maskFile = " "
useMask = 0
trajPoints = 41
minTrajPoints = 0
ompThreads = 1
showStats = 0

[Grids]
arrivalGridMinLon = -180
arrivalGridMaxLon = 180
arrivalGridMinLat = -90
arrivalGridMaxLat = 90
arrivalGridDx = 1
arrivalGridDy = 1
arrivalGridRadius = 200
sourceGridMinLon = -180
sourceGridMaxLon = 180
sourceGridMinLat = -90
sourceGridMaxLat = 90
sourceGridDx = 1
sourceGridDy = 1
sourceGridRadius = 200
griddingType = 2

[Diagnostics]
uptakeThreshold = 0.05
precipThreshold = 0.05
blhScale = 1.5
arrivalPrecipMin = 0.05
arrivalPrecipMax = 1.0
arrivalRHMin = 80
arrivalRHMax = 110
arrivalOroMin = -100
arrivalOroMax = 12000
arrivalAltMin = -100
arrivalAltMax = 12000
analyzeVapour = 0
assignToUptake = 0
forwardProjectionMode = 3
relativeThreshold = 1

[Output]
stepFile = 1
dayFile = 1
monthFile = 1
yearFile = 1
allFile = 1
staticFields = 1
saveTraj = 0
skipTraj = 0
saveHistogram = 0
saveMean = 0

[Variables]
sourcesBoundaryLayer = 1
sourcesFreeTroposphere = 1
evaporationMinusPrecipitation = 1
moistureTransport = 1
trajectoryLocations = 1
precipitationEstimate = 1
sourceLongitude = 1
sourceLatitude = 1
convectionCount = 0
convectionHeight = 0
landFraction = 1
boundaryLayerFraction = 1
freeTroposphereFraction = 1
combinedFraction = 0
transportTime = 1
sourceSkinTemperature = 1
sourceSpecificHumidity = 0
transportDistance = 1
sourceDistance = 1
source2mTemperature = 0
sourceDeuteriumExcess = 1
transportTemperature = 1
transportPressure = 1
condensationTemperature = 1
arrivalTemperature = 1
arrivalPressure = 1
arrival2mTemperature = 0
arrivalSkinTemperature = 1

[Flexpart]
inputFormat = 3
maxPart = 5000000
partMass = 1.01943e+12
partStride = 10
allowReenter = 1

Output file formats

The results from the WaterSip diagnostic are written to a set of output files in different format. The main output files are created in netCDF with detailed metadata information, including the parameter settings of the run for automated documentation. The creation of different output files can be adapted by parameter settings in parameter set *Output* and the contained variables with settings in parameter set *Variables*. Spatial fields at different time intervals are written to so-called grid files in netCDF format, time series of averaged quantities at different time intervals are written to so-called Series files in netCDF format, histograms of selected quantities identified during the processing for each time step and each trajectory are written to Histogram files in ASCII format, and trajectories are written to Trajectory files in either the binary format traj or the Lagranto ASCII format. Earlier versions than V3 reported output in so-called Mean files in an ASCII format. That format is documented here but no longer in use in current versions of WaterSip.

The time unit has changed in Version 3.1. Previously, the unit was set to "days since 0000-01-02 00:00:00" to allow matlab-compatible values for time that could directly be utilized with the datenum() commands. In order to confirm to netCDF-CF standards, where no calendar year 0000 exists, the time unit is now "days since 0001-01-01 00:00:00". This provides the ability to open and visualize netCDF output files directly with tools such as ncview and panoply. To convert the time values into a matlab datenum compatible value, the following commands have to be used:

ncid=netcdf.open(filename,"noclobber");
tim=(float)netcdf.getVar(ncid,"time");
tim=tim-datenum(1,0,1);
datestr(tim)

The table below summarizes the available output files:

Name Content Format Filename
Grid files Spatial properties of moisture sources and arrival regios netCDF CASE_grd_all/year/month/day/step.nc
Series files Mean/min/max/std of regionally and globally averaged moisture source and arrival region properties netCDF CASE_ser_all/year/month/day/step.nc
Histogram files Histograms of quantities identified for each timestep along each trajectory ASCII CASE_hst_steps
Trajectory files Trajectories for identified precipitation events ASCII/binary traj CASE_DATE.traj/CASE_DATE_lsl

Grid files

Grid file variables are separated into immediate source and transport variables, typically on a coarser, global grid, and arrival and forward-projected variables on the (typically finer-scale) arrival grid. The grid settings are determined by the corresponding parameters in parameter set *Grid*. All variables are of type float, and the fill value (netCDF property _FillValue) is -999.99. The averaging over time steps, as required by different grid files, is done by weighting each time step contribution with the corresponding precipitation estimate, and dividing by the total precipitation (as described above).

    • Moisture source and transport properties**

Variables related to immediate moisture source and transport properties (not forward projected) have dimension of variables time, global_latitude, global_longitude, as defined by input file parameters *sourceGridMinLon,sourceGridMaxLon, sourceGridMinLat, sourceGridMaxLat, sourceGridDx, sourceGridDy, sourceGridRadius*.

The moisture sources are contained in the variables "moisture_uptakes_boundary_layer" and "moisture_uptakes_free_troposphere". The "moisture_transport" variable is a gridded map of the water vapour traced to the target region, and can help you identify transport pathways (weighted by humidity). The "trajectory_location" is a gridded map of all trajectory points, regardless of the air parcel humidity. In most current analyses, it is recommended to sum the two moisture_uptake_xx variables, except when one wants to distinguish the influence from convection on the moisture source diagnostic.

Name Symbol Units Description
moisture_uptakes_boundary_layer E_s^BL mm (step)h^-1 or mm 24h^-1 text
moisture_uptakes_free_troposphere E_s^FT mm (step)h^-1 or mm 24h^-1 text
evaporation_minus_precipitation E-P mm (step)h^-1 or mm 24h^-1 text
moisture_transport Q_t mm text
trajectory_location N_t counts km^-2 text
    • Arrival properties and Lagrangian forward projections**

The variables contained in these files have the dimensions time (days since 0001-01-01 00:00:00), latitude (degrees_north), and longitude (degrees_east) as defined by input file parameters *arrivalGridMinLon, arrivalGridMaxLon, arrivalGridMinLat, arrivalGridMaxLat, arrivalGridDx, arrivalGridDy, arrival | source | text |GridRadius*.

Name Symbol Unit Property Description
precipitation_estimate PE mm day^-1 or mm step^-1 arrival precipitation at arrival location estimated from change in specific humidity during last time step
arrival_temperature T_a K arrival PE-weighted temperature at trajectory location and elevation during arrival
arrival_pressure p_a hPa arrival PE-weighted pressure at trajectory location and elevation during arrival
arrival_skin_temperature SKT_a K arrival PE-weighted SKT below trajectory location during arrival
accounted_fraction_boundary_layer f_BL fraction arrival fractional contribution of BL moisture sources to PE
accounted_fraction_free_troposphere f_FT fraction arrival fractional contribution of FT moisture sources to PE
precipitation_lifetime \tau_t h transport contribution and precipitation-weighted precipitation life time
transport_distance \Delta_t km transport contribution and precipitation-weighted transport distance along trajectory
moisture_transport_temperature T_t K transport contribution and precipitation-weighted temperature during moisture transport
moisture_transport_pressure p_t hPa transport contribution and precipitation-weighted pressure during moisture transport
condensation_temperature T_c K transport contribution and precipitation-weighted temperature when RH>80% during transport
source_longitude \lambda_s degrees_east source contribution and precipitation-weighted latitude of the moisture source
source_latitude \phi_s  degrees_north source contribution and precipitation-weighted longitude of the moisture source
land_fraction f_l fraction source contribution and precipitation-weighted fraction of moisture sources over land
source_skin_temperature SKT_s K source contribution and precipitation-weighted SKT at the moisture source
source_distance \Delta_s km source contribution and precipitation-weighted direct distance between the moisture source and arrival location
deuterium_excess d_s permil source contribution and precipitation-weighted estimate of deuterium excess at the source from RH and T using the Pfahl and Sodemann (2013) relation
    • Global attributes**

The netCDF grid files contain a range of essential parameters as global attributes. These parameters allow to fully characterise the result of the WaterSip run as required for the interpretation of the results. A number of run parameters are omitted, that concern logistical settings, or that are self-evident from the content of the the output files. The table below gives an example for a WaterSip run:

Parameter Example Type
startDate "2010-02-28 00:00:00 +0000" string
endingDate "2010-01-11 00:00:00 +0000"  string
analysisRegion "NEEM" string
maxPart 5000001 int
caseName "global_201002_V3_stride" string
trajPoints 61 int
timeStep 6 in float
partMass 2.03885996E12 float
dryLevel 0.01 float
blhScale 1.5 float
rhMin 80.0 float
rhMax 110.0 float
uptakeThreshold 0.2 float
precipThreshold -0.2 float
arrPrecipMin -0.2 float
arrPrecipMax -120.0 float
arrOroMin 0.0 float
arrOroMax 9000.0 float
arrAltMin 0.0 float
arrAltMax 9000.0 float
anaVapour 0 int
filterIndex -1 int

Series files

The netCDF series files contain two sets of information. The so-called sectorization output provides time series of the moisture source information seperated into relative contributions from predefined geographical areas. Furthermore, the series files contains weighted averages and further statistical properties of all quantities in the grid files.

    • Sectorisation output**

A set of sectorisations is chosen by the parameter *sectorizeRegion*. The currently available options are listed in the table below. New sectorisations can be defined by changing the code in routine Sectors.cpp/Sectors.h. This requires defining a new name and new decision tree that provides a unique number for any lat/lon value between -180E to 180E and -90 to 90N. See comments in the code.

For each of the predefined areas, the relative contributions are subdivided into land and sea covered areas. Time series of the contributions are of dimension time and sector. Thereby, the sector numbers correspond to the sector numbers defined in the program code. The area of the sectors is calculated automatically within WaterSip. As noted above for the grid files, the time unit has been changed starting from Version 3.1.

Variable Symbol Unit Description
time t days since 0001-01-01 00:00:00 text
sector s sector number text
sector_area A_s km^2 text
land_fraction_moisture_uptakes_boundary_layer f_l^BL percent text
sea_fraction_moisture_uptakes_boundary_layer f_s^BL percent text
land_fraction_moisture_uptakes_free_troposphere f_l^FT percent text
sea_fraction_moisture_uptakes_free_troposphere f_s^FT percent text
land_fraction_trajectory_location f_l^N percent text
sea_fraction_trajectory_location f_s^N percent text
land_fraction_moisture_transport f_l^Q percent text
sea_fraction_moisture_transport f_s^Q percent text
land_fraction_evaporation_minus_precipitation f_l^EP percent text
f_s^EP | percent | text
    • Time-series output**

For immediate quantities, a time series of the total field sum is recorded in the series file. In order to obtain an area average, one needs to divide the sum by the surface of the earth (x km^2). The unit for moisture uptakes, E-P and precipitation estimate is mm step^-1 for step series files, and mm 24h^-1 for all other averaging series files. In addition to sums, the files contain time series of the minimum, maximum and standard deviation of the grid field at each time instance. For all forward-projected and arrival quantities, the average rather than the sum is calculated on the arrival grid locations. When averaging from step output to larger time intervals, the quantities are weighted with the corresponding PE at each grid point.

In addition, series files contain the same set of global attributes as described in Grid files to enable interpretation without additional documentation of the run setup.

  • Immediate quantities*
Variable Symbol Unit
moisture_uptakes_boundary_layer_min x mm (step or 24h)^-1
moisture_uptakes_boundary_layer_sum x mm (step or 24h)^-1
moisture_uptakes_boundary_layer_max x mm (step or 24h)^-1
moisture_uptakes_free_troposphere_min x mm (step or 24h)^-1
moisture_uptakes_free_troposphere_sum x mm (step or 24h)^-1
moisture_uptakes_free_troposphere_max x mm (step or 24h)^-1
evaporation_minus_precipitation_min x mm (step or 24h)^-1
evaporation_minus_precipitation_sum x mm (step or 24h)^-1
evaporation_minus_precipitation_max x mm (step or 24h)^-1
moisture_transport_min x mm
moisture_transport_sum x mm
moisture_transport_max x mm
trajectory_location_min x counts km^-2
trajectory_location_sum x counts km^-2
trajectory_location_max x counts km^-2
precipitation_estimate_min x mm (step or 24h)^-1
precipitation_estimate_sum x mm (step or 24h)^-1
precipitation_estimate_max x mm (step or 24h)^-1
  • Arrival and forward-projected quantities*
Variable Symbol Unit
source_longitude_min x degrees_east
source_longitude_avg x degrees_east
source_longitude_max x degrees_east
source_latitude_min x degrees_north
source_latitude_avg x degrees_north
source_latitude_max x degrees_north
land_fraction_min x fraction
land_fraction_avg x fraction
land_fraction_max x fraction
accounted_fraction_boundary_layer_min x fraction
accounted_fraction_boundary_layer_avg x fraction
accounted_fraction_boundary_layer_max x fraction
accounted_fraction_free_troposphere_min x fraction
accounted_fraction_free_troposphere_avg x fraction
accounted_fraction_free_troposphere_max x fraction
transport_time_min x hours_before_arrival
transport_time_avg x hours_before_arrival
transport_time_max x hours_before_arrival
source_skin_temperature_min x K
source_skin_temperature_avg x K
source_skin_temperature_max x K
transport_distance_min x km
transport_distance_avg x km
transport_distance_max x km
source_distance_min x km
source_distance_avg x km
source_distance_max x km
deuterium_excess_min x permil
deuterium_excess_avg x permil
deuterium_excess_max x permil
moisture_transport_temperature_min x K
moisture_transport_temperature_avg x K
moisture_transport_temperature_max x K
moisture_transport_pressure_min x hPa
moisture_transport_pressure_avg x hPa
moisture_transport_pressure_max x hPa
condensation_temperature_min x K
condensation_temperature_avg x K
condensation_temperature_max x K
arrival_temperature_min x K
arrival_temperature_avg x K
arrival_temperature_max x K
arrival_pressure_min x hPa
arrival_pressure_avg x hPa
arrival_pressure_max x hPa
arrival_skin_temperature_min x K
arrival_skin_temperature_avg x K
arrival_skin_temperature_max x K

Histogram files

  • Bounds freq (1 to n categories), (1 to m variables)
  • Main variables time, dq, conv
  • where to implement
20.71   46.56   8.1351e+05  -1.0000e+00
21.22   45.90   1.1314e+06  -1.0000e+00
22.03   45.24   4.1929e+05  -1.0000e+00
21.19   45.35   1.0639e+06  -1.0000e+00
20.71   46.50   5.0963e+05  -1.0000e+00
21.07   47.51   2.8182e+05  -1.0000e+00
21.71   48.67   9.3088e+05  -1.0000e+00
22.14   51.47   2.3634e+05  -1.0000e+00
22.14   52.49   8.0048e+05  -1.0000e+00
22.34   53.76   7.3297e+05  -1.0000e+00
23.17   54.41   4.1516e+05  -1.0000e+00
23.56   54.54   2.7414e+05  -1.0000e+00
24.39   54.55   5.0017e+05  -1.0000e+00
26.89   54.42   2.8215e+05  -1.0000e+00
28.18   54.40   3.9987e+05  -1.0000e+00
29.80   54.25   3.6020e+05  -1.0000e+00

Trajectory files

    • LSL format**
  • As documented elsewhere
  • only some variables
  • Code location
example
    • Traj format**
  • Binary format, only some variables
  • Code location
  • reading in and plotting traj files
example

Mean file

Legacy format, global_201002_V3_avg_steps

20100228_00 13795.603  0.001 7994.128  0.001 722561152.000 1977998.875   -0.081   -3.124    0.007  -0.080  -1.347   0.003   0.181   0.000   0.001   0.711   0.006   0.001   0.242   0.000   0.001 -999.990 -999.990 -999.990  -83.283 -340.404    0.153  288.231  242.846    0.050 -999.990 -999.990 -999.990   2828.54    120.41      7.50

Annotated bibliography

There are to date (Oct 2019) 25 publications involving the WaterSip method in one way or another. The versatility of WaterSip ranges from weather events to climatological studies, and from process understanding to paleoclimate proxy interpretation. This documentation can only provide initial guidance in applying WaterSip to new research plans. The annotated bibliography below provides an overview over the relevant studies, ordered by topic and the respective climatic zone.

Topic Time perspective Climate zone Region Reference
Method description - High latitudes Greenland Sodemann et al., 2008a
Precipitation extremes Climatology Subtropics Mediterranean Winschall et al., 2014a
Method evaluation Weather event Subtropics Mediterranean Winschall et al., 2014b
Lifetime of precipitation Climatology Global Global Läderach and Sodemann, 2016
Climate proxy interpretation Climatology High latitudes Greenland Sodemann et al., 2008b
Climate characteristics Climatology Mid latitudes Europe Sodemann and Zubler, 2010
Climate proxy interpretation Climatology Tropics Belize Kenneth et al.,
Climate proxy interpretation Climatology Mid latitudes China Baker et al., Luetscher et al.

References

  • Thurnherr, I., Kozachek, A., Graf, P., Weng, Y., Bolshiyanov, D., Landwehr, S., Pfahl, S., Schmale, J., Sodemann, H., Steen-Larsen, H. C., Toffoli, A., Wernli, H., and Aemisegger, F., 2019: Meridional and vertical variations of the water vapour isotopic composition in the marine boundary layer over the Atlantic and Southern Ocean, Atmos. Chem. Phys. Discuss., doi: 10.5194/acp-2019-782.
  • Fremme, A. and Sodemann, H., 2019: The role of land and ocean evaporation on the variability of precipitation in the Yangtze River valley, Hydrol. Earth Syst. Sci., 23, 2525–2540, doi: 10.5194/hess-23-2525-2019.
  • Huang, R, Zhu, H, Liang, E., Grießinger, J, Wernicke, J., Yu, W., Hochreuther, P., Risi, C., Zeng, Y., Fremme, A., Sodemann, H., Bräuning, A., 2019: Temperature signals in tree-ring oxygen isotope series from the northern slope of the Himalaya, EPSL 506: 455-465.
  • Buizert, Christo; Sigl, Michael; Severi, Mirko; Markle, Bradley; Wettstein, Justin; McConnell, J; Pedro, Joel; Sodemann, H.; Goto-Azuma, Kumiko; Kawamura, Kenji; Fujita, Shuji; Motoyama, Hideaki; Hirabayashi, Motohiro; Uemura, Ryu; Stenni, Barbara; Parrenin, Frederic; He, Feng; Fudge, T.J.; Steig, Eric J., 2018: Abrupt ice-age shifts in southern westerly winds and Antarctic climate forced from the north, Nature 563: 681-685.
  • Bohlinger, P., Sorteberg, A., Liu, C., Rasmussen, R., Sodemann, H., Ogawa, F., 2018: Multiscale characteristics of an extreme precipitation event over Nepal. QJRMS:1-18, doi:10.1002/qj.3418.
  • Bohlinger, P., Sorteberg, A., and Sodemann, H., 2017: Synoptic conditions and moisture sources actuating extreme precipitation in Nepal. Journal of Geophysical Research: Atmospheres, 122, 12,653–12,671. https://doi.org/10.1002/2017JD027543.
  • Blazina, T., A. Läderach, G. D. Jones, H. Sodemann, H. Wernli, J. W. Kirchner and L. H. E. Winkel, 2016: Marine primary productivity as a potential source of selenium and other trace elements in atmospheric deposition, Environ. Sci. Technol. 2017, 51, 108−118, doi: 10.1021/acs.est.6b03063.
  • Läderach, A. andSodemann, H., 2016: A revised picture of the atmospheric moisture residence time, Geophys. Res. Lett., 43, doi:10.1002/2015GL067449.
  • Baker, A., Sodemann, H., Baldini, J. U. L., Breitenbach, S. F. M., Johnson, K. R., van Hunen, J., and Pingzhong, Z., 2015: Seasonality of westerly moisture transport in the East Asian Summer Monsoon and its implications for interpreting precipitation d18O, J. Geophys. Res., 120, doi:10.1002/2014JD022919.
  • Steen-Larsen, H. C., Sveinbjörnsdottir, A. E., Jonsson, T., Ritter, F., Bonne, J.-L., Masson-Delmotte, V., Sodemann, H., Blunier, T., Dahl-Jensen, D., Vinther, B. M., 2015: Moisture sources and synoptic to seasonal variability of North Atlantic water vapor isotopic composition, J. Geophys. Res., 120, 5757–5774, doi:10.1002/ 2015JD023234.
  • Bonne, J.-L., Steen-Larsen, H. C., Risi, C., Werner, M., Sodemann, H., Lacour, J.-L., Fettweis, X., Cesana, G., Delmotte, M., Cattani, O., Vallelonga, P., Kjær, H. A., Clerbaux, C., Sveinbjörnsdóttir, A. E., and Masson-Delmotte, V., 2015: The summer 2012 Greenland heat wave: In situ and remote sensing observations of water vapor isotopic composition during an atmospheric river event, J. Geophys. Res., 120, 2970-2989, doi:10.1002/2014JD022602.
  • Luetscher, M., Boch, R., Sodemann, H., Spoetl, C., Cheng, H., Edwards, R. L., Frisia, S., Hof, F., Mueller, W., 2015: North Atlantic storm track changes during the Last Glacial Maximum recorded by Alpine speleothems, Nature Comm. 6: 6344, doi:10.1038/ncomms7344.
  • Winschall, A., Sodemann, H.,Pfahl, S. and Wernli, H., 2014: How important is intensified evaporation for Mediterranean precipitation extremes?, J. Geophys. Res., 119: 5240–5256, doi:10.1002/2013JD021175
  • Winschall, A., Pfahl, S., Sodemann, H.and Wernli, H.. 2014. Comparison of Eulerian and Lagrangian moisture source diagnostics - the flood event in eastern Europe in May 2010, Atmos. Chem. Phys. 14: 6605–6619, doi:10.5194/acp-14-6605-2014.
  • Aemisegger, F., Pfahl, S., Sodemann, H., Lehner, I., Seneviratne, S. I., and Wernli, H., 2014: Deuterium excess as a proxy for continental moisture recycling and plant transpiration, Atmos. Chem. Phys., 14: 4029–4054, doi:10.5194/acp-14-4029-2014.
  • Bonne, J. L., Masson-Delmotte, V., Cattani, O., Delmotte, M., Risi, C., Sodemann, H., and Steen-Larsen, H. C., 2014:The isotopic composition of water vapour and precipitation in Ivittuut, southern Greenland, Atmos. Chem. Phys. 14: 4419–4439, doi:10.5194/acp-14-4419-2014.
  • Wang, Y., Sodemann, H., Hou, S., Masson-Delmotte, V. Jouzel, J. and Pang, H., 2013: Snow accumulation and its moisture origin over Dome Argus, Antarctica. Clim. Dyn., 40:731-742, doi: 10.1007/s00382-012-1398-9.
  • Martius, O., Sodemann, H., Joos, H., Pfahl, S., Winschall, A., Croci-Maspoli, M., Graf, M., Madonna, E., Mueller, B., Schemm, S., Sedlacek, J., Sprenger, M. and Wernli, H., 2012: The role of upper-level dynamics and surface processes for the Pakistan flood in July 2010. Quart. J. Royal Meteorol. Soc., published online, doi: 10.1002/qj.2082.
  • Kennett, D. J., Breitenbach, S. F. M., Aquino, V. V., Asmerom, Y., Awe, J., Baldini, J. U. L., Bartlein, P., Culleton, B. J., Ebert, C., Jazwa, C., Macri, M. J., Marwan, N., Polyak, V., Prufer, K. M., Ridley, H. E., Sodemann, H., Winterhalder, B. and Haug, G. H., 2012: Development and Disintegration of Maya Political Systems in Response to Climate Change. Science, 338: 788-791, doi: 10.1126/science.1226299.
  • Winkler, R., Landais, A., Sodemann, H., Dümbgen, L., Priéa, F., Masson-Delmotte, V., Stenni, B., and Jouzel, J., 2012: Deglaciation records of 17O-excess in East Antarctica: reliable reconstruction of oceanic relative humidity from coastal sites. Clim. Past 8, 1-16.
  • Masson-Delmotte, V., Buiron, D., Ekaykin, A., Frezzotti, M., Gallée, H., Jouzel, J., Krinner, G., Landais, A., Motoyama, A., Oerter, H., Pol, K., Pollard, D., Ritz, C., Schlosser, E., Sime, L. C., Sodemann, H., Stenni, B., Uemura R., and Vimeux, F., 2011: A comparison of the present and last interglacial periods in six Antarctic ice cores Clim. Past, 7, 397-423.
  • Sodemann, H.and Zubler, E., 2010: Seasonality and inter-annual variability of the moisture sources for Alpine precipitation during 1995-2002, Int. J. Climatol., 30: 947-961, doi:10.1002/joc.1932.
  • Sodemann, H., and Stohl, A., 2009: Asymmetries in the moisture origin of Antarctic precipitation, Geophys. Res. Lett., 36, L22803, doi:10.1029/2009GL040242.
  • Sodemann, H., Masson-Delmotte, V., Schwierz, C., Vinther, B. M. and Wernli, H., 2008: Inter-annual variability of Greenland winter precipitation sources. Part II: Effects of North Atlantic Oscillation variability on stable isotopes in precipitation, J. Geophys. Res., 113, D12111, doi:10.1029/2007JD009416.
  • Sodemann, H., Schwierz, C., and Wernli, H., 2008: Inter-annual variability of Greenland winter precipitation sources. Lagrangian moisture diagnostic and North Atlantic Oscillation influence, J. Geophys. Res.,113, D03107, doi:10.1029/2007JD008503.