echosms 0.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. echosms-0.0.2/.gitignore +4 -0
  2. echosms-0.0.2/ExactSolutions/README.md +2 -0
  3. echosms-0.0.2/ExactSolutions/Sphere/Fluid/Anderson_fluid.py +134 -0
  4. echosms-0.0.2/ExactSolutions/Sphere/Fluid/Anderson_output.csv +96 -0
  5. echosms-0.0.2/ExactSolutions/Sphere/Fluid/README.md +6 -0
  6. echosms-0.0.2/ExactSolutions/Sphere/README.md +1 -0
  7. echosms-0.0.2/LICENSE +21 -0
  8. echosms-0.0.2/PKG-INFO +136 -0
  9. echosms-0.0.2/README.md +88 -0
  10. echosms-0.0.2/docs/api_reference.md +3 -0
  11. echosms-0.0.2/docs/benchmark_data.md +49 -0
  12. echosms-0.0.2/docs/contributing.md +37 -0
  13. echosms-0.0.2/docs/coordinate_system.jpg +0 -0
  14. echosms-0.0.2/docs/index.md +86 -0
  15. echosms-0.0.2/mkdocs.yml +20 -0
  16. echosms-0.0.2/pyproject.toml +43 -0
  17. echosms-0.0.2/src/echosms/__init__.py +8 -0
  18. echosms-0.0.2/src/echosms/benchmarkdata.py +40 -0
  19. echosms-0.0.2/src/echosms/mssmodel.py +240 -0
  20. echosms-0.0.2/src/echosms/psmsmodel.py +212 -0
  21. echosms-0.0.2/src/echosms/referencemodels.py +61 -0
  22. echosms-0.0.2/src/echosms/resources/BenchMark_Data/Benchmark_Angle_TS.csv +47 -0
  23. echosms-0.0.2/src/echosms/resources/BenchMark_Data/Benchmark_Frequency_TS.csv +196 -0
  24. echosms-0.0.2/src/echosms/resources/target definitions.toml +244 -0
  25. echosms-0.0.2/src/echosms/scattermodelbase.py +22 -0
  26. echosms-0.0.2/src/echosms/utils.py +82 -0
  27. echosms-0.0.2/src/example_code.py +126 -0
