Package 'acousticTS'

Description

Along-matrix summing function

Usage

along_sum(rpos, iterations)

Arguments

Value

A numeric matrix containing the adjacent column sums of rpos.

Examples

positions <- matrix(1:8, nrow = 2)
along_sum(positions, ncol(positions))

Description

Creates arbitrary body shape from user inputs

Usage

arbitrary(..., length_units = "m")

Arguments

Value

An Arbitrary shape object containing the padded position matrix and stored shape metadata.

See Also

Arbitrary

Examples

# Symmetric arbitrary shape using x/y/z + radius
arbitrary(
  x_body = c(0, 0.01), y_body = c(0, 0), z_body = c(0, 0),
  radius_body = c(0, 0.002)
)

# Dorsal/ventral style inputs
arbitrary(
  x_body = c(0, 0.015),
  w_body = c(0.005, 0.0075),
  zU_body = c(0.001, 0.002),
  zL_body = c(-0.001, -0.002)
)

Description

List available target-strength models

Usage

available_models()

Value

A data frame describing currently available built-in and user-registered target-strength models.

Examples

head(available_models())

Description

A S4 class that stores a fluid-like flesh component together with an explicit elastic backbone component for swimbladder-less fish applications where those two structures should remain separate. The body and backbone each retain their own geometry, orientations, and material properties. This class is intended to support composite flesh-plus-backbone model development and future extensions where additional internal structures may need to be carried alongside the body.

Value

An object of the BBF S4 class.

See Also

Scatterer, CSC

Examples

methods::getClass("BBF")

Description

Generate a BBF-class object.

Usage

bbf_generate(
  body_shape,
  backbone_shape,
  density_body = NULL,
  sound_speed_body = NULL,
  g_body = NULL,
  h_body = NULL,
  density_backbone,
  sound_speed_longitudinal_backbone,
  sound_speed_transversal_backbone,
  theta_body = pi/2,
  theta_backbone = pi/2,
  x_offset_backbone = 0,
  z_offset_backbone = 0,
  theta_units = "radians",
  length_units = "m",
  ID = NULL
)

Arguments

Details

bbf_generate() is intended for swimbladder-less fish workflows where the flesh and backbone should remain explicit, separately parameterized components. The body is stored using the same segmented-body representation used by FLS, while the backbone is stored as an explicit cylindrical component carrying elastic material properties for use by cylinder-based modal models.

Value

Generates a BBF-class object.

See Also

BBF, FLS, cylinder

Examples

body_shape <- arbitrary(
  x_body = c(0, 0.04, 0.08),
  zU_body = c(0.001, 0.004, 0.001),
  zL_body = c(-0.001, -0.004, -0.001)
)
backbone_shape <- cylinder(
  length_body = 0.06,
  radius_body = 0.0008,
  n_segments = 40
)
bbf_generate(
  body_shape = body_shape,
  backbone_shape = backbone_shape,
  density_body = 1070,
  sound_speed_body = 1570,
  density_backbone = 1900,
  sound_speed_longitudinal_backbone = 3500,
  sound_speed_transversal_backbone = 1700
)

Description

A packaged list of benchmark target-strength spectra for the canonical sphere, shell-sphere, finite-cylinder, and prolate-spheroid comparison cases used throughout the package validation workflow. The stored values follow the benchmark definitions assembled by Jech et al. (2015) and distributed in the echoSMs reference resources.

Usage

data(benchmark_ts)

Format

An object of class list of length 2.

Value

A list of benchmark target-strength spectra.

Source

echoSMs benchmark resources, especially the target-definition and Jech benchmark tables archived at https://github.com/ices-tools-dev/echoSMs.

References

Jech, J.M., Horne, J.K., Chu, D., Demer, D.A., Francis, D.T.I., Gorska, N., Jones, B., Lavery, A.C., Stanton, T.K., and Reeder, D.B. (2015). Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. The Journal of the Acoustical Society of America, 138, 3742-3764. doi:10.1121/1.4937607

Jech, M., and Macaulay, G. echoSMs: Acoustic backscattering models used in aquatic ecosystem research. GitHub repository: https://github.com/ices-tools-dev/echoSMs

Examples

data("benchmark_ts", package = "acousticTS")
str(benchmark_ts, max.level = 1)

Description

Apply a smooth curvature transformation to an existing scatterer body or to a list-like body component containing an rpos matrix. This is useful when a target should keep the same broad identity while adopting a curved centerline for model comparisons or sensitivity studies.

Usage

brake(object, radius_curvature, mode = "ratio")

Arguments

Value

A bent version of object, returned as the same broad object type with updated geometry and curvature metadata.

See Also

extract(), reforge(), translate_shape(), reanchor_shape(), inflate_shape(), smooth_shape(), resample_shape(), flip_shape(), offset_component()

Examples

shape_obj <- cylinder(
  length_body = 0.05,
  radius_body = 0.003,
  n_segments = 80
)
obj <- fls_generate(
  shape = shape_obj,
  density_body = 1045,
  sound_speed_body = 1520
)

bent_obj <- brake(obj, radius_curvature = 5)
head(extract(bent_obj, c("body", "rpos", "z")))
extract(bent_obj, c("shape_parameters", "radius_curvature_ratio"))

bent_body <- brake(
  extract(obj, "body"),
  radius_curvature = 0.35,
  mode = "measurement"
)
head(bent_body$rpos["z", ])

Description

Calculates the bulk modulus (K) from two of the three other elastic moduli: Young's modulus (E), shear modulus (G), or Poisson's ratio ($\nu$). Assumes 3D material properties.

The relationships used are:

$K = \frac{E G}{3(3G - E)}$

$K = \frac{2G(1 + \nu)}{3(1 - 2\nu)}$

$K = \frac{E}{3(1 - 2\nu)}$

Usage

bulk(E = NULL, G = NULL, nu = NULL)

Arguments

Value

Bulk modulus (K, Pa).

Examples

bulk(E = 3e9, G = 1.1e9)

Description

