%% Template: OSGeo Journal - Article
%% Language: Latex
%% Template OSGeo Journal - Nove 2010
%% Head
%% This template shows some of the minimal basics for describing your article.  
%% To build a PDF demo of the template run:
%% pdflatex osgeo_template.tex
%% Many of these are options, only a few core concepts are often used.  
%% More advanced usage is a possibility too in coordination with the Journal Development Team.  
%% Join our mailing list to ask questions: http://lists.osgeo.org/mailman/listinfo/newsletter
%% Percent signs represent comments but most of the comments are written in examples so you can
%% compile this document and see what it looks like yourself.
%% Please leave the double comment "%%" lines in place as they are used for automation.
%
%% Next line is for testing your document only.  This will be removed by editors when your article is added as a child in their MASTER DOCUMENT.
%
%% This sets the type of document we will create
%% Use option twocolumn [,twocolumn] for a two column 
%\documentclass[12pt,a4paper]{article} %% HEADCLASS 
%
%% Let's keep the use of packages as simple as possible in the template.
%\usepackage{hyperref} %% HEADPACK
%\usepackage{graphicx} %% HEADPACK
%\usepackage[printonlyused]{acronym} % 1st time Common Data Model (CDM), 2nd time CDM (both with links)
%\usepackage{natbib} % For \citep (Donchyts, 2010) \citet Donchyts (2010) \citeauthor Donchyts
%\usepackage{tabularx} % For automated column widths (X type)
%
%\graphicspath{{./figures/}}
%
%% This begins the text of your document
%\begin{document} %% DOCSTART
%\setcounter{secnumdepth}{1}
\begin{article}
\title{Functional Coverages}
\author{Gennadii Donchyts, Fedor Baart, H.R.A (Bert) Jagers, Arthur van Dam}

% Keep this next line to generate the title page.  Don't worry, it will fit into our master document well, even if it creates a separate title page at the moment.  A date will automatically be shown as well, don't worry about it.

\maketitle
 

%\refstepcounter{section}
%\setcounter{section}{0}
\section{Abstract}
A new \ac{API} is presented which simplifies working with geospatial coverages as well as many other data structures of a multi-dimensional nature. The main idea extends the \ac{CDM} developed at the \ac{UCAR}. The proposed function object model uses the mathematical definition of a vector-valued function. A geospatial coverage  will be expressed as a vector-valued function whose dependent variables (the vector components) are fully defined by its independent variables (the coordinates).

Our goal is to provide an \ac{API} using a terminology and an object model that is both appealing to computer scientists and numerical modelers and is flexible enough to enable defining data structures for a wide range of applications. Examples of such data structures can be: wind velocity as a continuous variable defined along the channels in a river network. Precipitation data defined as a time-dependent variable on a set of sub-catchments of a drainage basin, preserving association with sub-catchment features.

The new object model provides a basis for both continuous and discrete coverages including non-geospatial data structures such as time series. Different storage models for variables are implemented, based on the \ac{NetCDF}, the \ac{GDAL} and memory.

The \ac{API} is available as set of open source libraries developed in C\# consisting of a multi-dimensional arrays library; a scientific data structures library defining variables, functions, units of measure; a geospatial extensions library built on top of GeoAPI.NET and NetTopologySuite, defining specialized coverages: network coverage, feature coverage, regular grid coverage, and unstructured grid coverage.


\acresetall  % so the acronyms will be expanded again

