Skip to contents

acousticTS

CRAN Version GitHub Version DOI

Documentation R-CMD-check Codecov License: GPL-3

acousticTS estimates the acoustic target strength of aquatic organisms, calibration spheres, and other individual scatterers with physics-based models. It provides one interface for defining geometry and material properties, running compatible scattering models, and comparing results across frequency, orientation, and morphology.

Package workflow

The package separates geometry, physical interpretation, and model execution:

Build a shape, wrap it as a scatterer, and run a model

Shapes and scatterers are implemented as S4 objects. A Shape stores geometry. A Scatterer adds the physical properties, orientation, model inputs, and results needed for an acoustic calculation.

Installation

Install the latest version on CRAN:

install.packages("acousticTS")

Or install the latest developments from the current GitHub version:

install.packages("remotes")
remotes::install_github("brandynlucca/acousticTS")

Installation note: acousticTS contains C++17 and Fortran source code. Windows users need the version of Rtools matching their R installation. macOS users need the Xcode Command Line Tools and a compatible GNU Fortran compiler. Linux users need a C++17 compiler, make, and gfortran. See Troubleshooting if compilation fails.

Quick start

Build a shape, attach its acoustic properties, and run a model:

library(acousticTS)

# 1. Build a geometric Shape
krill_shape <- cylinder(
  length_body = 0.03,
  radius_body = 0.003
)

# 2. Wrap it as a fluid-like Scatterer
krill_target <- fls_generate(
  shape = krill_shape,
  g_body = 1.0357,
  h_body = 1.0279,
  theta_body = pi / 2
)

# 3. Calculate and plot target strength
krill_target <- target_strength(
  object = krill_target,
  frequency = seq(38e3, 120e3, by = 2e3),
  model = "dwba"
)

plot(krill_target, type = "model")

The result remains attached to krill_target, so the same object can be plotted, inspected with extract(), or reused in a simulation.

What is included

  • Constructors for canonical and arbitrary shapes, including spheres, spheroids, cylinders, and digitized body profiles.
  • S4 scatterer classes for fluid-like, gas-filled, elastic, composite, and calibration targets.
  • Exact, modal-series, T-matrix, weak-scattering, high-frequency, and composite model families.
  • Shape manipulation and reforge() workflows for resizing, resampling, bending, and repositioning targets.
  • Repeated parameter studies with simulate_ts().
  • Stored-state T-matrix tools for angular scattering, bistatic summaries, and orientation averages.
  • Validation registries, benchmark datasets, and documented implementation checks.

Use available_models() for the current model registry and accepted aliases.

Example data

The package includes ready-to-use biological targets and benchmark results:

data(krill, package = "acousticTS")
data(cod, package = "acousticTS")
data(sardine, package = "acousticTS")
data(benchmark_ts, package = "acousticTS")

plot(krill, type = "shape")

See Example Data for the contents and intended use of each object.

Documentation

The documentation explains package conventions, supported formulations, and validation scope. It complements the original scattering literature rather than replacing it.

Citation

To cite acousticTS, run:

citation("acousticTS")

The Zenodo concept DOI, which resolves to the latest archived release, is 10.5281/zenodo.7600659.

Contributing

Bug reports and feature requests are welcome through GitHub Issues. Please include a minimal reproducible example and sessionInfo() when reporting a problem.

acousticTS is licensed under GPL-3. Upstream code attribution and license notices are provided in inst/COPYRIGHTS.