A S4 class that provides slots to contain relevant metadata for solid sphere objects belonging to the CAL-class scatterers. This object is created using parameters specific to the outer shell. The default behavior of this object is to only reference these outer elastic shell properties with few exceptions that are model-dependent. CAL inherits from the broader elastic-based ELA class rather than from ESS, because calibration targets are solid elastic bodies rather than elastic shells. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the CAL S4 class.

See Also

Scatterer

Examples

methods::getClass("CAL")

Description

Generate a CAL-class object.

Usage

cal_generate(
  material = "WC",
  diameter = 0.0381,
  sound_speed_longitudinal = NULL,
  sound_speed_transversal = NULL,
  density_sphere = NULL,
  theta_sphere = pi,
  ID = NULL,
  diameter_units = "m",
  theta_units = "radians",
  n_segments = 100
)

Arguments

Details

There are several options for the material argument:

Value

Generates a CAL-class object.

See Also

CAL

Examples

cal_generate(material = "WC", diameter = 38.1e-3, n_segments = 120)

Description

Build an explicit canonical surrogate shape from an existing Shape object. This is intended for workflows where a measured or segmented body should be approximated deliberately by one of the package's canonical geometries before being passed to a shape-specific model family such as SPHMS, PSMS, or FCMS.

Usage

canonicalize_shape(
  shape,
  to = c("ProlateSpheroid", "Cylinder", "Sphere", "OblateSpheroid"),
  method = c("auto", "volume", "length_volume", "profile_l2"),
  n_segments = NULL,
  diagnostics = FALSE
)

Arguments

Details

canonicalize_shape() is intentionally explicit. It does not run automatically inside model calls such as target_strength(..., model = "psms"), because there is no single defensible canonicalization rule for every biological or segmented target.

When the input shape contains both an explicit width profile and upper/lower height profiles, the canonicalization step first reduces those local cross-sections to an equal-area circular radius before fitting the canonical surrogate. That keeps the reduction axisymmetric while still honoring the original local cross-sectional area more closely than a height-only radius.

The returned diagnostics report how the source and target compare in length, enclosed volume, maximum equivalent radius, and equivalent-radius profile root-mean-square error on the source x-grid. Those diagnostics are the package's recommended way to judge whether a canonical surrogate is defensible for the intended model comparison.

Value

If diagnostics = FALSE, a canonical Shape object. If diagnostics = TRUE, a list with elements:

• shape: the fitted canonical Shape

• diagnostics: a named list of source, target, and fit metrics

See Also

create_shape(), arbitrary(), sphere(), cylinder(), prolate_spheroid(), oblate_spheroid()

Examples

bladder_like <- arbitrary(
  x_body = c(0, 0.01, 0.02, 0.03, 0.04),
  radius_body = c(0, 0.004, 0.006, 0.004, 0)
)

psms_shape <- canonicalize_shape(
  bladder_like,
  to = "ProlateSpheroid"
)

cyl_fit <- canonicalize_shape(
  bladder_like,
  to = "Cylinder",
  diagnostics = TRUE
)
cyl_fit$diagnostics$fit$radius_nrmse

Description

A pre-generated SBF scatterer containing all information required for target strength modeling. The packaged object corresponds to the historical Atlantic cod example used in the KRM literature and matches the Cod D case archived in the echoSMs KRM shape collection.

Usage

data(cod)

Format

A pre-generated SBF scatterer containing all information required for target strength modeling.

metadata

Relevant and identifying metadata (list).

model_parameters

Container for specified model parameters (list).

model

Model outputs and results (list).

body

List with:

• rpos: Position matrix (x, yw, zU, zL; m).

• sound_speed: Flesh sound speed ($c_{body}$, m/s).

• density: Flesh density ($\rho_{body}$, kg/m$^3$).

• theta: Orientation relative to transducer ($\theta_{body}$, radians).

bladder

List with:

• rpos: Position matrix (x, yw, zU, zL; m).

• sound_speed: Flesh sound speed ($c_{bladder}$, m/s).

• density: Flesh density ($\rho_{bladder}$, kg/m$^3$).

• theta: Orientation relative to transducer ($\theta_{bladder}$, radians).

shape_parameters

Named list with:

• body: List with length (m), ncyl (int), theta_units (str), length_units (str).

• bladder: List with length (m), ncyl (int), theta_units (str), length_units (str).

Value

A pre-generated SBF scatterer object.

Source

