`rect2cube` documentation

The `rect2cube` function reshapes and permutes a 2D matrix into a 3D cube. `rect2cube` is the complement of `cube2rect`.

Back to Climate Data Tools Contents

## Contents

## Syntax

A3 = rect2cube(A2,gridsize) A3 = rect2cube(A2,mask)

## Description

`A3 = rect2cube(A2,gridsize)` reshapes 2D matrix `A2` into a 3D matrix whose first two dimensions are spatial (e.g., lat x lon or lon x lat) and whose third dimension is time or perhaps ocean depth or some variable along which operations are performed. The final dimensions of `A3` are specified by `gridsize`, which may be a complete 3 element array describing `A3`, or gridsize may be just a 2 element array containing the first two dimensions of `A3`.

`A3 = rect2cube(A2,mask)` reshapes the elements of `A2` into the `true` grid cells in a 2D matrix `mask`.

## Why does this function exist?

Good question! The short answer is it enables fast and easy vectorization, meaning no more nested loops. A more nuanced explanation with lots of examples can be found in this Tutorial on 3D data analysis.

## Example 1: Simplest case

This example starts with a random 4x3x2 matrix, meaning it is a grid that has spatial dimensions 4x3 and there are two measurements--two "time" slices-- for each point in the grid:

```
% A random 4x3x2 matrix:
A3 = randi(50,[4 3 2])
```

A3(:,:,1) = 33 45 15 42 36 14 16 13 1 21 38 19 A3(:,:,2) = 22 47 29 16 44 25 15 20 14 13 24 50

Convert `A3` into a 2D matrix via `cube2rect`:

A2 = cube2rect(A3)

A2 = 33 42 16 21 45 36 13 38 15 14 1 19 22 16 15 13 47 44 20 24 29 25 14 50

Above we see that the top row of `A2` contains the values of each grid cell in the first "time slice" of `A3`, and the second row of `A2` corresponds to the second time slice.

To get A3 back into its original 3D arrangement, use `rect2cube` and specify the dimensions you'll want `A3` to be:

A3 = rect2cube(A2,[4 3 2])

A3(:,:,1) = 33 45 15 42 36 14 16 13 1 21 38 19 A3(:,:,2) = 22 47 29 16 44 25 15 20 14 13 24 50

And that brings us back to where we started.

Note: You don't actually have to specify the third dimension of `A3` when you use the syntax above. You can just specify the first two dimensions and `rect2cube` will figure out the third one, like this:

A3 = rect2cube(A2,[4 3]);

## Example 2: Masking

If you're working with very large grids of climate data, you might find it more computationally efficient to remove regions that aren't of interest before performing calculations. To accomplish this, create a mask containing `true` values for any grid cells you want to keep.

In this example, we'll also use a mask with 7 `true` values indicating grid cells we want to analyze and 5 `false` values that we don't want to include in our analysis:

```
% Create a mask:
mask = true([4 3]);
mask([3 4 6 10 11]) = false
```

mask = 4×3 logical array 1 1 1 1 0 0 0 1 0 0 1 1

Convert `A3` into a 2D matrix via `cube2rect`:

A2 = cube2rect(A3,mask)

A2 = 33 42 45 13 38 15 19 22 16 47 20 24 29 50

Above we see that every `true` grid cell in the `mask` gets a column in `A2`, and the rows of `A2` correspond to the time slices of `A3`.

Now if we want to get `A2` back into a 3D grid, use the same mask:

A3b = rect2cube(A2,mask)

A3b(:,:,1) = 33 45 15 42 NaN NaN NaN 13 NaN NaN 38 19 A3b(:,:,2) = 22 47 29 16 NaN NaN NaN 20 NaN NaN 24 50

Above, you'll notice that `A3b` does not exactly match the `A3` matrix we started with, because we threw away all the information in the grid cells that corresponded to `0` in the `mask`, and then later we had to fill them in with `NaN` values. This is a lossy way of doing analysis, but if those grid cells were not relevant to the analysis anyway, then was anything really lost?

## Author Info

This function is part of the Climate Data Toolbox for Matlab. The function and supporting documentation were written by Chad A. Greene of the University of Texas at Austin.