Package 'forImage' reference manual

Title:	Foraminiferal Image Analysis and Test Measurement
Description:	The goal of this collection of functions is to provide an easy to use tool for the measurement of foraminifera and other unicellulars organisms size. With functions developed to guide foraminiferal test biovolume calculations and cell biomass estimations. The volume function includes several microalgae models geometric adaptations based on Hillebrand et al. (1999) <doi:10.1046/j.1529-8817.1999.3520403.x>, Sun and Liu (2003) <doi:10.1093/plankt/fbg096> and Vadrucci, Cabrini and Basset (2007) <doi:10.1285/i1825229Xv1n2p83>.
Authors:	Thaise R Freitas [aut, cre], Eduardo Bacalhau [aut], Carla Bonetti [aut]
Maintainer:	Thaise R Freitas <[email protected]>
License:	MIT + file LICENSE
Version:	0.1.0
Built:	2025-03-09 04:57:12 UTC
Source:	https://github.com/thaiserf/forimage

Ammonia size data

Description

A 'data.frame' containing the size and other attributes of species from genus Ammonia. The variables are as follows:

Usage

ammonia
ammonia

Format

A 'data.frame' with 867 rows and 7 variables:

species: species of genus Ammonia from which raw data were gathered
ind: number of individuals by species
h: test height in um (82.05–390.65)
d_one: test minor diameter in um (20–220)
d_two: test major diameter in um (75.1–364.6)
area: test surface area in um2 (4438–107903)
pco: percent cell occupancy of the test (11–100)

Amphistegina size data

Description

A 'data.frame' containing the size and other attributes of genus Amphistegina. The variables are as follows:

Usage

amphistegina
amphistegina

Format

A 'data.frame' with 167 rows and 5 variables:

ind: number of individuals
h: test height in um (60.0–579.0)
d_one: test diameter in um (111.3–1193.1)
area: test surface area in um2 (9722–3027282)
pco: percent cell occupancy of the test (3.408–100)

Angulogerina size data

Description

A 'data.frame' containing the size and other attributes of species from genus Angulogerina. The variables are as follows:

Usage

angulogerina
angulogerina

Format

A 'data.frame' with 100 rows and 6 variables:

ind: number of individuals
h: test height in um (81.75–380.91)
d_one: test minor diameter in um (34–156)
d_two: test major diameter in um (66.04–237.34)
area: test surface area in um2 (4654–41915)
pco: percent cell occupancy of the test (6.818–100)

Asterotrochammina size data

Description

A 'data.frame' containing the size and other attributes of species from genus Asterotrochammina. The variables are as follows:

Usage

asterotrochammina
asterotrochammina

Format

A 'data.frame' with 335 rows and 7 variables:

species: species of genus Asterotrochammina from which raw data were gathered
ind: number of individuals by species
h: test height in um (12–72)
d_one: test minor diameter in um (77.86–265.50)
radius: test radius in um (38.93–132.75)
area: test surface area in um2 (4761–57577)
pco: percent cell occupancy of the test (15–100)

Biovolume calculus

Description

This function calculates Foraminifera biovolume, through geometric approximation. To compute others organisms cell volume use volume.total function

Usage

bio.volume(data, pco = 0.76, genus = NULL, model = NULL)
bio.volume(data, pco = 0.76, genus = NULL, model = NULL)

Arguments

`data`	a numeric vector or data frame with size data. Size data parameters by model see `volume` details.
`pco`	(optional) vector informing percent of cell occupancy in the test. Default value set for specific genus in `data_pco`.
`genus`	(optional) character informing foraminifera genus to calculate individual biovolume. See all genera available in `data_pco`
`model`	(optional if genus unknown) character informing geometric model to calculate volume. See all models available in `volume.total`

Details

The function calculates the biovolume of different individuals from the available genera.

Value

A 'data.frame' or numeric object, consisting of calculated individual volume (if not available), biovolume and model (if genus is informed).

Author(s)

Thaise R. Freitas [email protected]

Examples

# Calculate biovolume for different genera
#Ammonia size data
data("ammonia")

