Module 2 Script

Module 2: The oce R Package

Module Overview
Slide 1: Title Slide
In this section, you will learn about the need for the oce package, as well as seven tools that oce has to
offer, to make this package so powerful.

M2 Lesson 1: The oce R Package

Slide 1: Title Slide
Slide 2: Solution: Ability to Analyse a Variety of Different Data
The solution to having the ability to analyse a variety of different data is the oce R package. This package
is a free to use software used to analyse a variety of ocean observational data. It gives us the ability to
analyse data in complex formats collected by various instruments.

Slide 3: oce Resources

When you are first getting started with the oce package, there are a number of resources that you can
look into, including:

1. The official CRAN page

2. the oce website

3. The oce GitHub page

4. Blogs; and

5. Dan Kelley's book

Slide 4: Built-in Datasets

oce also has several built-in datasets to allow the user to become familiar with the structure and
information within the data.

Slide 5: Useful oce Tools

However, all real-world analysis would start by reading in your own data, which is the first tool that we'll
learn about today.

Slide 6: End of Lesson

Module 2 Script

M2 Lesson 2: Easily Read in Oceanographic Data

Slide 1: Title Slide
Slide 2: Easily Read in Data
The read.oce() function looks at the file suffix or what type of file it is that you are trying to read. It also
looks at the information that's stored within that file. Based off of those two things, the information as
well as the file type, read.oce() function can actually tell you what type of instrument you are looking at.

Slide 3: Demonstration
To demonstrate this, in RStudio you should open up the oce.R code to go line by line in the code. If you
are on a MacOS device, you just go to the beginning of the line and click Command+Enter. If you’re on a
Windows device, you should go to the beginning of the line then click Control+Enter, which allows you
to run each line of code line by line.

In line two and three we’re loading up the required packages for this code which is oce and ocedata. In
line 4, we're highlighting the read.oce() function so you can see that the argument that is provided was
a file name type. Stored within your workshop_material folder, you can see that a sample file for CTD
data type named ctd.cnv is provided. The name of that sample file becomes your argument in
read.oce(). When we make that line happen, we are given some warning messages which we will address
later on in this workshop. The other thing you can do is str() of your object. If we make that line happen
and just scroll to the top, you can see that the read.oce(), based on the fact that this was a cvs file and
that it stored certain information, told you that we're looking at a class. In other words, it was able to
identify what type of file you were looking at.

Slide 4: End of Lesson

M2 Lesson 3: Easy Access to Data

Slide 1: Title Slide
Slide 2: oce Useful Tools
Now that we’ve read in our data using read.oce(), we're going to talk about the second tool that oce
provides, which is easy access to data.

Slide 3: Easy Access to Data

read.oce() has broken up our data into a structure that contains: data, metadata, and processingLog.
Stored within the data, we have a list containing all of the actual data, such as pressure, temperature,
salinity, etc. The metadata on the other hand, is a list containing information about the data. This would
include things such as units, quality flags, sampling locations, scientist names, cruise names, etc. Lastly,
we also have the processingLog, which is a list that documents how the object was created and possibly
changed thereafter. That means it acts as a diary or history log of any of the changes that have occurred
to that file type.
Module 2 Script

Slide 4: Easy Access to Data

