depth_mapper is a function to convert a ROMS variable from terrain-following vertical coordinates to Atlantis layers.

Useage:


[output_var,nlayer] = depth_mapper(input_var,layers,grdfile)

Input Arguments:

grdfile – A string specifying the path/filename of the grid file.
layers – The required Atlantis layer boundaries in a row vector.
input_var – input ROMS variable, with format (lat, lon, h, t)

Output Arguments:

output_var – the input variable with depths now mapped into the specified layers, with format (lat, lon, size(layers), time)
nlayer – this is the number of elements in the layers vector - size(layers)

Comments:

ROMS is a terrain-following vertical coordinate model, meaning that the distribution of vertical levels is not linear, but much denser directly below the surface and directly above the sea-floor. As the bathymetry / bottom depth is different for every spatial cell, the depths of every cell above will be different for every neighbouring cell. Atlantis, on the other hand, will have pre-defined layers, which are obeyed globally, across the whole model. As a result, the ROMS depths will need to be binned into the appropriate Atlantis layers. However, this cannot be done grossly across the whole ROMS variable, but it must be done for every individual water column.

To achieve this, we require the specified Atlantis layers, the bathymetry, the scaling vector and the desired variable. The process of mapping the ROMS depths to Atlantis layers begins by pre-allocating the output variable. It will be exactly the same size as the input variable, except that the depth dimension will now be equal to the number of specified layers. We then make the scaled bathymetry. Since the bathymetry is originally a 2D matrix, we must replicate that in the 3rd dimension and apply the scaling factor to each water column. The result is a 3D matrix, where the rows and columns are the lat and lon, and the 3rd dim is the depth – a 3D depth matrix.

We then begin filling the output variable, one layer at a time. Beginning from the first layer (e.g. 0m to 20m) we find all elements within the 3D depth matrix that fall within the bounds of that layer (e.g. within 0m to 20m). This returns a 3D logic matrix, with a 1 for within the layer, and a 0 for outside of the layer. By replacing all the zero's with NaN's, and multiplying this mask matrix by the variable, the variable is returned, but now any elements outside of the Atlantis layer are replaced with NaN's. By taking an average of all numbers, down each water column (i.e. down the 3rd dim), we obtain a 2-dimensional matrix, where each element is the average of the elements that comprise the layer. This can then be placed into the output variable. Then, the next layer down is examined, and so on, until the output variable is filled.

This is (hopefully) described in the picture above. In the ROMS grid, each cell (here illustrated by each separate coloured rectangle) stretches over a different depth, depending on the bathymetry of that cell. In order to map this to the Atlantis layers (the grey layers on the right), each ROMS cell that falls within the depth defined by the Atlantis layer is averaged. What this means, is that (depending on the bathymetry of the water column) each water column will contribute different cells to the layer. An example of this is the two water columns arrowed above. The column on the left will contribute ROMS cells to the Atlantis layers in this manner:
(1,2,3,4,5)---->Layer 1
(6,7,8,9)---->Layer 2
(10)---->Layer 3
Whereas, for the column arrowed on the right:
(1,2,3,4,5,6,7)---->Layer 1
(8,9,10)---->Layer 2
[nothing]---->Layer 3