echosms-0.0.2/.gitignore ADDED
@@ -0,0 +1,4 @@
1
+ *.pyc
2
+ __pycache__/
3
+ /dist
4
+ /site
echosms-0.0.2/ExactSolutions/README.md ADDED
@@ -0,0 +1,2 @@
1
+ # Exact Solutions
2
+
echosms-0.0.2/ExactSolutions/Sphere/Fluid/Anderson_fluid.py ADDED
@@ -0,0 +1,134 @@
1
+ """Calculate backscatter by a fluid sphere using Anderson (1950).
2
+
3
+ JASA, 22: 426-431, https://doi.org/10.1121/1.1906621
4
+ """
5
+
6
+ import sys
7
+ from pathlib import Path
8
+ import numpy as np
9
+ from scipy.special import spherical_jn, spherical_yn
10
+ import matplotlib.pyplot as plt
11
+
12
+ ###
13
+ # physical parameters of the sphere and surrounding water
14
+ # from Jech et al. (2015)
15
+ # weakly-scattering sphere
16
+ # speed of sound in water (m/s)
17
+ c_water = 1477.4
18
+ # speed of sound in the sphere (m/s)
19
+ c_sphere = 1480.3
20
+
21
+ # radius of the sphere (m)
22
+ # from Jech et al. (2015)
23
+ a = 0.01
24
+
25
+ # from Jech et al. (2015)
26
+ # weakly-scattering sphere
27
+ # density of the water (kg/m^3)
28
+ rho_water = 1026.8
29
+ # density of the sphere (kg/m^3)
30
+ rho_sphere = 1028.9
31
+
32
+ # sound speed (h) and density (g) contrasts
33
+ g = rho_sphere/rho_water
34
+ h = c_sphere/c_water
35
+
36
+ ###
37
+ # model parameters
38
+ # minimum order, always = 0
39
+ order_min = 0
40
+ # maximum order
41
+ # the maximum order can be change to improve precision
42
+ order_max = 20
43
+ # number of orders
44
+ order_n = order_max+2
45
+ orders = range(order_min, order_n, 1)
46
+
47
+ # minimum acoustic frequency (Hz)
48
+ freq_min = 12000.0
49
+ # maximum acousic frequency (Hz)
50
+ freq_max = 200000.0
51
+ # frequency step (Hz)
52
+ freq_step = 2000.0
53
+ # the number of frequencies
54
+ freq_n = int((freq_max-freq_min)/freq_step)+1
55
+ # frequencies (Hz) at which to calculate scattering
56
+ freq_Hz = np.arange(freq_min, freq_max+freq_step, freq_step)
57
+
58
+ ###
59
+ # print the parameters and confirm calculations
60
+ print('water density: {}, sound-speed water: {}'.format(rho_water, c_water))
61
+ print('sphere density: {}, sound-speed sphere: {}'.format(rho_sphere, c_sphere))
62
+ print('g: {}, h: {}'.format(round(g, 3), round(h, 3)))
63
+ print('sphere radius: {}'.format(a))
64
+ print('ka range: {} to {}'.format(round(2*np.pi*freq_min*a/c_water, 3),
65
+ round(2*np.pi*freq_max*a/c_water, 3)))
66
+ answ = input('Continue? [y/n]')
67
+ if answ == 'n':
68
+ sys.exit()
69
+
70
+ ###
71
+ # set up output variables
72
+ # reflectivity coefficient
73
+ refl = []
74
+ # ka
75
+ ka = []
76
+
77
+ # real component
78
+ real = 0.0
79
+ # imaginary component
80
+ imag = 0.0
81
+ ###
82
+ # reflectivity coefficient
83
+ # Bessel functions from SciPy
84
+ # spherical Bessel function of the 2nd kind is the Neumann function
85
+ # Anderson uses Neumann function notation
86
+ for f in freq_Hz:
87
+ ka_sphere = (2*np.pi*f/c_sphere)*a
88
+ ka_water = (2*np.pi*f/c_water)*a
89
+ ka.append(ka_water)
90
+ for m in range(order_max):
91
+ sphjkas = (m/ka_sphere)*spherical_jn(m, ka_sphere)-spherical_jn(m+1, ka_sphere)
92
+ sphjkaw = (m/ka_water)*spherical_jn(m, ka_water)-spherical_jn(m+1, ka_water)
93
+ sphykas = (m/ka_sphere)*spherical_yn(m, ka_sphere)-spherical_yn(m+1, ka_sphere)
94
+ sphykaw = (m/ka_water)*spherical_yn(m, ka_water)-spherical_yn(m+1, ka_water)
95
+ alphaw = (2.*m+1.)*sphjkaw
96
+ alphas = (2.*m+1.)*sphjkas
97
+ beta = (2.*m+1)*sphykaw
98
+ numer = (alphas/alphaw)*(spherical_yn(m, ka_water)/spherical_jn(m, ka_sphere)) - \
99
+ ((beta/alphaw)*(g*h))
100
+ denom = (alphas/alphaw)*(spherical_jn(m, ka_water)/spherical_jn(m, ka_sphere))-(g*h)
101
+ cscat = numer/denom
102
+ real = real+((-1.)**m)*(2.*m+1)/(1.+cscat**2)
103
+ imag = imag+((-1.)**m)*(2.*m+1)*cscat/(1.+cscat**2)
104
+
105
+ refl.append((2/ka_water)*np.sqrt(real**2+imag**2))
106
+ imag = 0.0
107
+ real = 0.0
108
+
109
+ # convert to numpy arrays
110
+ refl = np.array(refl, dtype=float)
111
+ ka = np.array(ka, dtype=float)
112
+
113
+ # convert to target strength (TS dB re m^2)
114
+ # S is the cross-sectional area of the sphere
115
+ S = np.pi*a**2
116
+ # 4pi is for backscatter
117
+ TS = 10*np.log10(refl**2*S)-10*np.log10(4*np.pi)
118
+
119
+ ###
120
+ # plot reflectivity
121
+ # plt.plot(ka, refl)
122
+ # plt.plot(freq_Hz/1000., refl)
123
+ # plot TS
124
+ plt.plot(freq_Hz/1000., TS)
125
+ plt.show(block=False)
126
+
127
+ # write to a file
128
+ outfile = Path('./Anderson_output.csv')
129
+ with open(str(outfile), 'w', encoding='utf-8') as ofl:
130
+ hdr = 'f_kHz,R,TS\n'
131
+ ofl.write(hdr)
132
+ for i in range(freq_n):
133
+ ofl.write(','.join([str(round(freq_Hz[i]/1000, 1)),
134
+ str(round(refl[i], 9)), str(round(TS[i], 3))])+'\n')
echosms-0.0.2/ExactSolutions/Sphere/Fluid/Anderson_output.csv ADDED
@@ -0,0 +1,96 @@
1
+ f_kHz,TS,Benchmark,Bmk-TS
2
+ 12,-104.1,-103.95,0.150
3
+ 14,-101.762,-101.62,0.142
4
+ 16,-99.84,-99.69,0.150
5
+ 18,-98.25,-98.1,0.150
6
+ 20,-96.94,-96.79,0.150
7
+ 22,-95.869,-95.72,0.149
8
+ 24,-95.014,-94.87,0.144
9
+ 26,-94.355,-94.21,0.145
10
+ 28,-93.882,-93.74,0.142
11
+ 30,-93.588,-93.44,0.148
12
+ 32,-93.473,-93.33,0.143
13
+ 34,-93.541,-93.4,0.141
14
+ 36,-93.804,-93.66,0.144
15
+ 38,-94.279,-94.13,0.149
16
+ 40,-94.997,-94.85,0.147
17
+ 42,-96.008,-95.86,0.148
18
+ 44,-97.394,-97.25,0.144
19
+ 46,-99.305,-99.16,0.145
20
+ 48,-102.049,-101.91,0.139
21
+ 50,-106.433,-106.29,0.143
22
+ 52,-116.358,-116.22,0.138
23
+ 54,-115.009,-114.86,0.149
24
+ 56,-105.997,-105.85,0.147
25
+ 58,-101.808,-101.66,0.148
26
+ 60,-99.162,-99.02,0.142
27
+ 62,-97.32,-97.18,0.140
28
+ 64,-95.998,-95.85,0.148
29
+ 66,-95.056,-94.91,0.146
30
+ 68,-94.42,-94.28,0.140
31
+ 70,-94.049,-93.91,0.139
32
+ 72,-93.92,-93.78,0.140
33
+ 74,-94.029,-93.88,0.149
34
+ 76,-94.38,-94.24,0.140
35
+ 78,-94.997,-94.85,0.147
36
+ 80,-95.921,-95.78,0.141
37
+ 82,-97.227,-97.08,0.147
38
+ 84,-99.055,-98.91,0.145
39
+ 86,-101.692,-101.55,0.142
40
+ 88,-105.878,-105.73,0.148
41
+ 90,-114.918,-114.76,0.158
42
+ 92,-116.171,-116.04,0.131
43
+ 94,-106.28,-106.14,0.140
44
+ 96,-101.914,-101.77,0.144
45
+ 98,-99.195,-99.05,0.145
46
+ 100,-97.318,-97.18,0.138
47
+ 102,-95.979,-95.84,0.139
48
+ 104,-95.033,-94.89,0.143
49
+ 106,-94.402,-94.26,0.142
50
+ 108,-94.043,-93.9,0.143
51
+ 110,-93.936,-93.79,0.146
52
+ 112,-94.075,-93.93,0.145
53
+ 114,-94.468,-94.32,0.148
54
+ 116,-95.14,-94.99,0.150
55
+ 118,-96.141,-95.99,0.151
56
+ 120,-97.557,-97.41,0.147
57
+ 122,-99.556,-99.41,0.146
58
+ 124,-102.5,-102.35,0.150
59
+ 126,-107.415,-107.26,0.155
60
+ 128,-120.97,-120.79,0.180
61
+ 130,-112.031,-111.9,0.131
62
+ 132,-104.687,-104.55,0.137
63
+ 134,-100.921,-100.78,0.141
64
+ 136,-98.485,-98.34,0.145
65
+ 138,-96.785,-96.64,0.145
66
+ 140,-95.575,-95.43,0.145
67
+ 142,-94.735,-94.59,0.145
68
+ 144,-94.198,-94.05,0.148
69
+ 146,-93.93,-93.78,0.150
70
+ 148,-93.915,-93.77,0.145
71
+ 150,-94.151,-94,0.151
72
+ 152,-94.653,-94.51,0.143
73
+ 154,-95.455,-95.31,0.145
74
+ 156,-96.619,-96.47,0.149
75
+ 158,-98.259,-98.11,0.149
76
+ 160,-100.603,-100.46,0.143
77
+ 162,-104.19,-104.04,0.150
78
+ 164,-110.931,-110.79,0.141
79
+ 166,-124.601,-124.42,0.181
80
+ 168,-108.017,-107.87,0.147
81
+ 170,-102.79,-102.64,0.150
82
+ 172,-99.725,-99.58,0.145
83
+ 174,-97.659,-97.51,0.149
84
+ 176,-96.201,-96.05,0.151
85
+ 178,-95.172,-95.02,0.152
86
+ 180,-94.48,-94.33,0.150
87
+ 182,-94.075,-93.93,0.145
88
+ 184,-93.929,-93.78,0.149
89
+ 186,-94.035,-93.89,0.145
90
+ 188,-94.397,-94.25,0.147
91
+ 190,-95.038,-94.89,0.148
92
+ 192,-96.003,-95.86,0.143
93
+ 194,-97.374,-97.23,0.144
94
+ 196,-99.304,-99.16,0.144
95
+ 198,-102.121,-101.98,0.141
96
+ 200,-106.721,-106.59,0.131
echosms-0.0.2/ExactSolutions/Sphere/Fluid/README.md ADDED
@@ -0,0 +1,6 @@
1
+ # Fluid-Filled Spheres
2
+
3
+ # Fluid-filled sphere code
4
+ Anderson_fluid.py is Python code for calculating the acoustic backscatter and target strength using [Anderson's 1950 paper](https://doi.org/10.1121/1.1906621).
5
+
6
+
echosms-0.0.2/ExactSolutions/Sphere/README.md ADDED
@@ -0,0 +1 @@
1
+ # Spheres
echosms-0.0.2/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 ICES tools (development area)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
echosms-0.0.2/PKG-INFO ADDED
@@ -0,0 +1,136 @@
1
+ Metadata-Version: 2.3
2
+ Name: echosms
3
+ Version: 0.0.2
4
+ Summary: Acoustic backscattering models used in aquatic ecosystem research
5
+ Project-URL: Homepage, https://github.com/ices-tools-dev/echoSMs
6
+ Project-URL: Issues, https://github.com/ices-tools-dev/echoSMs/issues
7
+ Project-URL: Documentation, https://ices-tools-dev.github.io/echoSMs
8
+ Project-URL: Repository, https://github.com/ices-tools-dev/echoSMs
9
+ Project-URL: Discussions, https://github.com/ices-tools-dev/echoSMs/discussions
10
+ Author: Mike Jech, Gavin Macaulay
11
+ License: MIT License
12
+
13
+ Copyright (c) 2024 ICES tools (development area)
14
+
15
+ Permission is hereby granted, free of charge, to any person obtaining a copy
16
+ of this software and associated documentation files (the "Software"), to deal
17
+ in the Software without restriction, including without limitation the rights
18
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
19
+ copies of the Software, and to permit persons to whom the Software is
20
+ furnished to do so, subject to the following conditions:
21
+
22
+ The above copyright notice and this permission notice shall be included in all
23
+ copies or substantial portions of the Software.
24
+
25
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
26
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
27
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
28
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
29
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
30
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
31
+ SOFTWARE.
32
+ License-File: LICENSE
33
+ Keywords: acoustic,backscatter,model
34
+ Classifier: Development Status :: 3 - Alpha
35
+ Classifier: Intended Audience :: Science/Research
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Operating System :: OS Independent
38
+ Classifier: Programming Language :: Python :: 3
39
+ Classifier: Topic :: Scientific/Engineering
40
+ Requires-Python: >=3.10
41
+ Requires-Dist: matplotlib
42
+ Requires-Dist: mkdocstrings[python]
43
+ Requires-Dist: numpy
44
+ Requires-Dist: pandas
45
+ Requires-Dist: scipy
46
+ Requires-Dist: xarray
47
+ Description-Content-Type: text/markdown
48
+
49
+ # echoSMs
50
+ Making acoustic scattering models available to fisheries and plankton scientists via the world wide web.
51
+
52
+ Full documentation is available [here]( https://ices-tools-dev.github.io/echoSMs/).
53
+
54
+ # Background
55
+ This project is an international collaboration that is, in part, a component of a U.S. NOAA-Fisheries active acoustic strategic initiative [AA-SI](https://github.com/nmfs-fish-tools/AA-SI/tree/main).
56
+
57
+ Quantitative interpretation of acoustic echograms require software expertise to develop advanced analytical methods for echo classification using mathematical models that predict acoustic backscatter (e.g., target strength, TS, dB re m<sup>2</sup>). These models and predictions can be used to inform echo classification by validating empirical measurements and generating training data for machine learning (ML), artificial intelligence (AI), and other advanced analytical methods, such as inverse methods. Application of these models to fish and plankton requires anatomical and morphological data that are easily accessible and available to the models.
58
+
59
+ The goal of this project is to make acoustic scattering models available to fisheries and plankton acoustic scientists via the world wide web. By providing the models in an open-access and open-source software language (e.g, Python, R) and providing morphological and anatomical data in open data formats (e.g., HDF5, relational database), the proper and appropriate use of these models can extend to the entire fisheries and plankton acoustics’ community.
60
+
61
+ # Scattering Models
62
+ The initial set of acoustic scattering models will be those used by [Jech et al. (2015)](https://doi.org/10.1121/1.4937607) (Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. JASA. 138(6): 3742-3764). Acoustic model coding will follow 3 - 4 phases, where the first phase will focus on exact solutions and canonical shapes (Table 1), the second phase will focus on approximate analytical models applied to canonical shapes (Table 2), the third phase will focus on approximate analytical models applied to complex shapes approximating biological targets such as fish and zooplankton, and the fourth phase (if funding and time allows) will focus on numerical models applied to canonical shapes and biological targets.
63
+
64
+ # Exact Solutions
65
+ | Model | Shape | Description | References |
66
+ |-----------------------------------|--------|-------------|------------|
67
+ | Modal Series<br> solution (MSS) | Sphere | Fluid | 1,2 |
68
+ | | | Fixed-rigid | 2,3 |
69
+ | | | Pressure-release | 2 |
70
+ | | | Fluid-filled | 1,2 |
71
+ | | | Gas-filled | 2 |
72
+ | | | Weakly-scattering | 2 |
73
+ | | | Spherical fluid shell with<br> fluid interior | 2 |
74
+ | | | Fixed-rigid spherical shell | 2 |
75
+ | | | Spherical fluid shell with<br> pressure-release interior | 2 |
76
+ | | | Spherical fluid shell with<br> gas interior | 2 |
77
+ | | | Spherical fluid shell with<br> weakly-scattering interior | 2 |
78
+ | Prolate spheroid<br> modal series<br> solution | Prolate spheroid | Rigid-fixed | 2,4,5 |
79
+ | | | Pressure-release | 2,4,5 |
80
+ | | | Gas-filled | 2,4,5 |
81
+ | Infinite cylinder? | | | 3 |
82
+ | Infinite plane? | | | |
83
+ 1. [Anderson, V. C. 1950. Sound scattering from a fluid sphere. JASA. 22(4): 426-431](https://doi.org/10.1121/1.1906621)
84
+ 2. [Jech et al. 2015. Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. JASA. 138: 3742-3764](https://doi.org/10.1121/1.4937607)
85
+ 3. [Faran, J. J. 1951. Sound scattering by solid cylinders and spheres. JASA. 23(4): 405-418.](https://doi.org/10.1121/1.1906621)
86
+ 4. Skudrzyk. 1971. The Foundations of Acoustics (Springer, NY), pp. 455-465.
87
+ 5. Furusawa. 1988. Prolate spheroidal models for predicting general trends of fish target strength,” J. Acoust. Soc. Jpn. (E) 9, 13–14.
88
+
89
+
90
+ # Approximate Analytical Models and Shapes
91
+ | Model | Shape | Description | References |
92
+ |-----------------------------------|--------|-------------|------------|
93
+ | Modal Series-based<br> deformed cylinder<br> model | Finite cylinder | Fixed rigid | 1,2,3 |
94
+ | | | Pressure-release | 1,2,3 |
95
+ | | | Gas-filled | 1,2,3 |
96
+ | | | Weakly-scattering | 1,2,3 |
97
+ | | Prolate spheroid | Fixed rigid | 1,2,3 |
98
+ | | | Pressure-release | 1,2,3 |
99
+ | | | Gas-filled | 1,2,3 |
100
+ | | | Weakly-scattering | 1,2,3 |
101
+ | Kirchhoff<br> approximation (KA) | Sphere | Fixed rigid | 3,4,5 |
102
+ | | Prolate spheroid | Fixed rigid | 3,4,5 |
103
+ | | Finite cylinder | Fixed rigid | 3,4,5 |
104
+ | Kirchhoff ray mode<br> (KRM) | Sphere | Gas filled | 3,6,7,8 |
105
+ | | | Weakly scattering | 3,6,7,8 |
106
+ | | Spherical shell | gas filled | 3,6,7,8 |
107
+ | | | Weakly scattering | 3,6,7,8 |
108
+ | | Prolate spheroid | gas filled | 3,6,7,8 |
109
+ | | | Weakly scattering | 3,6,7,8 |
110
+ | | Finite cylinder | gas filled | 3,6,7,8 |
111
+ | | | Weakly scattering | 3,6,7,8 |
112
+ | Distorted wave Born<br> approximation (DWBA) | Sphere | Weakly scattering | 3,9,10,11 |
113
+ | | Prolate spheroid | Weakly scattering | 3,9,10,11 |
114
+ | | Finite cylinder | Weakly scattering | 3,9,10,11 |
115
+ | Phase-tracking<br> distorted wave Born<br> approximation<br> (PT-DWBA) | Sphere | Weakly scattering | 3,12 |
116
+ | | Spherical shell | Weakly scattering | 3,12 |
117
+ | | Prolate spheroid | Weakly scattering | 3,12 |
118
+ | | Finite cylinder | Weakly scattering | 3,12 |
119
+ | Stochastic distorted<br> wave Born<br> approximation<br> (SDWBA) | Sphere | Weakly scattering | 13,14,15 |
120
+ | | Prolate spheroid | Weakly scattering | 13,14,15 |
121
+ | | Finite cylinder | Weakly scattering | 13,14,15 |
122
+
123
+ 1. [Stanton. 1988. Sound scattering by cylinders of finite length. I. Fluid cylinders. JASA. 83, 55–63.](https://doi.org/10.1121/1.396184)
124
+ 2. [Stanton. 1989. Sound scattering by cylinders of finite length. III. Deformed cylinders. JASA. 86: 691-705](https://doi.org/10.1121/1.398193)
125
+ 3. [Jech et al. 2015. Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. JASA. 138: 3742-3764.](https://doi.org/10.1121/1.4937607)
126
+ 4. [Foote. 1985. Rather-high-frequency sound scattering by swimbladdered fish. JASA. 78: 688-700](https://doi.org/10.1121/1.392438)
127
+ 5. [Foote and Francis. 2002. Comparing Kirchhoff approximation and boundary-element models for computing gadoid target strengths. JASA. 111: 1644-1654.](https://doi.org/10.1121/1.1458939)
128
+ 6. [Clay and Horne. 1994. Acoustic models of fish: The Atlantic cod (Gadus morhua). JASA. 96: 1661-1668.](https://doi.org/10.1121/1.404903)
129
+ 7. [Clay. 1991. Low-resolution acoustic scattering models: Fluid-filled cylinders and fish with swim bladders. JASA. 89: 2168-2179.](https://doi.org/10.1121/1.400910)
130
+ 8. [Clay. 1992. Composite ray-mode approximations for backscattered sound from gas-filled cylinders and swimbladders. JASA. 92: 2173-2180.](https://doi.org/10.1121/1.405211)
131
+ 9. [Chu et al. 1993. Further analysis of target strength measurements of Antarctic krill at 38 and 120 kHz: Comparison with deformed cylinder model and inference of orientation distribution. JASA. 93: 2985-2988.](https://doi.org/10.1121/1.405818)
132
+ 10. [Stanton et al. 1993. Average echoes from randomly oriented random-length finite cylinders: Zooplankton models. JASA. 94: 3463-3472.](https://doi.org/10.1121/1.407200)
133
+ 11. [Stanton et al. 1998. Sound scattering by several zooplankton groups II: Scattering models. JASA. 103: 236-253.](https://doi.org/10.1121/1.421110)
134
+ 12. [Jones et al. 2009. Use of the distorted wave Born approximation to predict scattering by inhomogeneous objects: Application to squid. JASA. 125: 73-88.](https://doi.org/10.1121/1.3021298)
135
+ 13. [Demer and Conti. 2003. Reconciling theoretical versus empirical target strengths of krill: Effects of phase variability on the distorted wave Born approximation. ICES J. Mar. Sci. 60: 429-434.](https://doi.org/10.1016/S1054–3139(03)00002-X)
136
+ 14. [Demer and Conti. 2004. Erratum: Reconciling theoretical versus empirical target strengths of krill; effects of phase variability on the distorted-wave, Born approximation. ICES J. Mar. Sci. 61: 157-158.](https://doi.org/10.1016/j.icesjms.2003.12.003)
echosms-0.0.2/README.md ADDED
@@ -0,0 +1,88 @@
1
+ # echoSMs
2
+ Making acoustic scattering models available to fisheries and plankton scientists via the world wide web.
3
+
4
+ Full documentation is available [here]( https://ices-tools-dev.github.io/echoSMs/).
5
+
6
+ # Background
7
+ This project is an international collaboration that is, in part, a component of a U.S. NOAA-Fisheries active acoustic strategic initiative [AA-SI](https://github.com/nmfs-fish-tools/AA-SI/tree/main).
8
+
9
+ Quantitative interpretation of acoustic echograms require software expertise to develop advanced analytical methods for echo classification using mathematical models that predict acoustic backscatter (e.g., target strength, TS, dB re m<sup>2</sup>). These models and predictions can be used to inform echo classification by validating empirical measurements and generating training data for machine learning (ML), artificial intelligence (AI), and other advanced analytical methods, such as inverse methods. Application of these models to fish and plankton requires anatomical and morphological data that are easily accessible and available to the models.
10
+
11
+ The goal of this project is to make acoustic scattering models available to fisheries and plankton acoustic scientists via the world wide web. By providing the models in an open-access and open-source software language (e.g, Python, R) and providing morphological and anatomical data in open data formats (e.g., HDF5, relational database), the proper and appropriate use of these models can extend to the entire fisheries and plankton acoustics’ community.
12
+
13
+ # Scattering Models
14
+ The initial set of acoustic scattering models will be those used by [Jech et al. (2015)](https://doi.org/10.1121/1.4937607) (Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. JASA. 138(6): 3742-3764). Acoustic model coding will follow 3 - 4 phases, where the first phase will focus on exact solutions and canonical shapes (Table 1), the second phase will focus on approximate analytical models applied to canonical shapes (Table 2), the third phase will focus on approximate analytical models applied to complex shapes approximating biological targets such as fish and zooplankton, and the fourth phase (if funding and time allows) will focus on numerical models applied to canonical shapes and biological targets.
15
+
16
+ # Exact Solutions
17
+ | Model | Shape | Description | References |
18
+ |-----------------------------------|--------|-------------|------------|
19
+ | Modal Series<br> solution (MSS) | Sphere | Fluid | 1,2 |
20
+ | | | Fixed-rigid | 2,3 |
21
+ | | | Pressure-release | 2 |
22
+ | | | Fluid-filled | 1,2 |
23
+ | | | Gas-filled | 2 |
24
+ | | | Weakly-scattering | 2 |
25
+ | | | Spherical fluid shell with<br> fluid interior | 2 |
26
+ | | | Fixed-rigid spherical shell | 2 |
27
+ | | | Spherical fluid shell with<br> pressure-release interior | 2 |
28
+ | | | Spherical fluid shell with<br> gas interior | 2 |
29
+ | | | Spherical fluid shell with<br> weakly-scattering interior | 2 |
30
+ | Prolate spheroid<br> modal series<br> solution | Prolate spheroid | Rigid-fixed | 2,4,5 |
31
+ | | | Pressure-release | 2,4,5 |
32
+ | | | Gas-filled | 2,4,5 |
33
+ | Infinite cylinder? | | | 3 |
34
+ | Infinite plane? | | | |
35
+ 1. [Anderson, V. C. 1950. Sound scattering from a fluid sphere. JASA. 22(4): 426-431](https://doi.org/10.1121/1.1906621)
36
+ 2. [Jech et al. 2015. Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. JASA. 138: 3742-3764](https://doi.org/10.1121/1.4937607)
37
+ 3. [Faran, J. J. 1951. Sound scattering by solid cylinders and spheres. JASA. 23(4): 405-418.](https://doi.org/10.1121/1.1906621)
38
+ 4. Skudrzyk. 1971. The Foundations of Acoustics (Springer, NY), pp. 455-465.
39
+ 5. Furusawa. 1988. Prolate spheroidal models for predicting general trends of fish target strength,” J. Acoust. Soc. Jpn. (E) 9, 13–14.
40
+
41
+
42
+ # Approximate Analytical Models and Shapes
43
+ | Model | Shape | Description | References |
44
+ |-----------------------------------|--------|-------------|------------|
45
+ | Modal Series-based<br> deformed cylinder<br> model | Finite cylinder | Fixed rigid | 1,2,3 |
46
+ | | | Pressure-release | 1,2,3 |
47
+ | | | Gas-filled | 1,2,3 |
48
+ | | | Weakly-scattering | 1,2,3 |
49
+ | | Prolate spheroid | Fixed rigid | 1,2,3 |
50
+ | | | Pressure-release | 1,2,3 |
51
+ | | | Gas-filled | 1,2,3 |
52
+ | | | Weakly-scattering | 1,2,3 |
53
+ | Kirchhoff<br> approximation (KA) | Sphere | Fixed rigid | 3,4,5 |
54
+ | | Prolate spheroid | Fixed rigid | 3,4,5 |
55
+ | | Finite cylinder | Fixed rigid | 3,4,5 |
56
+ | Kirchhoff ray mode<br> (KRM) | Sphere | Gas filled | 3,6,7,8 |
57
+ | | | Weakly scattering | 3,6,7,8 |
58
+ | | Spherical shell | gas filled | 3,6,7,8 |
59
+ | | | Weakly scattering | 3,6,7,8 |
60
+ | | Prolate spheroid | gas filled | 3,6,7,8 |
61
+ | | | Weakly scattering | 3,6,7,8 |
62
+ | | Finite cylinder | gas filled | 3,6,7,8 |
63
+ | | | Weakly scattering | 3,6,7,8 |
64
+ | Distorted wave Born<br> approximation (DWBA) | Sphere | Weakly scattering | 3,9,10,11 |
65
+ | | Prolate spheroid | Weakly scattering | 3,9,10,11 |
66
+ | | Finite cylinder | Weakly scattering | 3,9,10,11 |
67
+ | Phase-tracking<br> distorted wave Born<br> approximation<br> (PT-DWBA) | Sphere | Weakly scattering | 3,12 |
68
+ | | Spherical shell | Weakly scattering | 3,12 |
69
+ | | Prolate spheroid | Weakly scattering | 3,12 |
70
+ | | Finite cylinder | Weakly scattering | 3,12 |
71
+ | Stochastic distorted<br> wave Born<br> approximation<br> (SDWBA) | Sphere | Weakly scattering | 13,14,15 |
72
+ | | Prolate spheroid | Weakly scattering | 13,14,15 |
73
+ | | Finite cylinder | Weakly scattering | 13,14,15 |
74
+
75
+ 1. [Stanton. 1988. Sound scattering by cylinders of finite length. I. Fluid cylinders. JASA. 83, 55–63.](https://doi.org/10.1121/1.396184)
76
+ 2. [Stanton. 1989. Sound scattering by cylinders of finite length. III. Deformed cylinders. JASA. 86: 691-705](https://doi.org/10.1121/1.398193)
77
+ 3. [Jech et al. 2015. Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. JASA. 138: 3742-3764.](https://doi.org/10.1121/1.4937607)
78
+ 4. [Foote. 1985. Rather-high-frequency sound scattering by swimbladdered fish. JASA. 78: 688-700](https://doi.org/10.1121/1.392438)
79
+ 5. [Foote and Francis. 2002. Comparing Kirchhoff approximation and boundary-element models for computing gadoid target strengths. JASA. 111: 1644-1654.](https://doi.org/10.1121/1.1458939)
80
+ 6. [Clay and Horne. 1994. Acoustic models of fish: The Atlantic cod (Gadus morhua). JASA. 96: 1661-1668.](https://doi.org/10.1121/1.404903)
81
+ 7. [Clay. 1991. Low-resolution acoustic scattering models: Fluid-filled cylinders and fish with swim bladders. JASA. 89: 2168-2179.](https://doi.org/10.1121/1.400910)
82
+ 8. [Clay. 1992. Composite ray-mode approximations for backscattered sound from gas-filled cylinders and swimbladders. JASA. 92: 2173-2180.](https://doi.org/10.1121/1.405211)
83
+ 9. [Chu et al. 1993. Further analysis of target strength measurements of Antarctic krill at 38 and 120 kHz: Comparison with deformed cylinder model and inference of orientation distribution. JASA. 93: 2985-2988.](https://doi.org/10.1121/1.405818)
84
+ 10. [Stanton et al. 1993. Average echoes from randomly oriented random-length finite cylinders: Zooplankton models. JASA. 94: 3463-3472.](https://doi.org/10.1121/1.407200)
85
+ 11. [Stanton et al. 1998. Sound scattering by several zooplankton groups II: Scattering models. JASA. 103: 236-253.](https://doi.org/10.1121/1.421110)
86
+ 12. [Jones et al. 2009. Use of the distorted wave Born approximation to predict scattering by inhomogeneous objects: Application to squid. JASA. 125: 73-88.](https://doi.org/10.1121/1.3021298)
87
+ 13. [Demer and Conti. 2003. Reconciling theoretical versus empirical target strengths of krill: Effects of phase variability on the distorted wave Born approximation. ICES J. Mar. Sci. 60: 429-434.](https://doi.org/10.1016/S1054–3139(03)00002-X)
88
+ 14. [Demer and Conti. 2004. Erratum: Reconciling theoretical versus empirical target strengths of krill; effects of phase variability on the distorted-wave, Born approximation. ICES J. Mar. Sci. 61: 157-158.](https://doi.org/10.1016/j.icesjms.2003.12.003)
echosms-0.0.2/docs/api_reference.md ADDED
@@ -0,0 +1,3 @@
1
+ # API reference
2
+
3
+ ::: echosms
echosms-0.0.2/docs/benchmark_data.md ADDED
@@ -0,0 +1,49 @@
1
+ # Benchmark Data
2
+ Benchmark data for the acoustic scattering models in [Jech et al., 2015](https://doi.org/10.1121/1.4937607).
3
+
4
+ ## Benchmark TS(f)
5
+ Benchmark target strength (TS, db re m<sup>2</sup>) as a function of acoustic frequency. The data file [Benchmark_Frequency_TS.csv](https://github.com/ices-tools-dev/echoSMs/blob/main/BenchMark_Data/Benchmark_Frequency_TS.csv) is a text file with comma-separated variable format (.csv). TS values are given to 2-decimal-place precision (i.e., 0.01 dB)
6
+
7
+ The column names and descriptions are:
8
+
9
+ | Column Name/Variable | Description |
10
+ |----------------------|-------------|
11
+ | Frequency_kHz | acoustic frequency in kiloHertz. TS values are given at 2-kHz increments from 12 to 400 kHz. |
12
+ | Sphere_Rigid | Benchmark values for the rigid sphere. |
13
+ | Sphere_PressureRelease | Benchmark values for the pressure-release sphere. |
14
+ | Sphere_Gas | Benchmark values for the gas-filled sphere. |
15
+ | Sphere_WeaklyScattering | Benchmark values for the weakly-scattering sphere. |
16
+ | ShellSphere_PressureRelease | Benchmark values for the pressure-release shelled sphere. |
17
+ | ShellSphere_Gas | Benchmark values for the gas-filled shelled sphere. |
18
+ | ShellSphere_WeaklyScattering | Benchmark values for the weakly-scattering shelled sphere. |
19
+ | ProlateSpheroid_Rigid | Benchmark values for the rigid prolate spheroid. Valid TS values were computed for 12-80 kHz. NA represents TS values that were not computed. |
20
+ | ProlateSpheroid_PressureRelease | Benchmark values for the pressure-release prolate spheroid. Valid TS values were computed for 12-80 kHz. NA represents TS values that were not computed. |
21
+ | ProlateSpheroid_Gas | Benchmark values for the gas-filled prolate spheroid. No benchmark TS values were computed. NA represents TS values that were not computed. |
22
+ | ProlateSpheroid_WeaklyScattering | Benchmark values for the weakly-scattering prolate spheroid. |
23
+ | Cylinder_Rigid | Benchmark values for the rigid cylinder. |
24
+ | Cylinder_PressureRelease | Benchmark values for the pressure-release cylinder. |
25
+ | Cylinder_Gas | Benchmark values for the gas-filled cylinder. |
26
+ | Cylinder_WeaklyScattering | Benchmark values for the weakly-scattering cylinder. |
27
+
28
+ ## Benchmark TS(&theta;) @ 38 kHz
29
+ Benchmark target strength (TS, db re m<sup>2</sup>) as a function of insonifying angle of incidence (&theta;) for the prolate spheroid and cylinder shapes. The data file [Benchmark_Angle_TS.csv](https://github.com/ices-tools-dev/echoSMs/blob/main/BenchMark_Data/Benchmark_Angle_TS.csv) is a text file with comma-separated variable format (.csv). TS values are given to 2-decimal-place precision (i.e., 0.01 dB). 90-degree &theta; is broadside incidence and 0-degree is end-on incidence.
30
+
31
+ The column names and descriptions are:
32
+
33
+ | Column Name/Variable | Description |
34
+ |----------------------|-------------|
35
+ | Angle_deg | Angle of incidence. TS values are given at 2-degree increments from 0 to 90 degrees. |
36
+ | ProlateSpheroid_Rigid | Benchmark values for the rigid prolate spheroid. |
37
+ | ProlateSpheroid_PressureRelease | Benchmark values for the pressure-release prolate spheroid. |
38
+ | ProlateSpheroid_Gas | Benchmark values for the gas-filled prolate spheroid. |
39
+ | ProlateSpheroid_WeaklyScattering | Benchmark values for the weakly-scattering prolate spheroid. |
40
+ | Cylinder_Rigid | Benchmark values for the rigid cylinder. TS values for end-on (0 degree) incidence were not computed.|
41
+ | Cylinder_PressureRelease | Benchmark values for the pressure-release cylinder. TS values for end-on (0 degree) incidence were not computed. |
42
+ | Cylinder_Gas | Benchmark values for the gas-filled cylinder. TS values for end-on (0 degree) incidence were not computed. |
43
+ | Cylinder_WeaklyScattering | Benchmark values for the weakly-scattering cylinder. TS values for end-on (0 degree) incidence were not computed. |
44
+
45
+
46
+
47
+
48
+
49
+
echosms-0.0.2/docs/contributing.md ADDED
@@ -0,0 +1,37 @@
1
+ # Contributing to echoSMs
2
+
3
+ We welcome all contributions to echoSMs, be it code, test cases, bug reports, discussion of models, etc. Please use the github facilities for this (i.e., issues and pull-requests). We are also happy to accept directly code that we can add to echoSMs on your behalf.
4
+
5
+ An objective of echoSMs is to provide scattering models in a form that is easy to access, use, and compare to other models. To help with that, we specify model parameter units, angle conventions, and required model outputs that code contributions should support. We also suggest coding conventions that should be followed.
6
+
7
+ ## Units
8
+ We use SI units for the model parameters and do not use SI prefixes for model inputs and outputs. The two exceptions to this are the use of degrees rather than radians for angles and the use of deciBels for target strength.
9
+
10
+ | Parameter | Units | Notes |
11
+ |-----------|-------|--|
12
+ |length, diameter, radius, thickness, etc|m||
13
+ |density|kg/m³||
14
+ |sound speed|m/s||
15
+ |angle|°|See below for coordinate conventions|
16
+ |frequency|Hz||
17
+ |target strength|dB|reference value is 1 m²|
18
+
19
+ ## Coordinate systems
20
+
21
+ A single coordinate system should be used for all models provided by echoSMs. The aim is to ease the comparison of results between different models.
22
+
23
+ The right-handed spherical coordinate system as defined by ISO 80000-2[1] is to be used, where organisms are oriented such that θ corresponds to pitch and ɸ to roll, as illustrated below, where the organism lies along the z-axis and the positive x-axis extends above the organism:
24
+
25
+ ![coordinate system](coordinate_system.jpg)
26
+
27
+ The definitions are such that θ values of 0°, 90°, and 180° correspond to organism pitches of head on, dorsal, and tail on, respectively, and positive values of ɸ indicate a roll to starboard. All model code should accept angles and produce results in this coordinate system. If the model calculations use a different coordinate system, the code should internally convert between the system given above and the version used in the code.
28
+
29
+ ## Code style
30
+ Contributions of code should follow standardised or community-agreed styles and be provided in (or added to) a structure suitable for packaging and uploading to package libraries. For Python this includes `pip` and/or `conda`, for R this would be `CRAN`, for Matlab this would be a toolbox on the MATLAB File Exchange, etc.
31
+
32
+ Python code should follow [PEP8](https://peps.python.org/pep-0008) and docstrings should use [PEP257](https://peps.python.org/pep-0257/) with the contents following the [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html).
33
+
34
+
35
+ # References
36
+ 1. ISO. 2019. ISO 80000-2. Part 2: Mathematics. https://www.iso.org/obp/ui/en/#iso:std:iso:80000:-2:ed-2:v2:en.
37
+
echosms-0.0.2/docs/coordinate_system.jpg ADDED
Binary file