bio.volume(ammonia, genus= "ammonia")

# Calculate biovolume for unknown genus
df <- data.frame(h = 10, d_one = 10,
d_two = 10, area = 10, width = 10, length = 10)
bio.volume(df, model = "10hl", pco = 0.76)

# Calculate biovolume for different genera
#Ammonia size data
data("ammonia")

bio.volume(ammonia, genus= "ammonia")

# Calculate biovolume for unknown genus
df <- data.frame(h = 10, d_one = 10,
d_two = 10, area = 10, width = 10, length = 10)
bio.volume(df, model = "10hl", pco = 0.76)

Biomass estimative

Description

The function estimates biomass through biovolume data and applies different cell density values as conversion methods. See details ‘Details’:

Usage

biomass(biovolume, method = "michaels")
biomass(biovolume, method = "michaels")

Arguments

biovolume

numeric value, object or data.frame with cell living volume values.

method

The methods of conversion from biovolume to biomass are listed below, default is 'michaels':

'saidova' : adopted cell density of 1.027 g/cm3;
'strathmann' : measured cell density of 0.110 pgC[org]/um3;
'turley' : estimated cell density of 0.132 pgC[org]/um3;
'putt' : estimated cell density of 0.140 pgC[org]/um3;
'gerlach' : adopted cell density of 1.13 g/cm3 wet mass, assuming 10 percent as living organic carbon;
'michaels' : calculated cell density of 0.089 pgC[org]/um3.

Details

For biomass estimates based on biovolume is usual the application of a cell density value, to retrieve the amount of organic carbon in the organism. The function made available distinct options of conversion factor which are based in several authors. These factors have been applied to a wide diversity of nano, micro, and macro-organisms, some applied to foraminifera and other nearby groups.

Value

An 'data.frame' or numeric object, consisting of calculated biomass in ugC[org]/ind.

Author(s)

Thaise R. Freitas [email protected]

References

Saidova, K. (1966). The biomass and quantitative distribution of live foraminifera in the Kurile-Kamchatka trench area. DOKLADY AKAD. NAUK SSSR, 174(1), 216–217.
Strathmann, R. (1967). Estimating the Organic Carbon Content of Phytoplankton from Cell Volume or Plasma Volume. Limnology and Oceanography, 12, 411–418. doi:10.4319/lo.1967.12.3.0411
Turley, C., Newell, R., & Robins, D. (1986). Survival Strategies of 2 Small Marine Ciliates and Their Role in Regulating Bacterial Community Structure Under Experimental Conditions. Marine Ecology Progress Series, 33(1), 59–70. doi:10.3354/meps033059
Putt, M., & Stoecker, D. K. (1989). An experimentally determined carbon : volume ratio for marine ‘oligotrichous’ ciliates from estuarine and coastal waters. Limnology and Oceanography, 34(6), 1097–1103. doi:10.4319/lo.1989.34.6.1097
Gerlach, S. A., Hahn, A., & Schrage, M. (1985). Size spectra of benthic biomass and metabolism . Marine Ecology Progress Series, 26, 161–173. doi:10.3354/meps026161
Michaels, A. F., Caron, D. A., Swanberg, N. R., Howse, F. A., & Michaels, C. M. (1995). Planktonic sarcodines (Acantaria, Radiolaria, Foraminifera) in surface waters near Bermuda: abundance, biomass and vertical flux. Journal of Plankton Research, 17(0), 131–163. doi:10.1093/plankt/17.1.131

Examples

#Ammonia biomass calculation
data(ammonia)

#calculate test volume and biovolume
df <- bio.volume(data = ammonia, genus = "ammonia")
df

#calculate individual biomass with choosen method
res <- biomass(df, method = 'michaels')
res


#Ammonia biomass calculation
data(ammonia)

#calculate test volume and biovolume
df <- bio.volume(data = ammonia, genus = "ammonia")
df

#calculate individual biomass with choosen method
res <- biomass(df, method = 'michaels')
res

Bolivina size data

Description

A 'data.frame' containing the size and other attributes of species from genus Bolivina. The variables are as follows:

Usage

bolivina
bolivina