Historical KRM cod shape collection archived in echoSMs (https://github.com/ices-tools-dev/echoSMs) and associated with the Clay and Horne Atlantic cod example.

References

Clay, C.S., and Horne, J.K. (1994). Acoustic models of fish: The Atlantic cod (Gadus morhua). The Journal of the Acoustical Society of America, 96, 1661-1668. doi:10.1121/1.410245

Examples

data("cod", package = "acousticTS")
cod

Description

Calculates the compressibility contrast ($\kappa$) between a scattering interface and the surrounding medium. Compressibility is defined as:

$K = \frac{1}{\rho c^2}$

where $\rho$ is density ($kg~m^{-3}$) and $c$ is sound speed ($m~s^{-1}$).

The compressibility contrast is then:

$\kappa = \frac{K_2 - K_1}{K_1}$

where $K_1$ is the compressibility of the medium and $K_2$ is that of the target interface.

Usage

compressibility(medium, target)

Arguments

Value

Compressibility contrast ($\kappa$), dimensionless.

Examples

seawater <- data.frame(density = 1026, sound_speed = 1480)
animal <- data.frame(density = 1050, sound_speed = 1530)
compressibility(seawater, animal)

Description

A wrapper function that automatically creates generalized and/or canonical shapes for TS modeling.

Usage

create_shape(shape, ...)

Arguments

Details

The shape argument specifies what shape for the function to generate the desired shape for TS modeling. Options currently include:

Model Parameter Definitions

• length: the x-axis length of the shape.

• radius: the radius of the shape when applicable.

• length_radius_ratio: the length-to-radius ratio (L/A), which specifically refers to the radius at the mid-point of the cylinder and should be the maximum value. A typical L/A ratio in the literature is 16 for krill.

• taper: the taper order (n), which parameterizes the tapering function reported by Chu et al. (1993) to create a tapered cylinder. The tapering order will converge on a prolate and oblate spheroid when L > 2a and L < 2a, respectively, and n = 2. A typical taper order in the literature is 10.

• polynomial: the vector of arbitrary polynomial coefficients to generate a deformed cylinder as reported by Smith et al. (2013). Although listed as a mandatory argument for the polynomial cylinder function, it has a default setting that uses the sixth-degree polynomial coefficients reported by Smith et al. (2013).

Value

A Shape object.

Examples

create_shape("sphere", radius_body = 0.01)
create_shape(
  "prolate_spheroid",
  length_body = 0.04, radius_body = 0.004
)
create_shape(
  "oblate_spheroid",
  length_body = 0.012, radius_body = 0.01
)
create_shape(
  "cylinder",
  length_body = 0.05, radius_body = 0.003
)

Description

A shared parent S4 class for composite scatterers that retain a primary body component together with one or more additional anatomically distinct sub-components. The CSC-class is intended to provide modular scaffolding for multi-component biological targets, such as swimbladder-bearing fish and swimbladder-less fish represented as flesh plus backbone. It stores the primary body, a general component list, the shared model output slot, and shape metadata without implying any one specific resonant or elastic inclusion type.

Value

An object of the CSC S4 class.

See Also

Scatterer, SBF, BBF

Examples

methods::getClass("CSC")

Description

Creates a cylinder.

Usage

cylinder(length_body, radius_body = NULL, length_radius_ratio = NULL,
  taper = NULL, radius_curvature_ratio = NULL, n_segments = 100,
  length_units = "m")

Arguments

Value

Creates the position vector for a tapered or untapered cylinder.

See Also

Cylinder

Examples

cylinder(length_body = 0.05, radius_body = 0.003, n_segments = 80)

Description

Convert angular measurements from radians to degrees

Usage

degrees(x)

Arguments

Value

Angle in degrees

Examples

orientation <- pi / 2 # radians
degrees(orientation) # this should return a value equal to 90 degrees

Description

A shared parent S4 class for elastic-based scatterers. The ELA-class collects the slots common to solid elastic targets such as calibration spheres (CAL) and elastic-shelled targets (ESS), without implying a particular internal structure such as a shell or homogeneous elastic solid. See Scatterer for a more detailed description of the shared object organization.

Value

An object of the ELA S4 class.

See Also

Scatterer, CAL, ESS

Examples

methods::getClass("ELA")

Description

Generate a ELA-class object.

Usage

ela_generate(
  shape,
  density_body = NULL,
  sound_speed_longitudinal_body = NULL,
  sound_speed_transversal_body = NULL,
  theta_body = pi/2,
  ID = NULL,
  length_units = "m",
  theta_units = "radians"
)

Arguments

Details

ela_generate() builds a generic solid-elastic scatterer under the shared ELA class. Unlike CAL, it is not restricted to spheres, so it can carry prolate, oblate, cylindrical, or arbitrary elastic shapes together with the body density and longitudinal/transversal wave speeds used by solid-elastic models such as TMM.

Value

ELA-class object.

See Also

ELA, CAL, ESS

Examples

elastic_sphere <- sphere(radius_body = 0.01, n_segments = 40)
ela_generate(
  shape = elastic_sphere,
  density_body = 7800,
  sound_speed_longitudinal_body = 5900,
  sound_speed_transversal_body = 3200
)

Description

A S4 class that provides slots to contain relevant metadata for elastic shelled scatterers/objects belonging to the ESS-class. This object can be created using values for both an outer shell and internal tissues, if applicable. The default behavior for this type of this object is to only reference the outer shell with few exceptions that are model-dependent. ESS inherits from the broader elastic-based ELA class. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the ESS S4 class.

See Also

Scatterer

Examples

methods::getClass("ESS")

Description

Generate an ESS-class object

Usage

ess_generate(
  shape = NULL,
  x_body = NULL,
  y_body = NULL,
  z_body = NULL,
  radius_shell = NULL,
  shell_thickness = NULL,
  g_fluid = NULL,
  density_fluid = NULL,
  h_fluid = NULL,
  sound_speed_fluid = NULL,
  g_shell = NULL,
  density_shell = NULL,
  h_shell = NULL,
  sound_speed_shell = NULL,
  E = NULL,
  G = NULL,
  K = NULL,
  nu = NULL,
  theta_shell = pi/2,
  ID = NULL,
  theta_units = "radians",
  length_units = "m"
)

Arguments

Details

The preferred workflow is to build the shell geometry first as a Shape object and pass it through shape, or to supply explicit shell profile coordinates directly. Character-based shape dispatch remains available only as a compatibility pathway and is now deprecated. Material properties for both the shell and the inner fluid may be supplied either as contrasts or as absolute values, but each property pair must use only one representation.

Scatterer constructors store geometry in meters and orientations in radians. length_units and theta_units are retained as compatibility arguments, but non-SI values are normalized to the package-standard representation.

Value

ESS-class object

See Also

ESS

Examples

shell <- sphere(radius_body = 0.03, n_segments = 80)
ess_generate(
  shape = shell,
  shell_thickness = 0.001,
  density_shell = 1050,
  sound_speed_shell = 2350,
  density_fluid = 1030,
  sound_speed_fluid = 1500,
  E = 3.5e9,
  nu = 0.34
)

Description

Convenience accessor for reaching into Scatterer and Shape objects without spelling out direct slot access repeatedly. extract() can also walk through nested lists, matrices, and named vectors, which makes it useful for pulling model outputs, component properties, or position-matrix fields from a common interface. This is especially helpful after geometry manipulations such as brake() and reforge(), where inspecting the stored body profile is often the fastest way to confirm what changed.

Usage

extract(object, feature)

Arguments

Value

The extracted object, slot, list element, matrix row/column, or vector element identified by feature.

See Also

brake(), reforge(), translate_shape(), reanchor_shape(), inflate_shape(), smooth_shape(), resample_shape(), flip_shape(), offset_component()

Examples

obj <- fls_generate(
  shape = sphere(radius_body = 0.01, n_segments = 40),
  density_body = 1045,
  sound_speed_body = 1520
)

extract(obj, "body")
extract(obj, c("body", "density"))
extract(obj, c("shape_parameters", "shape"))

bent_obj <- brake(obj, radius_curvature = 5)
head(extract(bent_obj, c("body", "rpos", "z")))
extract(bent_obj, c("shape_parameters", "radius_curvature_ratio"))

Description

Reverse axial orientation (axis = "x") or mirror the geometry dorsoventrally (axis = "z") without manually editing the position matrix.

Usage

flip_shape(
  object,
  axis = c("x", "z"),
  component = NULL,
  containment = c("warn", "error", "ignore")
)

Arguments

Value

The modified object, returned as the same broad object type.

See Also

translate_shape(), reanchor_shape(), inflate_shape(), smooth_shape()

Examples

shape_obj <- arbitrary(
  x_body = c(0, 0.01, 0.02, 0.03),
  radius_body = c(0, 0.004, 0.002, 0)
)
flipped_shape <- flip_shape(shape_obj, axis = "x")
head(extract(flipped_shape, c("position_matrix", "zU")))

Description

A S4 class that provides slots to contain relevant metadata for scatterers similar to the surrounding fluid medium (i.e fluid-like) belonging to FLS-class scatterers. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the FLS S4 class.

See Also

Scatterer

Examples

methods::getClass("FLS")

Description

Generate a FLS-class object.

Usage

fls_generate(
  shape = NULL,
  x_body = NULL,
  y_body = NULL,
  z_body = NULL,
  length_body = NULL,
  radius_body = NULL,
  radius_curvature_ratio = NULL,
  n_segments = 18,
  g_body = NULL,
  h_body = NULL,
  density_body = NULL,
  sound_speed_body = NULL,
  theta_body = pi/2,
  ID = NULL,
  length_units = "m",
  theta_units = "radians",
  ...
)

Arguments

Details

The preferred workflow is to build a geometry first with sphere(), cylinder(), prolate_spheroid(), or arbitrary(), then pass that Shape object to fls_generate(). Material properties can be supplied either as contrasts (g_body/h_body) or as absolute density/sound-speed values (density_body/sound_speed_body), but not both for the same property pair. Downstream models derive contrasts automatically when only absolute values are supplied.

The only supported public geometry paths are now:

1. supply a pre-built Shape object, or

2. supply explicit profile coordinates directly to the constructor.

Character-based shape dispatch is retained only as a compatibility pathway and is now deprecated. Internally, every pathway is resolved to the same Shape-first geometry contract before the FLS object is built.

Scatterer constructors store geometry in meters and orientations in radians. length_units and theta_units are retained as compatibility arguments, but non-SI values are normalized to the package-standard representation.

Value

FLS-class object

See Also

FLS

Examples

shape <- prolate_spheroid(
  length_body = 0.04, radius_body = 0.004, n_segments = 50
)
fls_generate(
  shape = shape, density_body = 1045, sound_speed_body = 1520
)

Description

A S4 class that provides slots to contain relevant metadata for gas-bearing scatterers belonging to the GAS-class. This object can include simple gas-filled bubbles to other scatterers with gas occlusions, swimbladders, and other internal features, if applicable. The default behavior for this type of object is to only reference the gaseous/fluid feature with exceptions that are model-dependent. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the GAS S4 class.

See Also

Scatterer

Examples

methods::getClass("GAS")

Description

Generate a GAS-class object

Usage

gas_generate(shape = NULL, radius_body = NULL, h_fluid = 0.22,
  g_fluid = 0.0012, sound_speed_fluid = NULL, density_fluid = NULL,
  theta_body = pi/2, ID = NULL, radius_units = "m",
  theta_units = "radians", n_segments = 100, ...)

Arguments

Details

The preferred workflow is to supply a pre-built Shape object or explicit profile coordinates and then describe the internal gas by either contrasts (g_fluid, h_fluid) or absolute density/sound-speed values (density_fluid, sound_speed_fluid). Character-based shape dispatch remains available only as a compatibility pathway and is now deprecated.

Scatterer constructors store geometry in meters and orientations in radians. radius_units and theta_units are retained as compatibility arguments, but non-SI values are normalized to the package-standard representation.

Value

GAS-class object

See Also

GAS

Examples

shape_gas <- sphere(radius_body = 0.01, n_segments = 60)
gas_generate(shape = shape_gas, g_fluid = 0.0012, h_fluid = 0.22)

Description

Compute Gauss-Legendre quadrature nodes and weights on an interval $[a,~b]$.

Usage

gauss_legendre(n, a = -1, b = 1)

Arguments

Details

Gauss-Legendre quadrature provides exact integration for polynomials of degree up to $2n-1$ using n nodes and weights chosen as the roots of the Legendre polynomial $P_n(x)$ on the canonical interval $[-1,1]$. For a general interval $[a,b]$ the canonical nodes are shifted and rescaled onto $[a,b]$, and the weights are scaled by $(b-a)/2$.

This wrapper performs basic argument validation and calls the C++ routine to obtain nodes and weights with high accuracy for moderate n.

Value

A list with components:

nodes

Quadrature abscissae $x_i$ in $[a,~b]$.

weights

Quadrature weights $w_i$ such that $\int_a^b f(x)\,dx \approx \sum_{i=1}^n w_i\,f(x_i).$

References

Davis, P. J., & Rabinowitz, P. (2007). Methods of Numerical Integration (2nd ed.).

Examples

rule <- gauss_legendre(n = 4, a = 0, b = 1)
sum(rule$weights * rule$nodes^2)

Description

Computes the cylindrical Hankel function of the first kind ($H^{(1)}_\nu(z)$) and its derivatives through hcdk().

Usage

hc(l, n)

hcdk(l, n, k)

Arguments

Details

The Hankel function of the first kind is defined as:

$H^{(1)}_\nu(z) = J_\nu(z) + i Y_\nu(z)$

where $J_\nu(z)$ is the Bessel function of the first kind and $Y_\nu(z)$ is the Bessel function of the second kind.

Supported argument types: Since $H^{(1)}_\nu(z)$ is computed from $J_\nu(z)$ and $Y_\nu(z)$, the same restrictions apply:

• Purely real arguments ($z = x$): Fully supported.

• Purely imaginary arguments ($z = iy$): Supported.

• General complex arguments ($z = x + iy$): Not supported.

Derivatives:

• First derivative: $\frac{d}{dz}H^{(1)}_\nu(z) = \frac{\nu}{z} H^{(1)}_\nu(z) - H^{(1)}_{\nu+1}(z)$

• Second derivative: $\frac{d^2}{dz^2}H^{(1)}_\nu(z) = H^{(1)}_{\nu-2}(z) - \frac{2\nu-1}{z} H^{(1)}_{\nu-1}(z) + \frac{\nu^2+\nu}{z^2} H^{(1)}_\nu(z)$

• k-th derivative (DLMF 10.6.1): $\frac{d^k}{dz^k}H^{(1)}_\nu(z) = \frac{1}{2^k} \sum_{j=0}^{k} (-1)^j \binom{k}{j} H^{(1)}_{\nu-k+2j}(z)$

Value

A complex vector containing:

• hc: $H^{(1)}_\nu(z)$

• hcdk(..., k = 1): $\frac{d}{dz}H^{(1)}_\nu(z)$ (first derivative)

• hcdk(..., k = 2): $\frac{d^2}{dz^2}H^{(1)}_\nu(z)$ (second derivative)

• hcdk: $\frac{d^k}{dz^k}H^{(1)}_\nu(z)$ (k-th derivative)

References

Abramowitz, M. and Stegun, I.A. (Eds.). (1964). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. National Bureau of Standards, Applied Mathematics Series 55. Chapter 9.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

• Hankel function definition: https://dlmf.nist.gov/10.2

• k-th derivative formula: Eq. 10.6.1 at https://dlmf.nist.gov/10.6

See Also

jc for Bessel functions of the first kind, yc for Bessel functions of the second kind, hs for spherical Hankel functions.

Examples

# Hankel function
hc(0, 1)
hc(1, 2.5)

# Fractional order
hc(0.5, 3)

# Purely imaginary argument
hc(1, 1i)

# First derivative
hcdk(1, 2, 1)

# Second derivative
hcdk(1, 2, 2)

# k-th derivative
hcdk(1, 2, 3) # Third derivative

Description

Computes the spherical Hankel function of the first kind ($h^{(1)}_\nu(z)$) and its first-th derivative.

Usage

hs(l, n)

hsdk(l, n, k)

Arguments

Details

The spherical Hankel function of the first kind is defined as:

$h^{(1)}_\nu(z) = j_\nu(z) + i y_\nu(z)$

where $j_\nu(z)$ is the spherical Bessel function of the first kind and $y_\nu(z)$ is the spherical Bessel function of the second kind.

It is related to the cylindrical Hankel function by:

$h^{(1)}_\nu(z) = \sqrt{\frac{\pi}{2z}} H^{(1)}_{\nu+1/2}(z)$

The spherical Hankel functions are used extensively in scattering theory to represent outgoing spherical waves.

Derivative:

$\frac{d}{dz}h^{(1)}_\nu(z) = \frac{\nu}{z} h^{(1)}_\nu(z) - h^{(1)}_{\nu+1}(z)$

Value

A complex vector containing:

• hs: $h^{(1)}_\nu(z)$

• hsdK: $\frac{d}{dz^k}h^{(1)}_l(z)$ (k-th derivative)

References

Abramowitz, M. and Stegun, I.A. (Eds.). (1964). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. National Bureau of Standards, Applied Mathematics Series 55. Chapter 10.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

• Spherical Bessel functions: https://dlmf.nist.gov/10.47

• Relation to cylindrical Hankel functions: Eq. 10.47.5 at https://dlmf.nist.gov/10.47

See Also

hc for cylindrical Hankel functions, js for spherical Bessel functions of the first kind, ys for spherical Bessel functions of the second kind.

Examples

# Spherical Hankel function
hs(0, 1)
hs(1, 2.5)

# Fractional order
hs(0.5, 3)

# Vector input
hs(0, c(1, 2, 3))

# First derivative
hsdk(1, 2, 1)

Description

Apply a localized scaling window to a stored profile. Values of scale > 1 inflate the selected region, while scale < 1 pinch or taper it. For canonical Shape objects, the result is returned as an Arbitrary shape because the edited profile is no longer guaranteed to preserve the canonical class geometry.

Usage

inflate_shape(
  object,
  x_range = NULL,
  scale = 1,
  component = NULL,
  axis = c("radius", "width", "height"),
  profile = c("cosine", "linear", "box"),
  containment = c("warn", "error", "ignore")
)

Arguments

Value

The modified object. Shape inputs that are locally reshaped are returned as Arbitrary shapes.

See Also

smooth_shape(), resample_shape(), flip_shape(), brake(), reforge()

Examples

shape_obj <- cylinder(
  length_body = 0.05, radius_body = 0.003,
  n_segments = 80
)
pinched_shape <- inflate_shape(
  shape_obj,
  x_range = c(0.015, 0.035),
  scale = 0.7
)
max(extract(pinched_shape, c("shape_parameters", "max_radius")))

Description

Computes the cylindrical Bessel function of the first kind ($J_\nu(z)$) and its k-th derivatives.

Usage

jc(l, n)

jcdk(l, n, k)

Arguments

Details

The cylindrical Bessel function of the first kind satisfies Bessel's differential equation:

$z^2 \frac{d^2 J_\nu}{dz^2} + z \frac{dJ_\nu}{dz} + (z^2 - \nu^2) J _\nu = 0$

Supported argument types:

• Purely real arguments ($z = x$, where $x \in \mathbb{R}$): Fully supported for both positive and negative values.

• Purely imaginary arguments ($z = iy$, where $y \in \mathbb{R}$): Computed using the identity $J_\nu(iy) = e^{i\pi\nu/2} I_\nu(y)$ for $y > 0$, where $I_\nu$ is the modified Bessel function of the first kind. For negative imaginary arguments and real order, $J_\nu(-iy) = \overline{J_\nu(iy)}$.

• General complex arguments ($z = x + iy$, where $x \neq 0$ and $y \neq 0$): Not supported.

Special cases:

• $J_\nu(0) = 1$ if $\nu = 0$, otherwise $J_\nu(0) = 0$.

• For negative real arguments with integer order $n$: $J_n(-x) = (-1)^n J_n(x)$.

• For negative real arguments with non-integer order $\nu$: $J_\nu(-x) = e^{i\pi\nu} J_\nu(x)$ (complex result).

Derivatives:

• First derivative: $J'_\nu(z) = J_{\nu-1}(z) - \frac{\nu}{z} J_\nu(z)$

• Second derivative: $J''_\nu(z) = \frac{1}{4}\left[J_{\nu-2}(z) - 2J_\nu(z) + J_{\nu+2}(z)\right]$

• k-th derivative (DLMF 10.6.1):

  $\frac{d^k}{dz^k} J_\nu(z) = \frac{1}{2^k} \sum_{j=0}^{k} (-1)^j \binom{k}{j} J_{\nu - k + 2j}(z)$

Value

A complex vector containing:

• jc: $J_\nu(z)$

• jcdk(..., k = 1): $J'_\nu(z)$ (first derivative)

• jcdk(..., k = 2): $J''_\nu(z)$ (second derivative)

• jcdk: $J_\nu^{(k)}(z)$ (k-th derivative)

References

Abramowitz, M. and Stegun, I.A. (Eds.). (1964). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. National Bureau of Standards, Applied Mathematics Series 55. Chapter 9.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

• Bessel's equation: https://dlmf.nist.gov/10.2

• Negative argument identity ($J_\nu(-z)$): Eq. 10.4.1 at https://dlmf.nist.gov/10.4

• Imaginary argument identity ($J_\nu(iz)$): Eq. 10.27.6 at https://dlmf.nist.gov/10.27

See Also

yc for Bessel functions of the second kind, hc for Hankel functions (third kind), js for spherical Bessel functions of the first kind.

Examples

# Real argument, integer order
jc(0, 1)
jc(1, 2.5)

# Real argument, fractional order
jc(0.5, 3)

# Negative real argument (integer order gives real result)
jc(2, -1.5)

# Negative real argument (fractional order gives complex result)
jc(0.5, -2)

# Purely imaginary argument
jc(1, 1i)
jc(2, 3i)

# First derivative
jcdk(1, 2, 1)

# Second derivative
jcdk(1, 2, 2)

Description

Computes the spherical Bessel function of the first kind ($j_\nu(z)$) and its k-th derivative.

Usage

js(l, n)

jsdk(l, n, k)

Arguments

Details

The spherical Bessel function of the first kind is related to the cylindrical Bessel function by:

$j_\nu(z) = \sqrt{\frac{\pi}{2z}} J_{\nu+1/2}(z)$

where $J_\nu(z)$ is the cylindrical Bessel function of the first kind.

The spherical Bessel functions satisfy the differential equation:

$z^2 \frac{d^2 j_\nu}{dz^2} + 2z \frac{dj_\nu}{dz} + [z^2 - l(l+1)] j_\nu = 0$

Special cases:

• $j_\nu(0) = 0$ for all $\nu$.

• $j_0(z) = \frac{\sin(z)}{z}$

• $j_1(z) = \frac{\sin(z)}{z^2} - \frac{\cos(z)}{z}$

Derivatives:

• First derivative: $j'_\nu(z) = j_{\nu-1}(z) - \frac{\nu+1}{z} j_\nu(z)$

• Second derivative: $j''_\nu(z) = \frac{(\nu+1)(\nu+2) - z^2}{z^2} j_\nu(z) - \frac{2}{z} j_{\nu-1}(z)$

Value

A numeric vector or matrix (matching the input structure) containing:

• js: $j_\nu(z)$

• jsdk: $j^{(k)'}_l(z)$ (k-th derivative)

References

Abramowitz, M. and Stegun, I.A. (Eds.). (1964). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. National Bureau of Standards, Applied Mathematics Series 55. Chapter 10.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

• Spherical Bessel functions: https://dlmf.nist.gov/10.47

• Relation to cylindrical Bessel functions: Eq. 10.47.3 at https://dlmf.nist.gov/10.47

See Also

jc for cylindrical Bessel functions of the first kind, ys for spherical Bessel functions of the second kind, hs for spherical Hankel functions.

Examples

# Spherical Bessel function
js(0, 1)
js(1, 2.5)

# Fractional order
js(0.5, 3)

# Vector input
js(0, c(1, 2, 3))

# Matrix input (applied column-wise)
js(1, matrix(1:6, nrow = 2))

# First derivative
jsdk(1, 2, 1)

# Second derivative
jsdk(1, 2, 2)

Description

A dataset containing a sample krill (Euphausia superba) body shape proposed by McGehee et al. (1998).

Usage

data(krill)

Format

A pre-generated FLS scatterer containing all information required for target strength modeling.

metadata

Relevant and identifying metadata (list).

model_parameters

Container for specified model parameters (list).

model

Model outputs and results (list).

body

A list with elements:

• rpos: Position matrix (x, y, z; m).

• radius: Radius of each discrete cylinder (m).

• g: Body density contrast relative to medium.

• h: Sound speed contrast relative to medium.

• theta: Orientation angle ($\theta_{body}$, radians).

shape_parameters

A list with:

• length: Body length (m).

• ncyl: Number of cylinders.

• theta_units: Unit of orientation.

• length_units: Unit of length.

Value

A pre-generated FLS scatterer object.

Examples

data("krill", package = "acousticTS")
krill

Description

Calculates Lamé's first parameter ($\lambda$) from two of the four other elastic moduli: bulk modulus (K), Young's modulus (E), shear modulus (G), or Poisson's ratio ($\nu$). Assumes 3D material properties.

The relationships used are:

$\lambda = K - \frac{2G}{3}$

$\lambda = \frac{E\nu}{(1 + \nu)(1 - 2\nu)}$

$\lambda = \frac{2G\nu}{1 - 2\nu}$

$\lambda = \frac{3K\nu}{1 + \nu}$

$\lambda = \frac{3K(3K - E)}{9K - E}$

$\lambda = \frac{G(E - 2G)}{3G - E}$

Usage

lame(K = NULL, E = NULL, G = NULL, nu = NULL)

Arguments

Value

Lamé's first parameter ($\lambda$, Pa).

Examples

lame(K = 2.5e9, G = 1.1e9)

Description

The linear function converts a value from the logarithmic (dB) domain to the linear domain, while the db function converts a value from the linear domain to the logarithmic (dB) domain. These are commonly used for target strength (TS) and backscattering coefficient ($\sigma_{bs}$) conversions.

The conversions are defined as:

$\text{linear}(x) = c^{x / c}$

$\text{db}(x) = c \log_c(x)$

where $c$ is the coefficient (default 10).

Usage

linear(value, coefficient = 10)

db(value, coefficient = 10)

Arguments

Value

For linear, returns the value converted to the linear domain. For db, returns the value converted to the logarithmic (dB) domain.

Examples

sigma_bs <- linear(-40)
db(sigma_bs)

Description

The Neumann factor, denoted $\nu_{n}$, is a simple multiplicative constant commonly used in spherical or spheroidal function theory. It accounts for the symmetry of cosine terms or the duplication of even-order contributions in integrals.

Usage

neumann(x)

Arguments

Details

Formally, the Neumann factor is defined as:

$\eta_n = \begin{cases} 1, & n = 0, \\ 2, & n > 0. \end{cases}$

This factor frequently appears in the normalization of spherical Bessel functions, Legendre expansions, and spheroidal wave functions. It is not related to the "von Neumann ordinals" used in set theory.

Value

A numeric vector of the same length as x, containing values of $\eta_x$, each equal to 1 or 2.

Examples

neumann(0) # should return 1
neumann(1) # should return 2
neumann(2) # should return 2

# Vectorized use:
neumann(0:4)

Description

Creates an oblate spheroid.

Usage

oblate_spheroid(
  length_body = NULL,
  radius_body = NULL,
  length_radius_ratio = NULL,
  semimajor_length = NULL,
  semiminor_length = NULL,
  n_segments = 100,
  length_units = "m"
)

Arguments

Value

Creates the position vector for an oblate spheroid object of defined body-axis length and maximum equatorial radius.

See Also

OblateSpheroid

Examples

oblate_spheroid(
  length_body = 0.012, radius_body = 0.01, n_segments = 60
)
oblate_spheroid(
  semiminor_length = 0.006, semimajor_length = 0.01
)

Description

Translate an internal geometry-bearing component such as a swimbladder or backbone while leaving the outer body unchanged.

Usage

offset_component(
  object,
  component = c("bladder", "backbone"),
  x_offset = 0,
  z_offset = 0,
  containment = c("warn", "error", "ignore")
)

Arguments

Value

The modified scatterer object.

See Also

translate_shape(), reanchor_shape(), reforge()

Examples

fish <- sbf_generate(
  x_body = c(0, 0.1),
  w_body = c(0.006, 0.008),
  zU_body = c(0.001, 0.002),
  zL_body = c(-0.001, -0.002),
  x_bladder = c(0.02, 0.08),
  w_bladder = c(0, 0),
  zU_bladder = c(0.0012, 0.0012),
  zL_bladder = c(-0.0012, -0.0012),
  density_body = 1040,
  density_bladder = 1.2,
  sound_speed_body = 1500,
  sound_speed_bladder = 340
)
shifted_fish <- offset_component(
  fish,
  component = "bladder",
  x_offset = 0.003
)
min(extract(shifted_fish, c("bladder", "rpos", "x_bladder")))

Description

S3 plotting method for Scatterer objects. Depending on type, the method draws the target geometry, one or more stored model curves, or a stored single-target TMM scattering slice / map when the object was computed with retained T-matrix state.

Usage

## S3 method for class 'Scatterer'
plot(
  x,
  y = NULL,
  type = "shape",
  nudge_y = 1.1,
  nudge_x = 1.05,
  aspect_ratio = "manual",
  x_units = "frequency",
  y_units = "TS",
  ...
)

Arguments

Details

Plotting behavior is selected from the object's class. The supported type values therefore depend on what has been stored on the object. For example, type = "model" requires the object to already contain model output, and type = "scattering" currently applies only to stored TMM results.

Value

Called for its side effect of drawing a plot; returns the input invisibly.

See Also

extract(), target_strength(), tmm_scattering(), tmm_scattering_grid()

Examples

data("krill", package = "acousticTS")
plot(krill)

Description

Computes the Legendre polynomial of the first kind, $P_\nu(x)$, for real order $\nu$ (integer or fractional) and real argument $x$.

Usage

Pn(n, x)

Arguments

Details

The Legendre polynomial of the first kind satisfies the differential equation:

$(1 - x^2) \frac{d^2 P_\nu}{dx^2} - 2x \frac{dP_\nu}{dx} + \nu(\nu + 1) P_\nu = 0$

For integer order $n$, the function uses the recurrence relation:

$P_0(x) = 1$

$P_1(x) = x$

$P_n(x) = \frac{(2n-1) x P_{n-1}(x) - (n-1) P_{n-2}(x)}{n}$

For fractional order $\nu$, the function uses:

• For $|x| \leq 1$: The Ferrers function via the hypergeometric series $P_\nu(x) = {}_2F_1(-\nu, \nu+1; 1; \frac{1-x}{2})$

• For $|x| > 1$: A numerical contour integral representation

Value

A numeric matrix of dimension length(n) by length(x), where element [i, j] contains $P_{n_i}(x_j)$.

Note

This function calls underlying $C++$ code via Rcpp for computational efficiency and to support different cases for both order and argument that are not readily available in R.

References

Abramowitz, M. and Stegun, I. A. (1972). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. Dover Publications. Chapter 8: Legendre Functions.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/14

See Also

Pndk for the k^th derivative of the Legendre polynomial of the first kind, Qn for Legendre functions of the second kind.

Examples

# Single values
Pn(1, 1)

# Multiple orders, single argument
Pn(c(1, 2, 3), 1)

# Single order, multiple arguments
Pn(1, c(1, 2, 3))

# Multiple orders and arguments (returns a matrix)
Pn(c(1, 2, 3), c(1, 2, 3))

# Fractional orders
Pn(c(0.5, 2.2, 3), c(1, 2, 3))

# Negative arguments
Pn(c(0.5, 2, -3), c(1, -2.5, 3))

Description

Computes the $k$-th derivative of the Legendre polynomial of the first kind, $\frac{d^k}{dx^k} P_\nu(x)$, with respect to the argument $x$.

Usage

Pndk(n, x, k = 1L)

Arguments

Details

For integer order $n$:

The derivative is computed using the relationship with associated Legendre polynomials:

$\frac{d^m P_n(x)}{dx^m} = \frac{1}{(1-x^2)^{m/2}} P_n^m(x)$

where $P_n^m(x)$ is the associated Legendre polynomial (the Boost C++ uses Condon-Shortley phase convention).

At the endpoints $x = \pm 1$, the known closed-form expressions are used:

$P_n^{(k)}(1) = \frac{1}{2^k k!} \prod_{j=0}^{k-1} (n-j)(n+1+j)$

$P_n^{(k)}(-1) = (-1)^{n+k} P_n^{(k)}(1)$

If $k > n$ for integer $n$, the result is 0 (derivative of a polynomial of degree $n$ taken more than $n$ times).

For fractional order $\nu$:

Derivatives are computed using central finite differences:

$\frac{dP_\nu}{dx} \approx \frac{P_\nu(x+h) - P_\nu(x-h)}{2h}$

Higher-order derivatives use the generalized finite difference stencil. Note that accuracy may be limited for fractional orders due to the numerical integration underlying Pn.

Value

A numeric matrix of dimension length(n) by length(x), where element [i, j] contains $\frac{d^k}{dx^k} P_{n_i}(x_j)$.

Note

For fractional orders, the finite difference approximation may have reduced accuracy (typically 4-6 significant digits) compared to integer orders. A warning is issued for higher-order derivatives ($k > 1$) of fractional orders.

This function calls underlying $C++$ code via Rcpp for computational efficiency and to support different cases for both order and argument that are not readily available in R.

References

Abramowitz, M. and Stegun, I. A. (1972). Handbook of Mathematical Functions. Dover Publications. Section 8.5: Associated Legendre Functions.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/14.10

See Also

Pn for the Legendre polynomial of the first kind.

Examples

# First derivative of P_2(x) at x = 0.5
# P_2(x) = (3x^2 - 1)/2, so P'_2(x) = 3x, P'_2(0.5) = 1.5
Pndk(2, 0.5, 1)

# Second derivative of P_2(x)
# P''_2(x) = 3
Pndk(2, 0.5, 2)

# Multiple orders
Pndk(c(1, 2, 3), 0.5, 1)

# First derivative at multiple points
Pndk(2, c(-0.5, 0, 0.5), 1)

# Fractional order (uses finite differences)
Pndk(0.5, 0.5, 1)

# Derivative at endpoint
# P'_n(1) = n(n+1)/2
Pndk(3, 1, 1)  # Should be 3*4/2 = 6

Description

Calculates Poisson's ratio ($\nu$) from two of the three other elastic moduli: bulk modulus (K), Young's modulus (E), or shear modulus (G). Assumes 3D material properties.

The relationships used are:

$\nu = \frac{E}{2G} - 1$

$\nu = \frac{3K - 2G}{2(3K + G)}$

$\nu = \frac{3K - E}{6K}$

Usage

pois(K = NULL, E = NULL, G = NULL)

Arguments

Value

Poisson's ratio ($\nu$), dimensionless.

Examples

pois(E = 3e9, G = 1.1e9)

Description

Creates a polynomial deformed cylinder

Usage

polynomial_cylinder(
  length_body,
  radius_body,
  n_segments = 100,
  polynomial,
  length_units = "m"
)

Arguments

Value

Creates the position vector for a polynomial deformed cylinder.

References

Smith, J.N., Ressler, P.H., and Warren, J.D. 2013. A distorted wave Born approximation target strength model for Bering Sea euphausiids. ICES Journal of Marine Science, 70(1): 204-214. https://doi.org/10.1093/icesjms/fss140

See Also

PolynomialCylinder

Examples

# We can use the polynomial coefficients defined in Smith et al. (2013) to
# define the position vector of a sub-Arctic krill.
poly_vec <- c(0.83, 0.36, -2.10, -1.20, 0.63, 0.82, 0.64)
# Create the position vector
# This outputs a list containing "rpos" and "radius"
pos <- polynomial_cylinder(
  length_body = 15e-3, radius_body = 2e-3,
  polynomial = poly_vec
)
str(pos)

Description

Creates a prolate spheroid.

Usage

prolate_spheroid(
  length_body = NULL,
  radius_body = NULL,
  length_radius_ratio = NULL,
  semimajor_length = NULL,
  semiminor_length = NULL,
  n_segments = 100,
  length_units = "m"
)

Arguments

Value

Creates the position vector for a prolate spheroid object of defined semi-major and -minor axes.

See Also

ProlateSpheroid

Examples

prolate_spheroid(
  length_body = 0.04, radius_body = 0.004, n_segments = 60
)
prolate_spheroid(
  semimajor_length = 0.05, semiminor_length = 0.003
)

Description

Computes the Legendre function of the second kind, $Q_\nu(x)$, for real order $\nu$ (integer or fractional) and real argument $x$. Returns complex values when $|x| > 1$.