Linux, OS X: Windows:

CAIRS is a framework to reconstruct rain fields by assimilating signals of fundamentally different rain sensors.

In particular, the integration characteristics of sensors are explicitly considered. For example, non-recording standard rain gauges integrate over time and deliver information such as the daily rainfall sums. The rain-induced attenuation of micro wave links (MWL) can be used to measure the path-integrated intensities - an example of a sensor with spatial integration.

Sensor signals with different scales (e.g. continuous, binary) can be assimilated. Furthermore, CAIRS is formulated continuously in time and space. This is helpful because it enables a natural consideration of signals with irregular time-intervals.

The mathematical model is described in Scheidegger and Rieckermann (2014). The basic functionality and application is explained in this tutorial.

Note, CAIRS is still under development and the interface may change.

CAIRS is a Julia package. The first step is to download and install Julia version 0.6 or newer.

CAIRS can then be installed with the Julia command Pkg.clone():

Pkg.clone("git://github.com/scheidan/CAIRS.jl.git")

After that, CAIRS behaves like a normal package. For example, it can be updated with Pkg.update().

First, the package CAIRS must be loaded. For convinience, it is also recommended to load the packages Dates and Distributions:

using CAIRS
using Distributions
using Base.Dates

Every sensor must be characterized. In the simplest case a sensor measures the rain intensity at a point. In this case (the logarithm of) the signal distribution must be defined conditioned on the intesity at this coordinate:

function log_p_gauge(S::Float64, R::Vector) # non-linear continuous rain gauge

	mu = 0.1+R[1]^2.0    # Note, the signal and can be non-linearly
						 # related to the rain intensity.
	sigma = 0.005

	 ## log of normal density, p(S|R)
	logpdf(Normal(mu, sigma), S)   # doesn't have to be normal
end

sensor_gauge = Sensor(log_p_gauge)

For integrating sensors, also the integration domain must be specified. For example, a micro wave link (MWL) with length 6 may be defined as:

function log_p_MWL(S::Float64, I::Float64)

	R_mean = I/6.0
	sigma = 0.1

	## log of normal density, p(S|I)
	logpdf(Normal(R_mean, sigma), S)
end

sensor_MWL = Sensor(log_p_MWL, Coor(6, 0, 0)) # integrates along a path of length 6

The prior of the rain field is modeled as Gaussian process (GP). A GP is described by a mean and a covariance function.

This functions can be specified by the user. The mean function returns the prior mean of the rain intensity at a given coordinate. It must take a single argument of type Coor. The covariance function must return the covariance of the rain intensities at two given point, given by two arguments of type Coor. Note, it is not checked if the provided function is a valid covariance function!

However, helpers to construct valid functions are provided. The functions mean_constant() and cov_exponential() create a simple constant mean, and a separable gamma-exponential covariance function. Only the parameters must be provided:

mean_GP = mean_constant(mean=2.0)

cov_GP = cov_exponential(sigma=10.0,           # standard deviation of GP
						 l_spatial=1.5,        # spatial correlation length
						 l_temporal=Minute(1), # temporal correlation length
						 gamma=1.0)            # exponent for smoothness in [0, 2]

Other types of covariance functions will be added in future.

The next step is to import the signals. Every signal must have an attached sensor. Signals can be constructed with the function Signal or more conveniently with add_signal().

Currently add_signal() expected that the signals of every sensor are stored in a separate file. The file must contain two columns:

• Column 1: date and time
• Column 2: signal values

## path to example data that come with the CAIRS package
path1 = joinpath(Pkg.dir("CAIRS"), "example", "data", "Sensor1.csv")
path2 = joinpath(Pkg.dir("CAIRS"), "example", "data", "Sensor2.csv")

sig = Signal[]                          # create an empty array for Signals

add_signal!(sig,                        # add signal to vector 'sig'
			path1,                      # file name
			sensor_gauge,               # sensor
			Coor(5, 6),                 # coordinate of the sensor
			date_format="d.m.yyyy HH:MM:SS",
			delim=',')                  # delimitation character


add_signal!(sig, path2,
			sensor_MWL,                 # MWL link
			Coor(4.2, 2),               # coordinate of one end point of the sensor
			0.9,                        # rotation around the point defined above in [rad]
			date_format="d.m.yyyy HH:MM:SS",
			delim=',')

Information about a signal can be printed with show, e.g. show(sig[1]).

Writing the sensor positions in a file is useful for plotting:

sensor2csv(sig, "sensor_coor.csv")

The location for which a prediction of the rain intesity is desired must be defined as an Array or Vector of coordinates. Coordinates are defined with Coor(x, y, time). Time can be a number or a DateTime object.

### create a simple grid
nn = 20
loc_pred = [Coor(i, j, time)
			for i=linspace(0, 10, nn), j=linspace(0, 10, nn),
			time=DateTime(2013, 11, 22, 13, 15, 00) : Minute(1): DateTime(2013, 11, 22, 13, 20, 00) ]

This produced a regular grid, but the point could also be irregularly distributed. Also, not only predictions for coordinates but also for intesities integrated over a domain can be made. Domains are defined by the function Domain.

The assimilation of the signals and the computation of the predictions are done with predict.

R_pred = predict(loc_pred,               # vector or array with locations for predictions
				 sig,                    # vector of signals
				 mean_GP,                # mean function of prior
				 cov_GP,                 # covariance function of prior
				 n_sample_calib = 20000, # number of iterations of the Gibbs sampler
				 burn_in = 5000,         # number of removed samples (and length of adaptation)
				 n_sample_pred = 6000,   # number of samples for predictions
				 delta = Second(90))     # consider all signals within time 'delta'
										 # from prediction points

Write a summary of the samples in a file that is used for visualization:

summary2csv(R_pred, "rain_field.csv")

One possibility to visualize the result is to use R. A simple R-script to produce rain maps comes with CAIRE. It requires that R and the R-libraries lattice, latticeExtra and tripack are installed.

pathRscript = joinpath(Pkg.dir("CAIRS"), "R", "compute_rain_map.r")
run(`Rscript $pathRscript  rain_field.csv sensor_coor.csv out.pdf`)

Note, here it is assumed that Rscript is in PATH.

Scheidegger, A. and Rieckermann, J. (2014) "Bayesian assimilation of rainfall sensors with fundamentally different integration characteristics" in WRaH Proceedings, Washington, DC.