Format

A 'data.frame' with 628 rows and 7 variables:

species: species of genus Bolivina from which raw data were gathered
ind: number of individuals by species
d_one: test minor diameter in um (72.37–502.12)
h: test height (thickness) in um (12.5–83.0)
d_two: test major diameter in um (60.60–226.21)
area: test surface area in um2 (3187–72244)
pco: percent cell occupancy of the test (9.72–100)

Cibicidoides size data

Description

A 'data.frame' containing the size and other attributes of species from genus Cibicidoides. The variables are as follows:

Usage

cibicidoides
cibicidoides

Format

A 'data.frame' with 118 rows and 7 variables:

species: species of genus Cibicidoides from which raw data were gathered
ind: number of individuals by species
h: test height in um (24–117)
d_one: test minor diameter in um (76.46–266.85)
radius: test radius in um (38.23–133.43)
area: test surface area in um2 (4591–55928)
pco: percent cell occupancy of the test (11.87–100)

Foraminiferal genera data for `forImage` examples

Description

This 'data.frame' contains protoplasm occupancy mean and standard deviation data of 72 foraminifera genera. These genera data are originally from Freitas and others (2019)

Format

A 'data.frame' with 72 rows and 3 variables:

genera: foraminifera genera
mean: mean protoplasm occupancy percentage (pco)
sd: standard deviation of mean (pco)
n: number of specimens
model: fitted geometric model in Freitas and others (2019)

Details

Foraminifera genera with (pco) available:

"ammonia"	"amphistegina"	"angulogerina"
"archaias"	"asterotrochammina"	"bolivina"
"buliminella"	"cancris"	"caronia"
"cassidulina"	"cibicides"	"cibicidoides"
"cornuspira"	"cribroelphidium"	"cymbaloporetta"
"deuterammina"	"disconorbis"	"discorbia"
"discorbinella"	"discorbis"	"discorbitina"
"edentostomina"	"elphidium"	"eoeponidella"
"eponides"	"fissurina"	"fursenkoina"
"glabratella"	"globocassidulina"	"hanzawaia"
"hauerina"	"heronallenia"	"laevipeneroplis"
"lepidodeuterammina"	"loxostomina"	"miliolinella"
"mullinoides"	"mychostomina"	"neoconorbina"
"nonionella"	"nonioninoides"	"pararotalia"
"paratrochammina"	"patellina"	"planispirillina"
"planorbulina"	"planulina"	"pyrgo"
"quinqueloculina"	"rectocibicides"	"remaneicella"
"reophax"	"rosalina"	"rotaliammina"
"rotorbinella"	"rotorbis"	"sahulia"
"sigmavirgulina"	"siphonina"	"sorites"
"spirillina"	"spiroloculina"	"spirorbina"
"tetrataxiella"	"textularia"	"triloculina"
"triloculinella"	"trochammina"	"webbinella"
"wiesnerella"

Import image object depth (Z)

Description

The function retrieves the object depth information from image metadata as source.

Usage

## S3 method for class 'xml'
depth(x, ...)
## S3 method for class 'xml'
depth(x, ...)

Arguments

`x`	file containing metadata, if xml type: `'.xml', '.tif_meta.xml'`
`...`	other arguments.

Value

A 'data.frame' with the following information:

file : filename
z_depth : measured focus range depth (z)

Examples

## Not run: 
#Path to example file from package
meta <- system.file("extdata", "foram.tif_meta.xml", package="forImage")

#retrieve z-depth data
depth.xml(meta)
## End(Not run)

## Not run: 
#Path to example file from package
meta <- system.file("extdata", "foram.tif_meta.xml", package="forImage")

#retrieve z-depth data
depth.xml(meta)
## End(Not run)

Discorbinella size data

Description

A 'data.frame' containing the size and other attributes of species from genus Discorbinella. The variables are as follows:

Usage

discorbinella
discorbinella

Format

A 'data.frame' with 318 rows and 7 variables:

species: species of genus Discorbinella from which raw data were gathered
ind: number of individuals by species
h: test height in um (15–72)
d_one: test minor diameter in um (67.69–197.43)
radius: test radius in um (33.85–98.71)
area: test surface area in um2 (3599–30614)
pco: percent cell occupancy of the test (9.673–100)

Foraminiferal photomicrograph for `forImage` examples

Description

Contains image file of one foraminifer. These files are originally from previous work - Freitas and others (2019)

Format

Image objects with variable dimension and resolution.

Install python packages dependencies for measure function

Description

The function is a wrapper to install all python packages dependencies for measure function at once. It will install the following packages: numpy, scipy, imutils, Pillow, pandas, and opencv-python. If the latest versions of these packages are already installed, there is no need to run this function.

Usage

install_measure(
  method = "auto",
  conda = "auto",
  envname = NULL,
  extra_packages = NULL,
  pip = F
)
install_measure(
  method = "auto",
  conda = "auto",
  envname = NULL,
  extra_packages = NULL,
  pip = F
)

Arguments

`method`	Installation method. By default, "auto" automatically finds a method that will work in the local environment. Change the default to force a specific installation method. Note that the "virtualenv" method is not available on Windows.
`conda`	Path to conda executable (or "auto" to find conda using the PATH and other conventional install locations).
`envname`	Name of environment to install packages into.
`extra_packages`	Additional packages if needed.
`pip`	Install from pip, if possible.

Details