\section{1 Introduction}
Geospatial coverage is the concept describing geographic phenomena upon which a range of data values can be present. The concept dates back to early ArcInfo\footnote{\url{http://www.esri.com/software/arcgis/arcinfo}} versions, but has been applied and rethought numerous times in data standards and \ac{API}s ever since.  The assumptions that were made in these do not alway make them easily applicable in new fields, where both the data and the spatial domains may be more complicated. One special example is the role of the time dimension, which was absent in early coverage definitions. Over the past decades, many initiatives were taken to incorporate time into geospatial applications (\citep{Peuquet1999time}, \citep{Wachowicz1999}, \citep{Goodall2004}) resulting in a sometimes overly special role of the time dimension.

The goal of the present work is to define a high-level \ac{API} that will allow presenting most of the existing geospatial and temporal coverage data types in terms of vector-valued functions of one or more independent variable(s), inspired by basic vector calculus. The main reason for doing this is a unification of the storage of spatiotemporal domains and coverage values on top of these domains. In addition this will simplify development of generic data transformation algorithms such as aggregations, filtering, interpolation, and extrapolation. It will be much easier to re-use them, which will simplify development of applications, as was already shown for example for the \ac{OpenMI} 2.0 by \citet{Donchyts2010openmi}. We will show that this higher-level \ac{API} can not only define scalar data on spatial networks or grids, but can also be used to define more general data structures, such as time-series or vector fields. Evidently, these can be used in geospatial applications, but are also applicable in a wider scope.

\subsection*{Related work}
The definition and use of a geospatial coverage can be approached from several angles; two existing standards are the ISO 19123 standard (schema for coverage geometry and functions) and the \ac{CDM}, designed by the \ac{UCAR}.

The ISO 19123 standard defines a coverage as a "coverage is a feature that associates positions within a bounded space (its domain) to feature attribute values (its range)". ISO 19123  as well as the \ac{OGC} Abstract Specifications (2007) define an abstract concept of the coverage object model and how it supports mapping from a spatial, temporal or spatio-temporal domain to feature attribute values. These standards are mainly used to form the basis of an geospatial \ac{API}'s such as GeoAPI.\footnote{\url{http://www.geoapi.org/}}

Alternatively, the \ac{CDM} \ac{API} mainly focuses on the multidimensional aspects of coverages. An overview of the \ac{UCAR} \ac{CDM} and its mapping into the corresponding elements of the international standard coverage data model of ISO 19123 is presented by \citet{Nativi2008}. More information about \ac{CDM} and the \ac{NetCDF} can be found in \citet{Rew1990}. 

As a result of these two different angles, the coverage \ac{API} is very well suited in geospatial applications, whereas the \ac{CDM} \ac{API} has proven itself in numerical applications and for large datasets, see, e.g., \citet{Rutledge2006} and \citet{Signell2008}, respectively. For applications where data structures are less organized (ecological models) or require more complex relations (river models), both data models are less applicable. This paper deals with datasets where information is dependent on time and covers a network- or grid-based area (the spatial domain). Examples are: ocean dynamics (water levels and velocities in 3D grid layers) and river flows (water levels, velocities and transport across network connections), see, e.g., \citet{Kernkamp2011}. The new \ac{API} should facilitate this.

An example of an often-used \ac{API} for \emph{time-dependent} data sets defined on complex geometries can be found in the open source \ac{VTK} \citep{Schroeder2000}. Each object in VTK maintains an internal time stamp that is automatically updated when the object state changes (usually as a result of setting an instance variable value). An alternative approach to dealing with the time dependent grid based data is presented by \citet{Howe2005}. They use a relational database based approach using an algebra notation to manipulate both regular and irregular gridded datasets. When comparing these \ac{API}'s and data models we can see that they differ in scope, detail and field. When approached from the visualization field as was done in \ac{VTK}, the time dependency and geographic aspects were added later (see for example vtkGeoGlobeSource, vtkTemporalDataSet).  Because the \ac{API} is focused on visualizations we can see that all geometry objects are well defined and easy to comprehend.

When approached from the \ac{GIS} field we can see that the Feature is the base of all relevant objects, however it is still ongoing discussion about what it is and how it should be implemented and used in applications.  \ac{OGC} Coverage Primer \citep{Nordgren2006} reflects this in the following way: \textit{The question "What is a feature?" leads directly to a philosophical rabbit hole which deposits the unwary questioner in a wonderland from which it is difficult to return}. Also, time aspects are still being introduced in the \ac{OGC} standards and as a result most widely used geospatial \ac{API}'s that build upon these \ac{OGC} Standards still lack support for time dependency.

It is important to note that computer scientists will often define their own \ac{API} and naming conventions that are (partly) based on the problem domain in which they happen to be working at the time rather than using the terminology of the generic underlying concepts. This complicates the reuse by people in other domains.
The idea to use multi-valued functions to represent data structures in a more generic way has been formulated by \citet{Treinish1999} as: "Any data set may be considered as a single or multi-valued function of one or more independent variable(s)". In the present work we try to generalize and expand this idea to be applicable to geospatial coverages, resulting in both a conceptual description and an implementation in the form of a class library which can be easily re-used in geospatial applications.
\subsection*{Outline}
Section~\hyperref[sec:method]{2} motivates the approach we took in defining our API and summarized the underlying ideas. Sections~\hyperref[sec:vectorfunction]{3} and \hyperref[sec:coverage_examples]{4} then respectively describe the generic vector-Function \ac{API} and the geospatial API on top of it. Section~\hyperref[sec:persistence]{5} describes how the functions and their values can be stored in memory and in files. Section~\hyperref[sec:discussion]{6} considers our resulting API and provides some additional motivation. Section~\hyperref[sec:conclusion]{7} summarizes the paper in several conclusions.
The appendices summarize the terminology and acronyms used throughout the paper.

\section{2 Method} % Sections automatically end when a new one is started.
\label{sec:method}
The most important question is how to define an \ac{API} that offers data types and functionality for generic mathematical concepts such as variables, and at the same time be specifically suitable as well for both geospatial and non-geospatial applications? Can we introduce time-dependency in a non-intrusive way? The idea is to define a common \ac{API} which will describe all generic mathematical data structures required to manage variable values and and then base a geospatial coverage \ac{API} on top of that to provide a better separation of concepts and better code re-use.

The spatial domains also pose challenges: what to do when the topology is complicated, for example a river network? The channels in this network form a set of interconnected features, each of which is a polyline or polygon geometry as shown in Figure~\ref{fig:river}. Can we still use the same classes to model this situation in a similar way as we would do it for a simple time series at a single point station?

Next comes the data defined on the domains. In our river example, consider a time-dependent wind velocity field defined as a continuous vector variable $\vec{V}=(v_x, v_y)$ (discrete values with interpolation) along the channels in the river network. Inter- and extrapolation on such complicated geometries is also nontrivial. Do we need to deal with spatial variables differently than with time variables?

\begin{figure*}
   \centering
   \includegraphics[scale=1.0]{osgeo-functional-coverages/figures/river-example}
   \caption{Problems appearing while modeling variables defined on the network}
   \label{fig:river}
\end{figure*}


Even if it would be clear what should be done in this example, it is still not a trivial task to define using an object-oriented language. Both the \ac{OGC} Coverage model and \ac{CDM} fail to define it completely. The \ac{OGC} Coverage model is not flexible enough in the sense that it introduces many classes but there is no conceptual basis where every type of Coverage would fit. In terms of the \ac{CDM}, it should be trivial to define values of all variables used here  (river coordinates and wind) using multi-dimensional arrays. However, there is no room for the rest of the meta-information (the river topology and offsets of network locations). The use of basic \ac{CDM} attributes is insufficient here.

We will show that using the new approach proposed in this paper all coverage types can be defined in terms of vector-valued functions.

\subsection*{Design steps}
Before introducing an \ac{API} for multi-dimensional data structures, we will first try to identify and analyze the actual problem domains related to the practical applications that involve coverages or multi-dimensional data structures (Figure~\ref{fig:domains}). Then we will try to identify the functionality required by the developers when developing applications related to these domains.

For the design of the \ac{API} we used the following steps: identification of entities / classes, construction of a reference implementation of the classes to match the different fields (geospatial, environmental), separation of core logic of the classes from persistency so that multiple storage choices can be used, identification of interfaces / classes which should belong to the \ac{API}.

The term Coverage is used in the geospatial domain (by the \ac{OGC}) to describe discrete or continuous characteristics of the real world features. We will try to match our \ac{API} as much as possible (on a conceptual level) to the requirements listed in the \ac{OGC} standards.

Before moving to the geospatial domain we will first try to analyze in details how vector-valued function can be defined in terms of the software component since we plan to use it as a basis of our \ac{API}. After that we will show that the new \ac{API} is very well suitable to describe any coverage used in the geospatial domain.

\begin{figure*}
   \centering
   \includegraphics[width=0.5\linewidth]{osgeo-functional-coverages/figures/problem-domains}
   \caption{Problem domains involved}
   \label{fig:domains}
\end{figure*}

When developing an \ac{API} for multi-dimensional structure an important aspect is persistency. In section \hyperref[sec:persistence]{5} \hyperref[sec:persistence]{Persistence} several storage options will be discussed allowing reuse of existing data access libraries or file formats to persist structure and values of the vector-valued functions.

We will use motivating example problems appearing in the environmental modeling field, see sections \hyperref[sec:api]{3.2} and \hyperref[sec:coverage_examples]{4}.

\section{3 Vector-valued Function}
\label{sec:vectorfunction}

\subsection{3.1 Mathematical Definition}

The main idea of the new data structure is based on the following statement:

Any data structure of a multi-dimensional nature can be presented as a single or multiple number of a vector-valued functions.

In vector calculus a vector-valued function is defined in general form as Equation \ref{eq:vectorfunction} 

\begin{equation}
\label{eq:vectorfunction}
F=(f_1,f_2,\cdots,f_{n})(x_{1},x_2,\cdots,x_m)
\end{equation}

where $x_1, x_2, \cdots, x_m$ are independent variables and $f_1, f_2, \cdots, f_n$ are dependent variables.

Typical examples of independent variables are time, spatial coordinates, categories, etc. Dependent variables usually represent actual quantities. In scientific applications these variables are very frequently sampled or discretized and thus their values are defined in a form of arrays together with information about how to interpolate values of dependent variables where no exact values of the independent variables are available. For arguments (independent variables) these arrays are in most cases one-dimensional ($R1$) while for components (dependent variables) dimensionality of arrays is defined by a number of arguments used ($Rm$). In many cases value type used by the variable is a real number ($R$) however in general it can be any type available in programming language, for example: string, class, feature, etc. In some cases the rank of the independent variable space may be different from the rank of the sampled independent variable space: discrete coordinate arrays may be rank 1 (regular grid), or rank 2 (curvilinear/irregular grid), or even rank 3 (time dependent moving grid).

Let us analyze vector-valued function in more details: consider that we want to define a time-dependent velocity field (e.g. 3 moments in time), defined on a discrete, regular grid (see Figure~\ref{fig:datastructure}). In order to store values of this function we will have first to decompose it into independent ($x$, $y$ and $t$) and dependent ($vx$ and $vy$) variables. We can see that independent variables have to be defined as a set of values (ordered set if we want to interpolate values of the dependent variables along the argument). On the other hand dependent variables require 3-dimensional arrays to store their values (number of independent variables used in function). 

It is simple to show that every variable can be also considered as a function, as result we can list all objects required to store the above example, as can be seen in Table \ref{tab:datastructure-table}.

In the table Arguments denote independent variables and components - dependent variables.

In general any variable used in a function (independent or dependent variable) can be described by a set of properties: value type, units of measure, typical minimum and maximum values.

Additionally, for every independent variable we need to define interpolation and extrapolation method since its values are defined only at discrete locations. This will allow computing values of dependent variables outside of independent variable values space.

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.7\linewidth]{osgeo-functional-coverages/figures/function-data-structures.png}
   \caption{Analysis of the data structures required to store discrete vector-valued function}
   \label{fig:datastructure}
\end{figure*}

\begin{table*}
   \caption{List of functions and their properties used in example}
   \centering
  \begin{tabular}{c}
   \includegraphics[width=0.6\linewidth]{osgeo-functional-coverages/figures/function-example-table.png}\\
  \end{tabular}
   \label{tab:datastructure-table}
\end{table*}

From the table we can see that in order to completely define all objects used in this example we will have to define all functions listed in the table, together with their properties as well as relations between them such as that some of them are used as independent variables and other as dependent variables. In case if we have a function that uses more than one component ($V$) - the only thing to be stored is its relation to child component variables since its values are completely defined by the values of its components ($v_x, v_y$)

\subsection{3.2 \ac{API}}
\label{sec:api}
Based on the points discussed in the previous section we believe that the class diagram presented in Figure~\ref{fig:api} most closely describes all objects required to introduce a vector-valued function. 

\begin{figure*}
   \centering
   \includegraphics[width=1\linewidth]{osgeo-functional-coverages/figures/api.eps}
   \caption{Vector-value function class diagram}
   \label{fig:api}
\end{figure*}

As can be seen from Equation \ref{eq:vectorfunction}, component variables can be actually seen as vector-valued functions by themselves.

The code listing in Figure~\ref{fig:listing1} shows how the \ac{API} can be used. This is a simple example that shows how we can define a variable, its properties and an array of values.

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.8\linewidth]{osgeo-functional-coverages/figures/listing1.png}
   \caption{Create and set values of a simple scalar variable (C\#)}
   \label{fig:listing1}
\end{figure*}

Since a Variable in our \ac{API} is automatically considered to be a Function - we can also start combining variables as shown in Figure~\ref{fig:listing2}.

\begin{figure*}[ht]
   \centering
   \includegraphics[width=1\linewidth]{osgeo-functional-coverages/figures/listing2.png}
   \caption{Create a 1d function y=y(x), use linear interpolation for x (C\#)}
   \label{fig:listing2}
\end{figure*}

This type of function is one of the most frequently used. A simple example from hydrodynamic modeling can be a water level defined as a function of time, e.g. measured at some location: y=y(t). In this case value type of the argument variable will be DateTime (C\#) instead of double. In this case a water level is dependent variable and time is independent variable.

If we make it a bit more complex we can measure water level on a moving boat. In this case a water level variable is measured as a function of time, but so is location. So we have location as an object and a water level as a scalar value defined as a function of time: \textit{F=(location, depth)(t)}.

Suppose we measure wind direction at a meteorological station, then we have two parameters for direction and speed or in Cartesian space a u and v part of the vector. Both again are defined as functions of time.

The source code required to work with a vector-function that uses more than one independent variable (components) does not look much different, see Figure~\ref{fig:listing3}. 

\begin{figure*}[ht]
   \centering
   \includegraphics[width=1\linewidth]{osgeo-functional-coverages/figures/listing3.png}
   \caption{Define 2d velocity field function (C\#)}
   \label{fig:listing3}
\end{figure*}

Note that \ac{API} provides different ways to access or assign values of the variables. Depending on performance requirements values of the variable can be set as an array at once or one by one using simple and intuitive syntax.

\section{4 Adding geospatial aspects to Function}
\label{sec:coverage_examples}

Even though the above \ac{API} is powerful enough to describe a vector-valued function, in some cases we need to extend it in order to apply it to other domains. We will try to define a Coverage types on top of the Function \ac{API}. 

\subsection{4.1 What is Coverage?}

Definition of Coverage in many geospatial applications is also confusing and is given on a very conceptual level. We will introduce term Coverage as a bridge between two worlds: Geospatial and Mathematical. The UML class diagram is shown in Figure \ref{fig:coverage-uml}. 
The nice thing is that if Coverage can be defined as a function - then its values can be accessed in the same way as in examples of the previous section. On the other side Coverage is a geospatial object, which means it has to extend functional part with geometries. For example Geometry property of the coverage can be either a geometry that defines bounds of the coverage, or a complex geometry representing every location where values of the coverage are defined (GeometryCollection).

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.8\linewidth]{osgeo-functional-coverages/figures/coverage-uml.png}
   \caption{Coverage Class Diagram}
   \label{fig:coverage-uml}
\end{figure*}

In the OGC standards there is a clear distinction made between continuous and discrete coverages. We do not see the need to separate them. Really, the difference between if coverage is discrete or continuous is just an interpolation type used for its arguments. In fact we can define a Coverage that is discrete along one argument and continuous (interpolated) along the other one.

All other coverage types can be very simply defined as an extension of the ICoverage interface. For the sake of space we will not list all UML diagrams here.

\subsection{4.2 Regular Grid Coverage}

In many applications, including numerical modeling, data of the models are often defined on a discrete grid. Suppose we compute water level which can change in time and is defined on a rectangular regular grid, then it can be defined as a function of x, y coordinates and time t. In these case x and y identify location and used as independent variables as showin in Figure~\ref{fig:listing4-regular}. Actually this is also true for rectilinear grid, where values of x and/or y are not equidistant, see \citep{Balaji2007}. In case of regular grid the values of x and y variables (arguments) are equidistant and as a result their storage can be simplified.

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.8\linewidth]{osgeo-functional-coverages/figures/listing4-regular.png}
   \caption{RegularGridCoverage defined as 2D function (Python)}
   \label{fig:listing4-regular}
\end{figure*}

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.8\linewidth]{osgeo-functional-coverages/figures/listing5-regular-time.png}
   \caption{Define and query value of a time-dependent RegularGridCoverage (Python)}
   \label{fig:listing5-regular-time}
\end{figure*}

Depending on a type of grid we can also use cells of the grid (objects) as an independent variable values instead of scalar x and y variables to identify location on a grid. See \hyperref[sec:unstructured]{4.5} section for an example.

The biggest advantage of using the same base \ac{API} to work with Coverages is that the functionality of Coverage can be very easily extended. For example in order to make regular grid coverage time dependent we only need to add an additional argument (independent variable) of a time value type, see Figure~\ref{fig:listing5-regular-time}. The rest remains the same. 

Of course in case if we have other functionality (for example rendering) based on a specific Coverage type - we will need to extend it a little to make sure that we accessing only with a values corresponding to a single time value.

\subsection{4.3 Feature Coverage}

\begin{figure*}[ht]
   \centering
   \includegraphics[width=1\linewidth]{osgeo-functional-coverages/figures/listing6-uml-features.png}
   \caption{FeatureCoverage, function where one of the arguments uses features as values}
   \label{fig:listing6-uml-features}
\end{figure*}

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.7\linewidth]{osgeo-functional-coverages/figures/listing6-features.png}
   \caption{Creation and use of FeatureCoverage using existing features (C\#)}
   \label{fig:listing6-features}
\end{figure*}


We will call FeatureCoverage a function where one of arguments uses a Feature as a value type. 

Consider the following class as an example: a City, which has some default properties such as Name and Population (these properties are also available as feature attributes and accessible via Attributes dictionary).  

Now imagine that we want to compute a total precipitation over city for a given period of time without modifying existing City features. It can’t be simply added as an attribute (a property) since it doesn’t seem to be a default characteristic of the City. In this case FeatureCoverage type can be used to define a coverage function that uses cities as values of an independent variable as show in Figure~\ref{fig:listing6-uml-features} and Figure~\ref{fig:listing6-features}. 


\subsection{4.4 Network Coverage}

In some cases variable values are defined on a set of curves (see OGC CurveCoverage). In more specific cases these curves are connected into a network or graph, for example: river networks, roads and pipelines. It is frequently necessary to define a Coverage that can be seen as a continuous function defined along the branches (the polylines) of such a network (see Figure~\ref{fig:listing7-example-network}).

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.7\linewidth]{osgeo-functional-coverages/figures/listing7-example-network.png}
   \caption{Network coverage, values defined along the network branches.}
   \label{fig:listing7-example-network}
\end{figure*}

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.5\linewidth]{osgeo-functional-coverages/figures/listing7-network.png}
   \caption{Create network and network coverage (Python)}
   \label{fig:listing7-network}
\end{figure*}


This example is a bit more complicated compared to the ones discussed in the previous sections. The main problem is that we do not have an explicit independent variable to depend on in our function. Still we can introduce a variable which is defined as a combination of a curve and offset along that curve. In this case it will uniquely define location on a network. 

The only remaining problem is that if we would like to evaluate values of the dependent variables in other but existing locations on a network - we will need some custom interpolation algorithm at the sections where branches connect with each other. Once it is implemented - the rest of the functionality works as in any other function type.

Additionally to the network location independent variable we can also add time or any other variable.

We’ve defined NetworkCoverage as a separate coverage type as shown in Figure~\ref{fig:listing7-network}. However it will be more correct to introduce a CurveCoverage type first, and then define NetworkCoverage as an extension to it, in case if we need to use some network-specific interpolations e.g. at the nodes connecting different branches of the network. In this case it will be more consistent with the ideas introduced in the OGC Coverage standards.

\subsection{4.5 Unstructured Grid Coverage}
\label{sec:unstructured}

We did not fully implement support for unstructured grid coverages yet using new \ac{API}, but it should not be any more complicated than previously shown examples. In fact UnstructuredGridCoverage can be implemented in a way similar to FeatureCoverage, which depends on grid cells or interfaces between cells, depending on where values are defined (see Figure~\ref{fig:unstructured}). Additionally, custom interpolation methods have to be implemented for e.g. IDW, Krigging or any other interpolation methods required to evaluate values outside of the argument values domain.

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.6\linewidth]{osgeo-functional-coverages/figures/unstructured.png}
   \caption{Values defined on unstructured grid cells (faces) or interfaces between cells (edges)}
   \label{fig:unstructured}
\end{figure*}

\section{5 Persistence}
\label{sec:persistence}

In order to store values of the functions an interface IFunctionStore was introduced as a part of \ac{API}, see Figure~\ref{fig:store-uml}. An implementation of the IFunction / IVariable uses IFunctionStore to access all functions available in the store as well as to access their values. 

\begin{figure*}[ht]
   \centering
   \includegraphics[width=0.6\linewidth]{osgeo-functional-coverages/figures/store-uml.png}
   \caption{IFunctionStore - repository of functions and their values}
   \label{fig:store-uml}
\end{figure*}

Currently the following implementations are supported: MemoryFunctionStore, NetCDFFunctionStore and GdalFunctionStore. The first implementation is a default one and simply keeps a set of multi-dimensional arrays as well as a set of function objects in memory. The second is used to store functions in the \ac{NetCDF} files, wrapping UCAR Java implementation converted to .NET on a byte-code level using IKVM.NET. The third implementation is used to access raster data stored in GDAL file formats.

\subsection{5.1 Store Functions in \ac{NetCDF}}

Because the Common Data Model is a concept behind the \ac{NetCDF} file format, the file format is almost a perfect match for as a storage for Function classes. Still the following information needs to be defined implicitly using attributes: 

Relations between container vector-valued function and its component variables. 

Relations between components and arguments. Even it can be reconstructed using \ac{NetCDF} dimensions; it is still error prone and not very intuitive. 

Custom type mappings, in case if we want store entities (objects) in the \ac{NetCDF} variables. 

In the last case \ac{NetCDF} attributes can be used using some convention in order to define where properties need to be stored and to which type they belong to.

\section{6 Discussion}
\label{sec:discussion}
The need to this \ac{API} was mainly dictated by the reality that there was no \ac{API} library available written in C\# which is comparable to \ac{NetCDF}. Instead of reinventing the wheel we tried to extend concepts used in the CDM. On the other hand we did not port (or wrap) existing \ac{NetCDF} \ac{API} in C\# but tried to make it more intuitive by reviewing the concepts behind it. The \ac{NetCDF} library is a very powerful one but we believe that the \ac{API} introduced here better represents the reality (or mathematical abstractions used to describe the reality within computerized applications). The major difference between CDM and the present \ac{API}, except of course the language and syntax, is that CDM uses Dimensions as a separate entity next to Variable. For the \ac{API} we present the Dimension is not required as a separate entitity. The dimensions can be derived from the vector-valued functions.

Some variables need to be defined not as a set of values but e.g. as an equidistant series with start, stop and step. In this case only several properties need to be stored instead of array. The implementation can still generate all possible values on-the-fly in order to use this specific variable type in the same way as other variables.

In some cases a single vector-valued function is not sufficient to define all data structures. For example for curvilinear grid we want to preserve the information that the grid cells are defined as a 2D matrix. In this case it will be necessary to combine different vector-valued functions in order to fully define the data structure.

When comparing the proposed \ac{API} to the OGC/ISO Coverage specifications it is important to note that the latter specifications are quite complex compared to the \ac{API} presented here. Another point that is missing in OGC Coverages \ac{API} is that it does not provide a unified way to access all Coverage values in the same way for all Coverage types. We hope that this work will influence the existing OGC Coverage \ac{API} in a way that it will become simpler to use.

An important aspect that was not discussed in the present paper is related to the definitions of functions which represent filtered version of existing ones. This is a very useful functionality, especially if existing functions need to be queried and e.g. visualized as a function with a smaller number of arguments (time series representing values of a single cell of a time-dependent regular grid). In many cases this filtered functions need to be stored somewhere next to the real functions. Another example is when variable represents an aggregated version of another variable. It becomes a very tricky task when we add a user requirement that the connection between original and filtered variables must be live, meaning that when values in the original variable change - values in the filtered variable will be recalculated automatically.

\section{7 Conclusion}
\label{sec:conclusion}
We have presented an \ac{API} that provides users the possibility to work with geospatial and non-geospatial types of multidimensional data in a convenient way. By providing a direct connection to the \ac{NetCDF} data format we hope that our \ac{API} will become especially popular for working with results from numerical models. The library implementation also fills in the gap of a .NET based \ac{NetCDF} \ac{API} that makes use of the features of the .NET platform.

The design of an \ac{API} often feels a bit like tightrope walking. There need to be a balance between high level of usability and performance on one side, as well as a balance between completeness versus simplicity.

By following the general guidelines of a domain driven design the \ac{API} does adhere to good practices. Whether it is actually a usable one depends on the experience of users. Therefore we invite readers to try out the \ac{API} and provide us with feedback and critical comments.

The \ac{API} as well as its implementation will be released as an open-source project. Currently a draft version is already available as a branch of a SharpMap project.\footnote{\url{http://bit.ly/functional-coverages}} 


%\newpage % force new page so all figures show before the bib starts

% References
%\bibliographystyle{plainnat}

\begin{thebibliography}{14}
\providecommand{\natexlab}[1]{#1}
\providecommand{\url}[1]{\texttt{#1}}
\expandafter\ifx\csname urlstyle\endcsname\relax
  \providecommand{\doi}[1]{doi: #1}\else
  \providecommand{\doi}{doi: \begingroup \urlstyle{rm}\Url}\fi

\bibitem[Balaji and Liang(2006)]{Balaji2007}
V.~Balaji and Z.~Liang.
\newblock Gridspec: A standard for the description of grids used in earth
  system models.
\newblock In \emph{Workshop on Community Standards for Unstructured Grids},
  October 2006.

\bibitem[Donchyts et~al.(2010)Donchyts, Hummel, Vane{\c{c}}ek, Groos, Harper,
  Knapen, Gregersen, Schade, Antonello, and Gijsbers]{Donchyts2010openmi}
G.~Donchyts, S.~Hummel, S.~Vane{\c{c}}ek, J.~Groos, A.~Harper, R.~Knapen,
  J.~Gregersen, P.~Schade, A.~Antonello, and P.~Gijsbers.
\newblock Openmi 2.0 what's new?
\newblock In \emph{International Congress on Environmental Modelling and
  Software, July}, pages 5--8, 2010.

\bibitem[Goodall et~al.(2004)Goodall, Maidment, and Sorenson]{Goodall2004}
JL~Goodall, DR~Maidment, and J.~Sorenson.
\newblock Representation of spatial and temporal data in arcgis.
\newblock \emph{GIS and Water Resources III. AWRA, Nashville, TN}, 2004.

\bibitem[Howe and Maier(2005)]{Howe2005}
B.~Howe and D.~Maier.
\newblock Algebraic manipulation of scientific datasets.
\newblock \emph{The VLDB journal}, 14\penalty0 (4):\penalty0 397--416, 2005.

\bibitem[Kernkamp et~al.(2011)Kernkamp, van Dam, Stelling, and
  de~Goede]{Kernkamp2011}
H.W.J. Kernkamp, A.~van Dam, G.S. Stelling, and E.D. de~Goede.
\newblock Efficient scheme for the shallow water equations on unstructured
  grids with application to the continental shelf.
\newblock \emph{Ocean Dynamics}, 61\penalty0 (8):\penalty0 1175--1188, 2011.
\newblock \doi{doi:10.1007/s10236-011-0423-6}.

\bibitem[Nativi et~al.(2008)Nativi, Caron, Domenico, and Bigagli]{Nativi2008}
S.~Nativi, J.~Caron, B.~Domenico, and L.~Bigagli.
\newblock Unidata's common data model mapping to the iso 19123 data model.
\newblock \emph{Earth Science Informatics}, 1\penalty0 (2):\penalty0 59--78,
  September 2008.
\newblock \doi{10.1007/s12145-008-0011-6}.

\bibitem[Nordgren(2006)]{Nordgren2006}
B.~Nordgren.
\newblock An iso19123 coverage primer.
\newblock Integration guide, USDA Forest Service, 2006.

\bibitem[Peuquet(1999)]{Peuquet1999time}
D.J. Peuquet.
\newblock Time in gis and geographical databases.
\newblock \emph{Geographical information systems}, 1:\penalty0 91--103, 1999.

\bibitem[Rew and Davis(1990)]{Rew1990}
R.~Rew and G.~Davis.
\newblock Netcdf: an interface for scientific data access.
\newblock \emph{Computer Graphics and Applications, IEEE}, 10\penalty0
  (4):\penalty0 76--82, 1990.

\bibitem[Rutledge et~al.(2006)Rutledge, Alpert, and Ebisuzaki]{Rutledge2006}
G.K. Rutledge, J.~Alpert, and W.~Ebisuzaki.
\newblock A climate and weather model archive at the national oceanic and
  atmospheric administration.
\newblock \emph{Bulletin of the American Meteorological Society}, 87:\penalty0
  327--341, 2006.
\newblock \doi{10.1175/BAMS-87-3-327}.

\bibitem[Schroeder et~al.(2000)Schroeder, Avila, and Hoffman]{Schroeder2000}
W.J. Schroeder, L.S. Avila, and W.~Hoffman.
\newblock Visualizing with vtk: a tutorial.
\newblock \emph{Computer Graphics and Applications, IEEE}, 20\penalty0
  (5):\penalty0 20--27, 2000.

\bibitem[Signell et~al.(2008)Signell, Carniel, Chiggiato, Janekovic, Pullen,
  and Sherwood]{Signell2008}
R.P. Signell, S.~Carniel, J.~Chiggiato, I.~Janekovic, J.~Pullen, and C.R.
  Sherwood.
\newblock Collaboration tools and techniques for large model datasets.
\newblock \emph{Journal of Marine Systems}, 69\penalty0 (1-2):\penalty0
  154--161, 2008.

\bibitem[Treinish(1999)]{Treinish1999}
L.~Treinish.
\newblock A function-based data model for visualization.
\newblock In \emph{Proceedings of the IEEE Visualization 1999 Conference Late
  Breaking Hot Topics}, pages 73--76, 1999.

\bibitem[Wachowicz(1999)]{Wachowicz1999}
M.~Wachowicz.
\newblock \emph{Object-oriented design for temporal GIS}.
\newblock CRC, 1999.

\end{thebibliography}

\section*{Appendix: Acronyms}
\begin{acronym}[NetCDF] % Use the widest acronym as an option, so they line up nicely
\acro{OGC}{Open Geospatial Consortium}
\acro{NetCDF}{Network Common Data Format}
\acro{UCAR}{University Corporation for Atmospheric Research}
\acro{API}{Application Programming Interface}
\acro{GDAL}{Geospatial Data Abstraction Library}
\acro{CDM}{Common Data Model}
\acro{OpenMI}{Open Modeling Interface}
\acro{VTK}{Visualization Toolkit}
\acro{GIS}{Geographic Information System}
Geographic information -- Schema for coverage geometry and functions
\end{acronym}

\section*{Appendix: Definition of Terms}
\label{sec:definitions}

\begin{description}
\item[Feature] Geospatial Feature as defined by OGC. We will call Feature any type that implements at least the Geometry property and has a set of other attributes.
\item[Geometry] Feature Geometry as defined by OGC. An attribute of the Feature.
\item[Coverage] Specific type of Feature that can generate a value for any point within its domain. Examples include raster images, a polygon overlay or a digital elevation matrix. In other words, it is a geospatial feature and a function at the same time.
\item[Function] A vector(-valued) function. A function of one or more variables whose range is $n$-dimensional. It associates dependent variable (component) values with independent variable (argument) values. As an example, a scalar function has $n=1$ (a one-dimensional \emph{range}-space), but it may still 'live' on a multi-dimensional \emph{domain}-space.
\item[Variable] Defines a value that may change within the scope of a given problem. The mathematical definition is used, not to be confused with a computer science variable. Variables can be independent or dependent on other variables.
\item[Unit] Defines unit of measure for variable values. For example [m], [m/s], etc.
\item[Array] In general a multi-dimensional array of some value type.
\end{description}
\begin{minipage}{\columnwidth}
\address{Gennadii Donchyts, Fedor Bart, H.R.A (Bert) Jagers, Arthur van Dam: \\
Deltares,\\
Rotterdamseweg 185, Delft, The Netherlands\\
P.O. Box 177, 2600 MH Delft, The Netherlands\\
\email{gennadii.donchyts@deltares.nl}\\
\email{fedor.baart@deltares.nl}\\
\email{bert.jagers@deltares.nl} \\
\email{arthur.vandam@deltares.nl}
}
\end{minipage}
% finish the document with this command and we're all done!
%\setcounter{secnumdepth}{1}
\end{article} %% DOCEND