The power of having the data broken up into the data, metadata, and processingLog structure is the
ability to now use the [[ (‘square bracket square bracket’) function. This function allows us to extract
information within the file without needing to know where it's stored in the file.

Slide 5: Demonstration
So I will should you what I mean by that. In line eight, our goal here is to extract the temperature from
our object. Temperature is stored within the data of our object, so if we make line 8 happen that's one
way of extracting the temperature. However, let's say for example we didn't want to remember where
the temperature is stored; that's where [[ is used. This function extracts information regardless of
where it's stored in the file. In line 9, you’re doing the exact same thing as line 8 only [[ is allowing you to
not remember where data is stored.

Slide 6: Easy Access to Data

The [[ function also allows us to extract entire metadata or data sets

Slide 7: Demonstration
Going back over to RStudio, in line 12 for example we’re saying ctd[[‘metadata’]], which will extract all of
the metadata. We are then sorting the names of the metadata, which will show us all of the metadata
names in alphabetical order.

Slide 8: End of Lesson

M2 Lesson 4: Easy Access to Derived Variables

Slide 1: Title Slide
Slide 2: oce Useful Tools
Now that we have read in our data using read.oce, we’ve practiced the [[ method to extract data that
exists within our file, the next thing that we're going to do is demonstrate how the [[ method can also
extract data that can be calculated from the data that is within our file. This means the data doesn't
necessarily need to be stored in our data, but if the file contains the required information, we can extract
calculated or derived variables as well.

Slide 3: Easy Access to Derived Variables

So the first question is: how do you know what you can extract?

Slide 4: Demonstration
In order to do that, go to Rstudio and type ctd[[“?”]]. This will give you a list of the names of the metadata,
the derived metadata, names of any data, and a list of any derived variables. An example of this is
temperature. Earlier in this workshop we used [[ to extract our temperature. For those who don't know,
when you extract temperature from a object, you're extracting what's known as the in situ temperature.
That means that it’s measured directly in the water. Some scientists, however, want a more accurate
Module 2 Script

representation of temperature which is known as conservative temperature. We can extract the

conservative temperature by either doing [[“CT”]] or [[“Conservative Temperature”]], which is derived
from a calculation. It is important to know, however that these extractions are case sensitive.

In line 18 we're just extracting the in-situ temperature that is stored within our file and in line 19 we're
extracting the conservative temperature. Remember, we don’t have conservative temperature in our
file, but it can be calculated. If we compare the summary of temperature and CT, we can see that there
are slight differences.

Slide 5: End of Lesson

M2 Lesson 5: Extensive Support for Object Metadata

Slide 1: Title Slide
Slide 2: oce Useful Tools
At this point, we’ve read in our data, using read.oce(), where read.oce() looked at the file type, as well as
the information stored within the file, to actually tell us that we were looking at a object. We then know
that that function broke up our file into data, metadata, and processingLog. This structure allows us to
use [[ to extract not only data that is stored within the file, but also data that can be calculated from the
data stored within the file. Now the next tool that we are going to focus on here is the extensive support
for object metadata.

Slide 3: Support for Object Metadata

As we mentioned, read.oce() breaks up a file and it has this metadata component which stores
information such as units, scales, quality control flags, cruise number, etc.

Slide 4: Demonstration
If we now look over at our R Studio, in line 27, we can extract all of the metadata from our file. Let’s say,
for example, we were dealing with temperature and we wanted to determine if temperature was stored
in Celsius or Fahrenheit. In that case, we would do the following. In line 29, we're saying what parameters
have units associated with them. In line 30, we’re only looking at the temperature units, which in this
case is degree Celsius.

We also see that temperature has a specific scale. The scale tells us what calibration year is used in this
case for temperature. When we first read in the file, some warning messages were produced. One of
them in the cnv file that we're trying to read in temperature that is on the 1968 scale, meaning it's the
calibration year from 1968, however we're going to convert this so that the numbers are consistent with
the 1990s scale. It was just giving the user a warning that there's actually a more up-to-date calibration
year and any of the sea water calculations are going to use that up to date calibration year. There is
another warning, which is unrelated to the scale but while we're talking about warnings, it is telling us that
our file has a start time of 1903. This file, however, was not created in 1903 but rather 2003. This
occurred because in this particular file, the start year was entered as just “03” so the system read that
Module 2 Script

as 1903 rather than 2003. oce actually picked up that the date was not in a range that was expected and
suggests we may want to change it.

Slide 5: End of Lesson

M2 Lesson 6: Specialised Oceanographic Plots

Slide 1: Title Slide
Slide 2: oce Useful Tools
The next tool that we're going to look at specialised oceanographic plots. Depending on what type of
instrument you are looking at, oce has a way to guide them to show them what type of plots you might
want to make.

Slide 3: Specialised Oceanographic Plots

As you can see here, these are the default plots for a CTD plot, compared to the default plots for a
sea level type.

Slide 4: Demonstration
In Rstudio, if we load up the build in ctd data set using data(ctd) and type plot(ctd), we see that there are
a number of default plots such as temperature, salinity, TS, etc. On the other hand, if you load up the
sealevel data using data(sealevel), and then do plot(sealevel), you will see that default plots include
elevation, etc. This package looks at what information the user has to determine what they may want
to plot. To determine what options a user for plotting, the user should type ?`plot, ctd-method`, if
they’re dealing with a ctd object. They can also do ?oce, scroll down to the bottom of the help pages
where it says “Index”, click “P” for plot, and look down for where it says ctd object. They can then see all
of the different types of plots that they can make for ctd types. They also have the option of doing the
same approach for all other instrument types. For the ctd type, we see that there is an option to plot a
TS or temperature-salinity diagram. That is exactly what we’re going to do in line 36. We can also change
the aesthetics of this plot, for example, if we wanted to change the symbol type we would say plot(ctd,
which=”TS”, pch=20) and if we wanted to change the colour of the symbols we could do plot(ctd,
which=”TS”, pch=20, col=”red”).
Slide 5: End of Lesson

M2 Lesson 7: Easier Mapping

Slide 1: Title Slide
Slide 2: oce Useful Tools
Up to this point, we’ve looked at read.oce(), which reads in our file, and looks at what type of file it is, as
well as what information is stored in it to determine what type of instrument we are looking at. It then
breaks up our file into data, metadata, and processingLog, which allows us to use [[ to extract data or
Module 2 Script

information that not only exists within our file, but also information that can be derived or calculated. We
also looked at extensive support for metadata, such as units and scales, and then we just demonstrated
that there are specialised plots, depending on the type of file that we are looking at. The next thing we
are going to focus on is oce having the ability to provide easier mapping, especially projections.

Slide 3: Easier Mapping

For an explanation on when to use certain projections, meaning what projection to use at the poles
versus the equator, etc., I encourage you to click on the link in the PowerPoint provided that will take you
to the mapping vignette and really explain when you should what type. For the sake of this, we are just
going to show basic mapping skills of oce, and we are going to do that using mapPlot. mapPlot() is the
function used to plot coastlines.

Slide 5: Demonstration
In RStudio, in line 43 we're loading up our coastlineWorld data set and this coastlineWorld data set is just
telling us where the coastlines are in the world. In line 44, we're just saying plot up that coastline and use
the default Mollweide projection. We also have the ability, similar to the specialised plots, to customise
our map by changing the colour of the land or change the region of interest. In line 47, we’re loading up
coastlineWorldFine and that's what we use when we were looking at specific region or zooming in on a
specific region. In this case, we’re zooming in where our CTD sample is taken by setting the longitude
and latitude limits. The correct latitude and longitude limits were known by doing ctd[[‘latitude’]] and
ctd[[‘longitude’]]. In line 48, I plot the high-resolution coast line, using the default projection, and only
plot in the latitude and longitude limits with the colour of my land being tan.

Slide 6: Easier Mapping

The next function I'm using is mapPoints(), and according to our PowerPoint you add the latitude and
longitude points to a mapPlot() using mapPoints().

Slide 7: Demonstration
In mapPoints(), the user can provide a longitude, latitude, the colour, and the symbol type.

Slide 8: End of Lesson

M2 Lesson 8: Data Quality Flags

Slide 1: Title Slide
Slide 2: oce Useful Tools
The last tool that we'll discuss is oce's ability to deal with data quality flags.

Slide 3: Data Quality Flags

If an error occurs in a controlled scientific setting such as laboratory, there is usually the option of
resampling the data to correct for the error. In oceanography, resampling is not always a possibility, and
Module 2 Script

therefore existing measurements must go through a series of quality control tests. The process will flag
data that is of poor quality or a result of error.

Slide 4: End of Lesson