On Linux and OS X the "virtualenv" method will be used by default ("conda" will be used if virtualenv isn't available). On Windows, the "conda" method is always used. For more information check the 'reticulate' package documentation: https://rstudio.github.io/reticulate/

Value

No return value. The function is only called to install the required packages.

Laevipeneroplis size data

Description

A 'data.frame' containing the size and other attributes of species from genus Laevipeneroplis. The variables are as follows:

Usage

laevipeneroplis
laevipeneroplis

Format

A 'data.frame' with 79 rows and 7 variables:

species: species of genus Laevipeneroplis from which raw data were gathered
ind: number of individuals by species
h: test height in um (40–633.9)
d_one: test minor diameter in um (47–624.2)
area: test surface area in um2 (8827–306012)
pco: percent cell occupancy of the test (15.24–100)
d_two: test major diameter in um (169.2–544.0) - The NA's related to one species of this genus that don't required this measure

Loxostomina size data

Description

A 'data.frame' containing the size and other attributes of species from genus Loxostomina. The variables are as follows:

Usage

loxostomina
loxostomina

Format

A 'data.frame' with 31 rows and 7 variables:

ind: number of individuals by species
d_one: test minor diameter in um (101.4–534.6)
h: test height in um (28.0–80.0)
d_two: test major diameter in um (89.76–261.17)
area: test surface area in um2 (6636–76089)
pco: percent cell occupancy of the test (9.88–100)

Foraminifera image measurement

Description

This function measures dimensions in photomicrographs.

Usage

measure(file, scale = NULL, ref_scale = NULL,
unit = "um", pco = FALSE, save = FALSE, path = NULL)
measure(file, scale = NULL, ref_scale = NULL,
unit = "um", pco = FALSE, save = FALSE, path = NULL)

Arguments

`file`	image file with or without metadata.
`scale`	(optional) image physical pixel size (metric / pixel).
`ref_scale`	(optional) reference scale available on image (in micrometers or millimeters). This scale should be inserted under the main object.
`unit`	scale unit. Needs to agree with reference scale or metric per pixel. (Default "um")
`pco`	(optional) will assess proportion of cell occupancy inside the shell. Outlined proportion. This argument is still being tested and should be used with caution.
`save`	If TRUE save the result image in a specified folder (see `path`) or the working directory, if FALSE it does not save the image with measures. (Default FALSE)
`path`	(optional) path to save result file.

Value

A 'data.frame' containing the file name, surface area and major and minor axis. The unit is dependent on the pixel per metric scale. It also returns a PNG file with the measured dimensions if save = TRUE.

Author(s)

Thaise R. Freitas [email protected]

Examples

## Not run: 
#Path to example file from package
img <- system.file("extdata", "foram.tif", package="forImage")

#measure individual dimension
measure(img)

## End(Not run)

## Not run: 
#Path to example file from package
img <- system.file("extdata", "foram.tif", package="forImage")

#measure individual dimension
measure(img)

## End(Not run)

Nonionella size data

Description

A 'data.frame' containing the size and other attributes of species from genus Nonionella. The variables are as follows:

Usage

nonionella
nonionella

Format

A 'data.frame' with 208 rows and 7 variables:

species: species of genus Nonionella from which raw data were gathered
ind: number of individuals by species
d_one: test minor diameter in um (93.39–564.98)
h: test height in um (19.50–294.00)
d_two: test major diameter in um (82.99–547.67)
area: test surface area in um2 (5783–222371)
pco: percent cell occupancy of the test (15.51–100)

Patellina size data

Description

A 'data.frame' containing the size and other attributes of species from genus Patellina. The variables are as follows:

Usage

patellina
patellina

Format

A 'data.frame' with 79 rows and 6 variables:

ind: number of individuals by species
h: test height in um (24–66)
d_one: test minor diameter in um (84.84–247.46)
radius: test radius in um (42.42–123.73)
area: test surface area in um2 (5653–87838)
pco: percent cell occupancy of the test (9.94–100)

Quinqueloculina size data

Description

A 'data.frame' containing the size and other attributes of species from genus Quinqueloculina. As this genus has a wide morphological variation, two types of models can be applied to calculate its volume. Therefore the variables are grouped by model as well as by species. It is also an example that the model argument can be a 'data.frame' column. The variables are as follows:

Usage

quinqueloculina
quinqueloculina

Format

A 'data.frame' with 688 rows and 10 variables:

species: species of genus Quinqueloculina from which raw data were gathered
ind: number of individuals by species
h: test height in um (107.4–944.4)
d_one: test minor diameter in um (26.94–389.73)
d_two: test major diameter in um (18.52–662.23)
area: test surface area in um2 (6294–431271)
pco: percent cell occupancy of the test (13.76–100)
length: test length in um (44.02–609.00)
width: test width in um (83.72–688.32)
model: geometric model ('10hl'–'17fs')

Rectocibicides size data

Description

A 'data.frame' containing the size and other attributes of genus Rectocibicides. The variables are as follows:

Usage

rectocibicides
rectocibicides

Format

A 'data.frame' with 199 rows and 4 variables:

ind: number of individuals
h: test height in um (22.00–101.50)
area: test surface area in um2 (3450–674280)
pco: percent cell occupancy of the test (10–100)

Spirillina size data

Description

A 'data.frame' containing the size and other attributes of species from genus Spirillina. The variables are as follows:

Usage

spirillina
spirillina

Format

A 'data.frame' with 42 rows and 6 variables:

ind: number of individuals by species
h: test height in um (12–44)
d_one: test minor diameter in um (73.71–105.14)
radius: test radius in um (36.86–123.73)
area: test surface area in um2 (4268–34730)
pco: percent cell occupancy of the test (7.10–100)

Textularia size data

Description

A 'data.frame' containing the size and other attributes of species from genus Textularia. The variables are as follows:

Usage

textularia
textularia

Format

A 'data.frame' with 84 rows and 7 variables:

species: species of genus Textularia from which raw data were gathered
ind: number of individuals by species
h: test height in um (113.6–1034.4)
d_one: test minor diameter in um (40–306)
d_two: test major diameter in um (103.8–552.6)
area: test surface area in um2 (8235–336929)
pco: percent cell occupancy of the test (10.46–100)

Volumetric calculus of organisms

Description

The function calculates organisms volume based on geometric approximation.

Usage

## S3 method for class 'total'
volume(data, model, ...)
## S3 method for class 'total'
volume(data, model, ...)

Arguments

data

data frame containing size data. Size data parameters may vary according to chosen model, see Details.

model

character informing geometric model to calculate volume, the models options are listed below:

'1hl' : sphere
'2sl' : half-sphere
'3hl' : prolate spheroid
'4hl' : cone or double cone
'6fs' : paraboloid
'7fs' : dome
'8hl' : cylinder
'10hl' : ellipsoid
'11fs' : elliptic cone
'12v' : cone + half ellipsoid
'13hlsl' : gomphonemoid
'14hl' : prism on elliptic base/elliptic cylinder
'15hl' : half elliptic prism
'17fs' : triangular dypyramid
'ahx' : area x height

...

other parameters.

Details

These geometric models applied in this function are based and adapted from microalgae models developed by Hillebrand et al. (1999) - ('.hl'), Sun and Liu (2003) - ('.sl') and Vadrucci, Cabrini and Basset (2007) - ('.v'), plus other adapted models ('.fs'). The models can be a variable in data if specified as model.The size data parameters should follow the specified measures determined by each model, where $d_one$ is minor diameter, $d_two$ is major diameter and $h$ is height.

`'1hl'`	$V = (pi * (d_one^3))/6$
`'2sl'`	$V = (pi * (d_one^3))/12$
`'3hl'`	$V = (pi * h * (d_one^2))/6$
`'4hl'`	$V = (pi * h * (d_one^2))/12$
`'6fs'`	$V = (pi * hx * (d_one^2))/8$
	where $hx$ is a function of test height for trochamminids.
`'7fs'`	$V = (pi * h * (4 * (h^2) + 3 * (d_one^2)))/24$
`'8hl'`	$V = (pi * h * (d_one^2))/4$
`'10hl'`	$V = (pi * h * d_one * d_two)/6$
`'11fs'`	$V = (pi * h * d_one * d_two)/12$
`'12v'`	$V = (pi * h * d_one * d_two)/12$
`'13hlsl'`	$V = ((d_one * d_two)/4) * (d_one + ((pi/4) - 1) * d_two) * asin(h/(2*d_one))$
`'14hl'`	$V = (pi * h * d_one * d_two)/4$
`'15hl'`	$V = pi * h * d_one * d_two)/4$
`'17fs'`	$V = ((length * width)/2) * h)/3$

