scuba-package: The Scuba Package

In scuba: Diving Calculations and Decompression Models

The Scuba Package

Description

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.

Details

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.

Dive profiles

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.

Real Dive Profiles

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.

Decompression Calculations

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.

Nitrox and trimix

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.

Diving on different gases

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<-.

Manipulating dive profiles

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.

Changing the breathing gases

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".

Licence

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.

Author(s)

\adrian

with contributions from Vittorio Broglio and Pedro Antonio Neves.

References

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.

scuba documentation built on Oct. 18, 2022, 5:06 p.m.