This is a summary of the features of
scuba, a package in R
that performs theoretical calculations
about scuba diving --- dive profiles,
decompression models, gas toxicity and so on.
A dive profile gives the diver's depth as a function of elapsed
time during a scuba dive. The command dive creates an
object representing a dive profile.
A dive profile is piecewise linear: it is a series of stages that join successive waypoints. Each waypoint is specified by the depth and elapsed time when it is reached. The stage between two waypoints is either a sojourn at a fixed depth, or an ascent or descent at a constant rate.
The function dive interprets its arguments
as a sequence of actions or events occurring during the dive.
If an argument is a vector of length 2, it is interpreted
as c(depth,time) specifying the depth and duration
of a stage of the dive. If the argument is a single number,
it is interpreted as a depth, meaning that the diver ascends or
descends to this depth.
For example, the command
d <- dive(c(18, 45)) specifies a dive to 18 metres
for 45 minutes. The command d <- dive(c(18, 45), c(5,3))
specifies a dive to 18 metres for 45 minutes followed by a safety stop
at 5 metres for 3 minutes. Multilevel dives with any number of stages
are specified in the same way. A dive object may include
periods spent at the surface (depth zero) and may therefore represent
a succession of dives separated by surface intervals. For example,
d <- dive(c(30,15),c(9,1),c(5,5),c(0,60),c(12,60),c(5,5))
represents two dives (with safety stops)
separated by a one-hour surface interval.
The resulting object d is an object of class "dive".
It can be plotted as a conventional dive profile graph by executing
the command plot(d). It can be printed as a table of depths and times
by typing its name d, or by executing
print(d,seconds=FALSE) to print times to the nearest minute.
A summary of the dive (with such information as the average depth,
maximum depth and the main stages of the dive) can be printed
by typing summary(d).
By default, the function dive fills in some details
about the dive. It assumes that the diver breathes compressed air;
the dive starts and ends at the surface
(depth zero); the diver descends
at the default descent rate of 30 metres per minute; and the diver
ascends at the default ascent rate of 18 metres per minute.
These defaults can be changed by giving extra arguments to the
function dive.
Dive profiles can also be modified after they are created: see below.
Dive profiles may also be uploaded from your dive computer
and studied in the scuba package. First convert the
uploaded profile data to a data.frame with two columns,
the first column containing the elapsed time and the second column
containing the depth (in metres) recorded at each time. The elapsed
times can be either a vector of character strings
in minutes-and-seconds format
mm:ss or hours-minutes seconds hh:mm:ss,
or a vector of integer times measured in seconds
of elapsed time, or an object of class difftime
containing the elapsed times in any time unit. Then pass this data
frame as an argument to the function dive.
An example of such a data frame, uploaded from a dive computer,
is provided in the baron dataset supplied with the
package. See the help file for
baron for an example of how to convert a data frame
to a "dive" object.
The package also provides 12 real dive profiles that have already been
converted to "dive" objects.
See the help files for pedro and deepmine.
The scuba package performs the mathematical calculations of decompression theory:
the theoretical No Decompression Limit (maximum duration of a
no-decompression dive to a specified depth) can be computed by
ndl(depth)
the quantity of nitrogen dissolved in the diver's body
after a dive d can be computed by haldane(d)
the quantity of nitrogen dissolved in the diver's body
at each instant during a dive d can be computed by
haldane(d, progressive=TRUE)
or plotted interactively by showstates(d).
These calculations are based on the classical theory of decompression originated by Haldane (Boycott et al, 1908). The diver's body is idealised as a set of independent compartments, each connected directly to the breathing gas, and governed by classical (exponential) diffusion.
The model parameters (the number of compartments, their diffusion
rates, and the maximum tolerated nitrogen tension in each compartment)
may be chosen by the user.
By default, the model parameters are taken from the DSAT model
which is the basis of the PADI Recreational Dive Planner.
Alternatively, the user can choose from a variety of standard compartment
models using the command pickmodel, or
construct a new model using hm.
No-decompression limits (the maximum duration of a no-decompression
dive to a given depth) can be calculated using the function
ndl. For example ndl(30) gives the
theoretical NDL for a dive to 30 metres,
predicted by the DSAT model. To use the classical US Navy model instead,
type ndl(30, model="USN") or ndl(30, model=pickmodel("USN")).
The ‘best’
double no-decompression dive to given depths d1 and d2
can be calculated by bestdoubledive according to
the algorithm of Baddeley and Bassom (2012).
The nitrogen tension (the quantity of dissolved nitrogen,
in atmospheres absolute) in the diver's body after
a dive, can be calculated using the function
haldane. If d is a dive object
then haldane(d) returns a data frame containing the
nitrogen tissue tensions (ata) at the end of the dive,
in each of the 8 tissue compartments
of the DSAT model.
To use the US Navy model instead,
type haldane(d, "USN") or haldane(d, pickmodel("USN")).
To compute the nitrogen tissue tensions at each waypoint during the
dive, use haldane(d, progressive=TRUE).
To visualise the nitrogen tissue tensions during the dive,
use the interactive function showstates.
This plots the dive and waits for you to click on
a position in the graph. The tissue tensions at that
instant are displayed as a bar plot.
The total oxygen toxicity incurred during a dive can be computed
by oxtox.
Oxygen partial pressure at each stage of a dive is computed
by ppO2.
Bubble theory calculations are not yet implemented.
A breathing gas is represented by an object of class "gas".
The object air is a representation of compressed air
(21% oxygen, 79% nitrogen) as an object of this class.
(Don't reassign another value to this object!!!)
Nitrox mixtures (mixtures of oxygen and nitrogen) can be
represented using the function nitrox.
For example, EAN 32 is represented by nitrox(0.32).
Trimix (a mixture of oxygen, nitrogen and helium) can also be
represented, using the command trimix.
For example, Trimix 15/50
(containing 15% oxygen, 50% helium and 35% nitrogen)
is represented by trimix(0.15, 0.5).
There are methods for print and summary
for gas objects.
Decompression calculations (haldane,
ndl, showstates)
also work with nitrox and trimix.
Decompression calculations with trimix require a Haldane model
that includes parameters for Helium diffusion.
Use pickmodel("Z") to select the Buehlmann ZH-L16A model,
or hm to create a new model that includes
Helium diffusion.
Standard nitrox calculations are also available, for example
ead | equivalent air depth |
mod | maximum operating depth |
maxmix | richest nitrox mix for a given depth |
The total oxygen toxicity incurred during a nitrox or trimix dive
can be computed by oxtox.
Oxygen partial pressure at each stage of a dive is computed
by ppO2.
Every "dive" object contains information
about the breathing gas or gases used in the dive.
This information is determined when the "dive" object is
created (by the function dive). The default
breathing gas is air.
The function dive interprets its arguments
as a sequence of actions or events occurring during the dive.
If an argument is a vector of length 2, it is interpreted
as c(depth,time) specifying the depth and duration
of a stage of the dive. If the argument is a single number,
it is interpreted as a depth, meaning that the diver ascends or
descends to this depth.
Each argument to dive may also be a "gas" object,
like nitrox(0.32),
which means that the diver switches to this gas.
So, for example,
dive(nitrox(0.32), c(30,20))
means a dive to 30 metres for 20 minutes conducted on EAN 32
(Nitrox 0.32) from start to finish.
The command
dive(c(30,20), 5, nitrox(0.36), c(5,3)) means
a dive on air to 30 metres for 20 minutes, ascending to 5 metres
while breathing air, then switching to EAN 36 for a safety stop
at 5 metres for 3 minutes.
Alternatively you can use the argument tanklist to
specify a list of tanks of breathing gas (with optional names
like "travel" and "deco") and change between tanks at different
stages of the dive using an argument of the form tank=number
or tank=name. The tank list of a dive object can be extracted
using tanklist and modified using
tanklist<-.
Dive profiles can also be manipulated after they are created. This allows you, for example, to modify the deepest portion of a dive (diving to a deeper depth or for a longer duration), to abort a dive prematurely, to cut-and-paste several dives together, or to consider the tissue saturation incurred by a particular segment of a dive.
The commands depths.dive and times.dive
extract the depths and elapsed times at each waypoint during the dive.
The depths can be modified using depths.dive<-. For
example d <- dive(c(30,20)) creates a dive to 30 metres for 20
minutes, starting and finishing at the surface;
to change the depth to 35 metres, type depths.dive(d)[2:3] <- 35.
Similarly the elapsed times can be modified using
times.dive<-. It may be more convenient to use the
functions durations.dive and
durations.dive<- which give the duration of each stage
(the time between two successive waypoints).
For example durations.dive(d)[2] <- 25 would mean that the
diver now spends 25 minutes at the bottom instead of 20 minutes.
To extract only part of a dive profile, use chop.dive.
To paste together two dive profiles or fragments of dive profiles,
simply give them as arguments to dive.
A dive object has a tank list which is a list of the
tanks of breathing gas that were used (or were available to be used)
during the dive. The function tanklist returns
this list, and the function tanklist<- changes the list.
For example,
d <- dive(c(30,20), c(5,5)) is a dive conducted using air.
To modify it to a dive that used nitrox EANx 32, simply type
tanklist(d) <- list(nitrox(0.32)).
Again d <- dive(air, c(30,40), 6, nitrox(0.5), c(6,3), c(3,3)) is a
dive conducted using air (tank 1) for the deep section and EANx 50
(tank 2) for the decompression stops at 6 metres and 3 metres.
To change the contents of tank 1 to EANx 32, type
tanklist(d) <- list(nitrox(0.32), nitrox(0.5)) or
just tanklist(d)[[1]] <- nitrox(0.32).
To associate a name which
each tank, give names to the entries in the tank list, for example
tanklist(d) <- list(deep=nitrox(0.32), deco=nitrox(0.5))
or just assign names(tanklist(d)) <- c("deep", "deco").
The selection of tanks,
i.e. which tank is actually used at each stage of the
dive, is specified by the function whichtank.
The command whichtank(d)
returns a vector of integers or character strings,
identifying which tank in the tank list is in use at each
waypoint during the dive. That is, whichtank(d)[i] is the tank
in use at the ith waypoint during the dive.
The vector whichtank(d) has the same length as the vectors
depths.dive(d) and times.dive(d).
To change the selection of tanks at each stage during the dive,
use the function whichtank<-. For example,
d <- dive(air, c(30,40), 6, nitrox(0.5), c(6,3), c(3,3)) is a
dive conducted using air (tank 1) for the deep section and EANx 50
(tank 2) for the
decompression stops at 6 metres and 3 metres. To change this
so that the deco gas is only used at the 3-metre stop, type
whichtank(d) <- ifelse(depths.dive(d) < 3, 1, 2).
Alternatively whichtank(d)[depths.dive(d) > 3] <- 1
would select tank 1 for all parts of the dive deeper than 3 metres.
These manipulations are usually easier to understand if the tanks
have names. For example typing
names(tanklist(d)) <- c("deep", "deco") we could then
type whichtank(d) <- ifelse(depths.dive(d) < 3, "deep", "deco")
or whichtank(d)[depths.dive(d) > 3] <- "deep".
This library and its documentation are usable under the terms of the "GNU General Public License", a copy of which is distributed with the package.
Adrian Baddeley Adrian.Baddeley@curtin.edu.au with contributions from Vittorio Broglio and Pedro Antonio Neves.
scuba is a package for performing
calculations in the theory of scuba diving.
The package supports
creation, manipulation and plotting of dive profiles
gas diffusion models
decompression calculations
gas toxicity calculations.
The scuba package is intended only
for use in research and education about the mathematical
and statistical basis of decompression theory. It is emphatically
not designed for actual use in scuba diving and related activities.
See the detailed disclaimer in scuba.disclaimer.
Following is a summary of the main features of the package. For a more detailed explanation, with illustrations, see the vignette Introduction to the Scuba package which accompanies the package.
Baddeley, A. (2013) Introduction to the scuba package. Vignette accompanying this package.
Baddeley, A. and Bassom, A.P. (2011) Classical theory of decompression and the design of scuba diving tables. The Mathematical Scientist 36, 75-88.
Bookspan, J. (1995) Diving physiology in plain English. Undersea and Hyperbaric Medicine Society, Kensington, Maryland (USA). ISBN 0-930406-13-3.
Boycott, A.E. Damant, G.C.C. and Haldane, J.S. (1908) The prevention of compressed air illness. Journal of Hygiene (London) 8, 342--443.
Brubakk, A.O. and Neuman, T.S. (eds.) (2003) Bennett and Elliott's Physiology and Medicine of Diving. 5th Edition. Saunders. ISBN 0-7020-2571-2
Buehlmann, A.A. (1983) Dekompression - Dekompressionskrankheit. Springer-Verlag.
Buehlmann, A.A., Voellm, E.B. and Nussberger, P. (2002) Tauchmedizin. 5e Auflage. Springer-Verlag.
Tikvisis, P. and Gerth, W.A. (2003) Decompression Theory. In Brubakk and Neuman (2003), Chapter 10.1, pages 419-454.
Wienke, B.R. (1994) Basic diving physics and applications. Best Publishing Co.
Workman, R.D. (1965) Calculation of decompression schedules for nitrogen-oxygen and helium-oxygen dives. Research Report 6-65. US Navy Experimental Diving Unit. Washington DC.