Value

A 'data.frame' or numeric object, consisting of calculated individual volume along with biovolume if the pco is informed.

Author(s)

Thaise R. Freitas [email protected]

References

Hillebrand, H., Dürselen, C.D., Kirschtel, D., Pollingher, U., & Zohary, T. (1999). Biovolume calculation for pelagic and benthic microalgae. Journal of Phycology, 35(2), 403–424. doi:10.1046/j.1529-8817.1999.3520403.x
Sun, J., & Liu, D. (2003). Geometric models for calculating cell biovolume and surface area for phytoplankton. Journal of Plankton Research, 25(11), 1331–1346. doi:10.1093/plankt/fbg096
Vadrucci, M. R., Cabrini, M., & Basset, A. (2007). Biovolume determination of phytoplankton guilds in transitional water ecosystems of Mediterranean Ecoregion. Transitional Waters Bulletin, 2, 83–102. doi:10.1285/i1825229Xv1n2p83

Examples

#Ammonia size data
data("ammonia")

#calculate test volume
volume.total(ammonia, model = "10hl")


#Ammonia size data
data("ammonia")

#calculate test volume
volume.total(ammonia, model = "10hl")

Package 'forImage'

Help Index

Ammonia size data

Description

Usage

Format

Amphistegina size data

Description

Usage

Format

Angulogerina size data

Description

Usage

Format

Asterotrochammina size data

Description

Usage

Format

Biovolume calculus

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Biomass estimative

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Bolivina size data

Description

Usage

Format

Cibicidoides size data

Description

Usage

Format

Foraminiferal genera data for forImage examples

Description

Format

Details

Import image object depth (Z)

Description

Usage

Arguments

Value

Examples

Discorbinella size data

Description

Usage

Format

Foraminiferal photomicrograph for forImage examples

Description

Format

Install python packages dependencies for measure function

Description

Usage

Arguments

Details

Value

Laevipeneroplis size data

Description

Usage

Format

Loxostomina size data

Description

Usage

Format

Foraminifera image measurement

Description

Usage

Arguments

Foraminiferal genera data for `forImage` examples

Foraminiferal photomicrograph for `forImage` examples