This package is no longer in active development, and I do not recommend using it. The xgcm 'transform' function (see docs here_) is a better alternative with more community support.
xlayers allows you to transform your data from a regular vertical grid (like depth) to a vertical grid defined based on contours of some variable (like density). xlayers uses FORTRAN code from the layers package of the MITgcm, which was written by Ryan Abernathey.
We recommend using this package on xarrays, but it can also be applied to numpy arrays. This example may be helpful in getting started.
xlayers has many advantages over other similar tools. It conserves the total quantity of the input variable in the water column: this is particularly important when performing volume or heat budgets in density space. xlayers outputs the thickness-weighted variable in density space, which makes thickness-weighted averaging easier. This output is mapped in a smooth and sensible way. xlayers is also very fast and parallelizable.
xlayers can be installed from PyPI with pip:
python -m pip install xlayersIt is also available from conda-forge for conda installations:
conda install -c conda-forge xlayersTo install xlayers from source repository, the fortran-compiler package is required. The easiest way to install the fortran-compiler is via conda :
conda install -c conda-forge fortran-compiler
unset LDFLAGSOnce the compiler is installed, now we can install xlayers from Github:
git clone https://github.com/cspencerjones/xlayers.git
cd xlayers
python setup.py installxlayers is property conserving, meaning that the total amount of your variable in the water column will not change when it is transformed into the new coordinate system.
xlayers acheives this using binning: it bins the variable onto a much finer vertical grid, estimates the depth of the new coordinate surfaces, and adds up these bins in the new space.
This package expects your initial coordinate system to be on a structured grid. i.e. it will not take density as an initial vertical variable, but depth is ok.
Before running layers_xarray, you must run finegrid to define some of the binning parameters needed. finegrid takes 2 inputs (which should both be numpy arrays): the vertical depth of the gridcells, and the vertical distance between the centers of the grid cells. The second variable should be loneger by 1 than the first, because it includes the distance between the cell center of the top cell and the sea surface, and the distance between the cell center of the bottom cell and the domain bottom.
The first two inputs to layers_xarray should be on the same gridpoints. data_in is the variable to be remapped and theta_in is the variable that defines the location of the new coordinate system.
The output of layers_xarray is thickness weighted, i.e. if the input variable is salinity, the output variable is the salinity in each layer multiplied by the depth of the layer. In order to get an output that has the same units as the input, divide by the thickness of the layer (which you can get by inputting an array of ones into layers_xarray instead of you input variable data_in).
- Report bugs, suggest features or view the source code on GitHub.