Introduction to narwhal for oceanographers

narwhal is a package written in Python that aims to simplify handling oceanographic data. narwhal organizes data in a way that imitates its physical representation. For example, narwhal provides a CTDCast class with common processing operations built in.

Example

# Read in a set of CTD casts
ctd_data = narwhal.read('data.nwz')
# Select the first cast
cast1 = ctd_data[0]
# Print the geographical coordinates where the cast was collected
print(cast1.coords)
# Print the salinity field
print(cast1["sal"])
# Calculate the density based on temperature, pressure, and salinity, and print it
cast1.add_density()
print(cast1["rho"])

Cast types

Casts are initialized by providing a set of vector and scalar data. The vector data might represent pressure, temperature, and salinity profiles in a CTD cast, or depth and velocity components in an ADCP measurement. Scalar data (referred to as "properties") likely include geographical coordinates and timestamps, as well as comments, depth sounding notes, or other metadata.

pressure = [...]
salinity = [...]
temperature = [...]

cast = Cast(pressure, sal=salinity, temp=temperature,
            coords=(-58.7, 41.2), comment="likely an important observation")

The first argument is the primary vector, and is assumed to be pressure. Alternatives, such as depth or time can be specified by passing the primarykey keyword argument, e.g. primarykey="depth".

In addition to the generic Cast, specialized CTDCast, XBTCast, and ADCP types are available. These specialized casts automatically use the appropriate primary key.

CastCollection types

CastCollections are like lists of Casts, and could represent every cast from a cruise, a specific profile, or some other collection of ordered or unordered casts. It's possible to query CastCollection objects in a number of ways:

cc = CastCollection([...])

cc.castwhere("station", 31)      # returns the Cast with station number 31

cc.castswhere("depth", lambda d: 20 < d < 1000)   # returns all casts where "depth" is
                                                  # between 20 and 1000

cc.castswhere("station", (1, 2, 4, 5))   # returns a list of casts with matching
                                         # station numbers in the order they are found

cc.select("station", (1, 2, 4, 5))    # returns a list of stations in the same order
                                      # as specified

Some basic hydrographic analyses are built into CastCollections. For example, from a collection of CTD cast, geostrophic velocities can be inferred using

cc.thermal_wind()

which adds velocity shears and their integrals to each cast.

Bathymetry types

The class narwhal.Bathymetry is intended for holding bathymetric profiles collected from cruises, and is based on the karta.Line class.

Plotting

Visualizing data is an important part of the analysis and presentation processes. narwhal includes routines in the narwhal.plotting namespace built on top of matplotlib. These include routines for making common plots such as vertical profiles (plot_profile), characteristic property plots (plot_properties), and vertical sections.