osekit 0.4.3__tar.gz → 1.0.1__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 (182) hide show
  1. osekit-1.0.1/CITATION.cff +41 -0
  2. osekit-1.0.1/CONTRIBUTING.md +39 -0
  3. osekit-1.0.1/LICENSE +21 -0
  4. {osekit-0.4.3 → osekit-1.0.1}/PKG-INFO +25 -3
  5. {osekit-0.4.3 → osekit-1.0.1}/README.md +22 -1
  6. osekit-1.0.1/docs/source/_static/favicon.ico +0 -0
  7. osekit-1.0.1/docs/source/audiodata.rst +7 -0
  8. {osekit-0.4.3 → osekit-1.0.1}/docs/source/audiodataset.rst +1 -1
  9. osekit-1.0.1/docs/source/audiofile.rst +7 -0
  10. osekit-1.0.1/docs/source/audioitem.rst +7 -0
  11. osekit-1.0.1/docs/source/basedata.rst +7 -0
  12. {osekit-0.4.3 → osekit-1.0.1}/docs/source/basedataset.rst +1 -1
  13. osekit-1.0.1/docs/source/basefile.rst +7 -0
  14. osekit-1.0.1/docs/source/baseitem.rst +7 -0
  15. {osekit-0.4.3 → osekit-1.0.1}/docs/source/conf.py +1 -0
  16. {osekit-0.4.3 → osekit-1.0.1}/docs/source/contributing.rst +4 -2
  17. {osekit-0.4.3 → osekit-1.0.1}/docs/source/coreapi.rst +2 -2
  18. {osekit-0.4.3 → osekit-1.0.1}/docs/source/coreapi_introduction.rst +5 -5
  19. {osekit-0.4.3 → osekit-1.0.1}/docs/source/coreapi_usage.rst +45 -46
  20. osekit-1.0.1/docs/source/event.rst +7 -0
  21. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_ltas_core.ipynb +6 -6
  22. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_ltas_public.ipynb +40 -51
  23. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_multiple_spectrograms_core.ipynb +15 -7
  24. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_multiple_spectrograms_id_core.ipynb +4 -4
  25. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_multiple_spectrograms_id_public.ipynb +32 -37
  26. osekit-1.0.1/docs/source/example_multiple_spectrograms_public.ipynb +301 -0
  27. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_reshaping_multiple_files_core.ipynb +12 -4
  28. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_reshaping_multiple_files_public.ipynb +64 -71
  29. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_reshaping_one_file.ipynb +3 -3
  30. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_spectrogram.ipynb +5 -5
  31. osekit-1.0.1/docs/source/export_transform.rst +7 -0
  32. osekit-1.0.1/docs/source/frequencyscale.rst +10 -0
  33. {osekit-0.4.3 → osekit-1.0.1}/docs/source/installation.rst +1 -1
  34. {osekit-0.4.3 → osekit-1.0.1}/docs/source/instrument.rst +1 -1
  35. {osekit-0.4.3 → osekit-1.0.1}/docs/source/jobs.rst +37 -30
  36. {osekit-0.4.3 → osekit-1.0.1}/docs/source/ltasdata.rst +1 -1
  37. {osekit-0.4.3 → osekit-1.0.1}/docs/source/multiprocessing.rst +5 -5
  38. {osekit-0.4.3 → osekit-1.0.1}/docs/source/normalization.rst +1 -1
  39. osekit-1.0.1/docs/source/project.rst +7 -0
  40. osekit-1.0.1/docs/source/publicapi.rst +11 -0
  41. {osekit-0.4.3 → osekit-1.0.1}/docs/source/publicapi_usage.rst +108 -108
  42. {osekit-0.4.3 → osekit-1.0.1}/docs/source/spectrodata.rst +1 -1
  43. {osekit-0.4.3 → osekit-1.0.1}/docs/source/spectrodataset.rst +1 -1
  44. {osekit-0.4.3 → osekit-1.0.1}/docs/source/spectrofile.rst +1 -1
  45. {osekit-0.4.3 → osekit-1.0.1}/docs/source/spectroitem.rst +1 -1
  46. osekit-1.0.1/docs/source/transform.rst +18 -0
  47. {osekit-0.4.3 → osekit-1.0.1}/docs/source/usage.rst +1 -1
  48. {osekit-0.4.3 → osekit-1.0.1}/pyproject.toml +3 -2
  49. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/audio_backend/audio_backend.py +4 -0
  50. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/audio_backend/audio_file_manager.py +6 -0
  51. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/audio_backend/mseed_backend.py +35 -0
  52. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/audio_backend/soundfile_backend.py +9 -2
  53. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/audio_data.py +115 -40
  54. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/audio_dataset.py +23 -16
  55. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/audio_file.py +34 -7
  56. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/audio_item.py +18 -2
  57. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/base_data.py +28 -14
  58. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/base_dataset.py +79 -6
  59. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/base_file.py +7 -4
  60. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/base_item.py +3 -3
  61. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/frequency_scale.py +1 -1
  62. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/json_serializer.py +6 -4
  63. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/ltas_data.py +8 -8
  64. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/ltas_dataset.py +4 -4
  65. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/spectro_data.py +79 -36
  66. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/spectro_dataset.py +38 -35
  67. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/spectro_file.py +7 -27
  68. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/spectro_item.py +2 -2
  69. osekit-1.0.1/src/osekit/core_api/__init__.py +12 -0
  70. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/logging_config.yaml +2 -2
  71. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/logging_context.py +2 -3
  72. osekit-0.4.3/src/osekit/public_api/export_analysis.py → osekit-1.0.1/src/osekit/public/export_transform.py +49 -46
  73. osekit-0.4.3/src/osekit/public_api/dataset.py → osekit-1.0.1/src/osekit/public/project.py +277 -228
  74. osekit-0.4.3/src/osekit/public_api/analysis.py → osekit-1.0.1/src/osekit/public/transform.py +92 -48
  75. osekit-1.0.1/src/osekit/public_api/__init__.py +12 -0
  76. osekit-0.4.3/src/osekit/utils/audio_utils.py → osekit-1.0.1/src/osekit/utils/audio.py +3 -2
  77. osekit-0.4.3/src/osekit/utils/core_utils.py → osekit-1.0.1/src/osekit/utils/core.py +6 -6
  78. osekit-1.0.1/src/osekit/utils/deserialization.py +25 -0
  79. osekit-0.4.3/src/osekit/utils/formatting_utils.py → osekit-1.0.1/src/osekit/utils/formatting.py +2 -2
  80. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/utils/job.py +38 -12
  81. osekit-0.4.3/src/osekit/utils/multiprocess_utils.py → osekit-1.0.1/src/osekit/utils/multiprocess.py +2 -2
  82. osekit-0.4.3/src/osekit/utils/timestamp_utils.py → osekit-1.0.1/src/osekit/utils/timestamp.py +84 -15
  83. {osekit-0.4.3 → osekit-1.0.1}/tests/conftest.py +11 -11
  84. osekit-0.4.3/LICENSE → osekit-1.0.1/tests/helpers/__init__.py +0 -0
  85. osekit-1.0.1/tests/helpers/dummy.py +106 -0
  86. {osekit-0.4.3 → osekit-1.0.1}/tests/test_audio.py +92 -20
  87. {osekit-0.4.3 → osekit-1.0.1}/tests/test_audio_file_manager.py +2 -2
  88. {osekit-0.4.3 → osekit-1.0.1}/tests/test_core_api_base.py +277 -126
  89. {osekit-0.4.3 → osekit-1.0.1}/tests/test_event.py +3 -3
  90. osekit-0.4.3/tests/test_export_analysis.py → osekit-1.0.1/tests/test_export_transform.py +32 -23
  91. {osekit-0.4.3 → osekit-1.0.1}/tests/test_frequency_scales.py +1 -1
  92. {osekit-0.4.3 → osekit-1.0.1}/tests/test_instrument.py +8 -8
  93. {osekit-0.4.3 → osekit-1.0.1}/tests/test_job.py +90 -18
  94. {osekit-0.4.3 → osekit-1.0.1}/tests/test_logging.py +26 -17
  95. {osekit-0.4.3 → osekit-1.0.1}/tests/test_mseed.py +6 -9
  96. {osekit-0.4.3 → osekit-1.0.1}/tests/test_multiprocessing.py +8 -6
  97. {osekit-0.4.3 → osekit-1.0.1}/tests/test_permissions.py +14 -14
  98. {osekit-0.4.3 → osekit-1.0.1}/tests/test_public_api.py +532 -347
  99. {osekit-0.4.3 → osekit-1.0.1}/tests/test_serialization.py +105 -30
  100. {osekit-0.4.3 → osekit-1.0.1}/tests/test_spectro.py +517 -130
  101. {osekit-0.4.3 → osekit-1.0.1}/tests/test_timestamp_utils.py +180 -1
  102. {osekit-0.4.3 → osekit-1.0.1}/tests/test_utils.py +54 -8
  103. {osekit-0.4.3 → osekit-1.0.1}/tests/test_welch.py +5 -5
  104. {osekit-0.4.3 → osekit-1.0.1}/uv.lock +1 -11
  105. osekit-0.4.3/docs/source/_static/favicon.ico +0 -0
  106. osekit-0.4.3/docs/source/analysis.rst +0 -18
  107. osekit-0.4.3/docs/source/audiodata.rst +0 -7
  108. osekit-0.4.3/docs/source/audiofile.rst +0 -7
  109. osekit-0.4.3/docs/source/audioitem.rst +0 -7
  110. osekit-0.4.3/docs/source/basedata.rst +0 -7
  111. osekit-0.4.3/docs/source/basefile.rst +0 -7
  112. osekit-0.4.3/docs/source/baseitem.rst +0 -7
  113. osekit-0.4.3/docs/source/dataset.rst +0 -7
  114. osekit-0.4.3/docs/source/event.rst +0 -7
  115. osekit-0.4.3/docs/source/example_multiple_spectrograms_public.ipynb +0 -340
  116. osekit-0.4.3/docs/source/export_analysis.rst +0 -7
  117. osekit-0.4.3/docs/source/frequencyscale.rst +0 -10
  118. osekit-0.4.3/docs/source/publicapi.rst +0 -11
  119. {osekit-0.4.3 → osekit-1.0.1}/.github/workflows/documentation.yml +0 -0
  120. {osekit-0.4.3 → osekit-1.0.1}/.github/workflows/github_ci.yml +0 -0
  121. {osekit-0.4.3 → osekit-1.0.1}/.github/workflows/publish.yml +0 -0
  122. {osekit-0.4.3 → osekit-1.0.1}/.gitignore +0 -0
  123. {osekit-0.4.3 → osekit-1.0.1}/.pre-commit-config.yaml +0 -0
  124. {osekit-0.4.3 → osekit-1.0.1}/CHANGELOG.md +0 -0
  125. {osekit-0.4.3 → osekit-1.0.1}/docs/Makefile +0 -0
  126. {osekit-0.4.3 → osekit-1.0.1}/docs/logo/osekit.png +0 -0
  127. {osekit-0.4.3 → osekit-1.0.1}/docs/logo/osekit_mid.png +0 -0
  128. {osekit-0.4.3 → osekit-1.0.1}/docs/logo/osekit_small.png +0 -0
  129. {osekit-0.4.3 → osekit-1.0.1}/docs/logo/osmose.png +0 -0
  130. {osekit-0.4.3 → osekit-1.0.1}/docs/logo/osmose_texte_sombre.png +0 -0
  131. {osekit-0.4.3 → osekit-1.0.1}/docs/logo/osmose_texte_sombre_small.png +0 -0
  132. {osekit-0.4.3 → osekit-1.0.1}/docs/make.bat +0 -0
  133. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/audio_data/ex1.svg +0 -0
  134. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/audio_data/ex2.svg +0 -0
  135. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/data_structure/file_item_data_0.svg +0 -0
  136. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/data_structure/file_item_data_1.svg +0 -0
  137. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/data_structure/file_item_data_2.svg +0 -0
  138. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/ltas/ltas.gif +0 -0
  139. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1829.wav +0 -0
  140. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1830.wav +0 -0
  141. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1832.wav +0 -0
  142. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1833.wav +0 -0
  143. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1834.wav +0 -0
  144. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1835.wav +0 -0
  145. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1836.wav +0 -0
  146. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1837.wav +0 -0
  147. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/id/1838.wav +0 -0
  148. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223450.wav +0 -0
  149. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223500.wav +0 -0
  150. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223510.wav +0 -0
  151. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223520.wav +0 -0
  152. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223530.wav +0 -0
  153. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223600.wav +0 -0
  154. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223610.wav +0 -0
  155. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223620.wav +0 -0
  156. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223630.wav +0 -0
  157. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/sample_audio/timestamped/sample_220925_223640.wav +0 -0
  158. {osekit-0.4.3 → osekit-1.0.1}/docs/source/_static/spectrograms/frequency_scale.png +0 -0
  159. {osekit-0.4.3 → osekit-1.0.1}/docs/source/api.rst +0 -0
  160. {osekit-0.4.3 → osekit-1.0.1}/docs/source/audiofilemanager.rst +0 -0
  161. {osekit-0.4.3 → osekit-1.0.1}/docs/source/coreapi_home.rst +0 -0
  162. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_ltas.rst +0 -0
  163. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_multiple_spectrograms.rst +0 -0
  164. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_multiple_spectrograms_id.rst +0 -0
  165. {osekit-0.4.3 → osekit-1.0.1}/docs/source/example_reshaping_multiple_files.rst +0 -0
  166. {osekit-0.4.3 → osekit-1.0.1}/docs/source/examples.rst +0 -0
  167. {osekit-0.4.3 → osekit-1.0.1}/docs/source/index.rst +0 -0
  168. {osekit-0.4.3 → osekit-1.0.1}/docs/source/job.rst +0 -0
  169. {osekit-0.4.3 → osekit-1.0.1}/docs/source/utils.rst +0 -0
  170. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/__init__.py +0 -0
  171. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/config.py +0 -0
  172. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/__init__.py +0 -0
  173. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/event.py +0 -0
  174. {osekit-0.4.3/src/osekit/core_api → osekit-1.0.1/src/osekit/core}/instrument.py +0 -0
  175. {osekit-0.4.3/src/osekit/public_api → osekit-1.0.1/src/osekit/public}/__init__.py +0 -0
  176. {osekit-0.4.3 → osekit-1.0.1}/src/osekit/utils/__init__.py +0 -0
  177. /osekit-0.4.3/src/osekit/utils/path_utils.py → /osekit-1.0.1/src/osekit/utils/path.py +0 -0
  178. {osekit-0.4.3 → osekit-1.0.1}/tests/__init__.py +0 -0
  179. {osekit-0.4.3 → osekit-1.0.1}/tests/sample_dataset/sample1_180701_204453.wav +0 -0
  180. {osekit-0.4.3 → osekit-1.0.1}/tests/sample_dataset/sample1_190222_010000.wav +0 -0
  181. {osekit-0.4.3 → osekit-1.0.1}/tests/sample_dataset/sample1_220998_185532.wav +0 -0
  182. {osekit-0.4.3 → osekit-1.0.1}/tests/test_files.py +0 -0
@@ -0,0 +1,41 @@
1
+ authors:
2
+ - affiliation: ENSTA
3
+ family-names: Berthomieu
4
+ given-names: Gauthier
5
+ orcid: 0000-0001-9527-4087
6
+ - affiliation: ENSTA
7
+ family-names: Cazau
8
+ given-names: Dorian
9
+ orcid: 0000-0003-4414-1721
10
+ - family-names: Loire
11
+ given-names: Benjamin
12
+ orcid: 0009-0005-0362-1835
13
+ - affiliation: ENSTA
14
+ family-names: Mathieu Dupont
15
+ - family-names: Anatole Gros-Martial
16
+ - affiliation: ENSTA
17
+ family-names: Torterotot
18
+ given-names: Maelle
19
+ orcid: 0000-0002-8912-2463
20
+ - affiliation: ENSTA
21
+ family-names: Morin
22
+ given-names: Elodie
23
+ orcid: 0009-0000-3919-1463
24
+ - family-names: Carvaillo
25
+ given-names: Paul
26
+ - family-names: Dubus
27
+ given-names: Gabriel
28
+ orcid: 0009-0000-9390-6765
29
+ cff-version: 1.2.0
30
+ date-released: '2026-01-22'
31
+ doi: 10.5281/zenodo.18337275
32
+ identifiers:
33
+ - type: swh
34
+ value: swh:1:dir:a543d6089126ffcb64e9ab87e2046c1940acd8ea;origin=https://doi.org/10.5281/zenodo.18337274;visit=swh:1:snp:2ef4d0a3cee6b9a69d76f21dd32dd99c0d3e43cf;anchor=swh:1:rel:25b5f0a5812251a7bb313752af46a4ea9d625386;path=Project-OSmOSE-OSEkit-78ebba6
35
+ license:
36
+ - mit
37
+ message: If you use this software, please cite it using the metadata from this file.
38
+ repository-code: https://github.com/Project-OSmOSE/OSEkit/tree/v0.4.3
39
+ title: OSEkit
40
+ type: software
41
+ version: v0.4.3
@@ -0,0 +1,39 @@
1
+ # Contribute to OSEkit
2
+
3
+ Thank you for your interest in this project.
4
+
5
+ This document describes the rules and best practices to
6
+ follow when contributing to the development of the software.
7
+
8
+
9
+ ## Contributions
10
+
11
+ There are many ways to contribute to this project, including:
12
+
13
+ - **Starring** the [OSEkit GitHub page](https://github.com/Project-OSmOSE/OSEkit) to show the world that you use it
14
+ - **Referencing OSEkit** in your articles
15
+
16
+ (see *"Cite this repository"* in [the About section of the OSEkit GitHub page](https://github.com/Project-OSmOSE/OSEkit))
17
+
18
+ - **Participating** in the [OSEkit GitHub](https://github.com/Project-OSmOSE/OSEkit) by:
19
+ - **Reporting** difficulties you encounter when using the package in new [issues](https://github.com/Project-OSmOSE/OSEkit/issues)
20
+ - **Suggesting** functionalities that would come in handy in **OSEkit** in new [issues](https://github.com/Project-OSmOSE/OSEkit/issues)
21
+ - **Reviewing** existing [pull requests](https://github.com/Project-OSmOSE/OSEkit/pulls)
22
+ - **Authoring** new [pull requests](https://github.com/Project-OSmOSE/OSEkit/pulls) to:
23
+ - **Add** new cool functionalities
24
+ - **Fix** things that don't work exactly the way they should
25
+ - **Improve** the documentation
26
+
27
+ Any contribution submitted to this project is deemed to be provided
28
+ under the project's MIT license, without additional restrictions.
29
+
30
+ By submitting a contribution, you warrant that:
31
+ - You are the author of the contribution or have the necessary rights,
32
+ - The contribution does not violate any third-party rights,
33
+ - The contribution is provided under the project's MIT license.
34
+ - No contributions can be accepted under a different or incompatible license.
35
+
36
+ ## Contribution process
37
+
38
+ Please refer to the [Contributing page in our official documentation](https://project-osmose.github.io/OSEkit/contributing.html#github-contributor-workflow)
39
+ for a straightforward guide on how to push your contribution to our repo!
osekit-1.0.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025-present [ENSTA, Lab-STICC UMR CNRS 6285]
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.
@@ -1,10 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: osekit
3
- Version: 0.4.3
3
+ Version: 1.0.1
4
4
  Summary: OSEkit
5
5
  Author-email: OSmOSE team <osmose@ensta-bretagne.fr>
6
+ License-Expression: MIT
6
7
  License-File: LICENSE
7
- Classifier: Development Status :: 4 - Beta
8
+ Classifier: Development Status :: 5 - Production/Stable
8
9
  Classifier: Programming Language :: Python :: 3.12
9
10
  Classifier: Programming Language :: Python :: 3.13
10
11
  Requires-Python: >=3.12
@@ -37,6 +38,7 @@ Description-Content-Type: text/markdown
37
38
  [![Coverage Status](https://coveralls.io/repos/github/Project-OSmOSE/OSEkit/badge.svg?branch=version-bump)](https://coveralls.io/github/Project-OSmOSE/OSEkit?branch=version-bump)
38
39
  ![license](https://img.shields.io/github/license/mashape/apistatus.svg)
39
40
  ![Open Source Love](https://img.shields.io/badge/open%20source-♡-lightgrey)
41
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18337275.svg)](https://doi.org/10.5281/zenodo.18337275)
40
42
  ![Python 3.12](https://img.shields.io/pypi/pyversions/osekit)
41
43
 
42
44
 
@@ -60,6 +62,7 @@ It is primarily designed for working on underwater passive acoustics data, but c
60
62
  - Seamless, timestamp-based access across multiple files (e.g., pick a 3-minutes long segment spannign over two 1.5-minutes long files without manual file picking)
61
63
  - Preprocessing utilities: resampling, normalization...
62
64
  - Spectral analysis routines: compute power spectra, spectrograms, LTAS...
65
+ - A high-level **API** designed to work with [APLOSE](https://github.com/Project-OSmOSE/APLOSE), our web-base spectrogram annotation tool
63
66
 
64
67
  **OSEkit** treats your audio dataset as a continuous timeline, whatever the raw files configuration.
65
68
  You request audio by time intervals and the package fetches from the raw files behind the scenes: no manual I/O juggling required.
@@ -70,8 +73,27 @@ You request audio by time intervals and the package fetches from the raw files b
70
73
 
71
74
  All details to start using our toolkit and make the most out of it are given in our [documentation](https://project-osmose.github.io/OSEkit/).
72
75
 
73
- <br>
74
76
 
77
+ This software is distributed under the MIT license.
78
+
79
+ You are free to use, modify, and redistribute it, provided that you retain the copyright
80
+ notices and license text, in accordance with the terms of this license.
81
+
82
+ See the [LICENSE](./LICENSE) file for the full text.
83
+
84
+ Some third-party libraries are used in this project. Details of their licenses are
85
+ available in the repository [dependency graph](https://github.com/Project-OSmOSE/OSEkit/network/dependencies).
86
+
87
+ This software must not be sold.
88
+
89
+ If you use this software in scientific work, please cite it in accordance with the
90
+ [CITATION](./CITATION.cff) file.
91
+
92
+ This software is provided for research and teaching purposes. It is provided “as is,”
93
+ without warranty. The authors and the institution cannot be held responsible for any
94
+ damage resulting from its use.
95
+
96
+ <br>
75
97
 
76
98
  <div align="center">
77
99
 
@@ -12,6 +12,7 @@
12
12
  [![Coverage Status](https://coveralls.io/repos/github/Project-OSmOSE/OSEkit/badge.svg?branch=version-bump)](https://coveralls.io/github/Project-OSmOSE/OSEkit?branch=version-bump)
13
13
  ![license](https://img.shields.io/github/license/mashape/apistatus.svg)
14
14
  ![Open Source Love](https://img.shields.io/badge/open%20source-♡-lightgrey)
15
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18337275.svg)](https://doi.org/10.5281/zenodo.18337275)
15
16
  ![Python 3.12](https://img.shields.io/pypi/pyversions/osekit)
16
17
 
17
18
 
@@ -35,6 +36,7 @@ It is primarily designed for working on underwater passive acoustics data, but c
35
36
  - Seamless, timestamp-based access across multiple files (e.g., pick a 3-minutes long segment spannign over two 1.5-minutes long files without manual file picking)
36
37
  - Preprocessing utilities: resampling, normalization...
37
38
  - Spectral analysis routines: compute power spectra, spectrograms, LTAS...
39
+ - A high-level **API** designed to work with [APLOSE](https://github.com/Project-OSmOSE/APLOSE), our web-base spectrogram annotation tool
38
40
 
39
41
  **OSEkit** treats your audio dataset as a continuous timeline, whatever the raw files configuration.
40
42
  You request audio by time intervals and the package fetches from the raw files behind the scenes: no manual I/O juggling required.
@@ -45,8 +47,27 @@ You request audio by time intervals and the package fetches from the raw files b
45
47
 
46
48
  All details to start using our toolkit and make the most out of it are given in our [documentation](https://project-osmose.github.io/OSEkit/).
47
49
 
48
- <br>
49
50
 
51
+ This software is distributed under the MIT license.
52
+
53
+ You are free to use, modify, and redistribute it, provided that you retain the copyright
54
+ notices and license text, in accordance with the terms of this license.
55
+
56
+ See the [LICENSE](./LICENSE) file for the full text.
57
+
58
+ Some third-party libraries are used in this project. Details of their licenses are
59
+ available in the repository [dependency graph](https://github.com/Project-OSmOSE/OSEkit/network/dependencies).
60
+
61
+ This software must not be sold.
62
+
63
+ If you use this software in scientific work, please cite it in accordance with the
64
+ [CITATION](./CITATION.cff) file.
65
+
66
+ This software is provided for research and teaching purposes. It is provided “as is,”
67
+ without warranty. The authors and the institution cannot be held responsible for any
68
+ damage resulting from its use.
69
+
70
+ <br>
50
71
 
51
72
  <div align="center">
52
73
 
@@ -0,0 +1,7 @@
1
+ .. _audiodata:
2
+
3
+ AudioData
4
+ ---------
5
+
6
+ .. autoclass:: osekit.core.audio_data.AudioData
7
+ :members:
@@ -3,5 +3,5 @@
3
3
  AudioDataset
4
4
  ------------
5
5
 
6
- .. autoclass:: osekit.core_api.audio_dataset.AudioDataset
6
+ .. autoclass:: osekit.core.audio_dataset.AudioDataset
7
7
  :members:
@@ -0,0 +1,7 @@
1
+ .. _audiofile:
2
+
3
+ AudioFile
4
+ ---------
5
+
6
+ .. autoclass:: osekit.core.audio_file.AudioFile
7
+ :members:
@@ -0,0 +1,7 @@
1
+ .. _audioitem:
2
+
3
+ AudioItem
4
+ ---------
5
+
6
+ .. autoclass:: osekit.core.audio_item.AudioItem
7
+ :members:
@@ -0,0 +1,7 @@
1
+ .. _basedata:
2
+
3
+ BaseData
4
+ --------
5
+
6
+ .. autoclass:: osekit.core.base_data.BaseData
7
+ :members:
@@ -3,5 +3,5 @@
3
3
  BaseDataset
4
4
  -----------
5
5
 
6
- .. autoclass:: osekit.core_api.base_dataset.BaseDataset
6
+ .. autoclass:: osekit.core.base_dataset.BaseDataset
7
7
  :members:
@@ -0,0 +1,7 @@
1
+ .. _basefile:
2
+
3
+ BaseFile
4
+ --------
5
+
6
+ .. autoclass:: osekit.core.base_file.BaseFile
7
+ :members:
@@ -0,0 +1,7 @@
1
+ .. _baseitem:
2
+
3
+ BaseItem
4
+ --------
5
+
6
+ .. autoclass:: osekit.core.base_item.BaseItem
7
+ :members:
@@ -27,6 +27,7 @@ autoclass_content = "both"
27
27
  html_theme = "sphinx_book_theme"
28
28
  html_logo = "../logo/osekit_small.png"
29
29
  html_title = "OSEKit"
30
+ html_favicon = "_static/favicon.ico"
30
31
 
31
32
  html_theme_options = {
32
33
  "repository_url": "https://github.com/Project-OSmOSE/OSEkit",
@@ -9,6 +9,8 @@ There are many ways to contribute to this project, including:
9
9
 
10
10
  - **Starring** the `OSEkit GitHub page <https://github.com/Project-OSmOSE/OSEkit>`_ to show the world that you use it
11
11
  - **Referencing OSEkit** in your articles
12
+ (see *"Cite this repository"* in `the About section of the OSEkit GitHub page <https://github.com/Project-OSmOSE/OSEkit>`_)
13
+
12
14
  - **Participating** in the `OSEkit GitHub <https://github.com/Project-OSmOSE/OSEkit>`_ by:
13
15
  - **Reporting** difficulties you encounter when using the package in new `issues <https://github.com/Project-OSmOSE/OSEkit/issues>`_
14
16
  - **Suggesting** functionalities that would come in handy in **OSEkit** in new `issues <https://github.com/Project-OSmOSE/OSEkit/issues>`_
@@ -23,14 +25,14 @@ There are many ways to contribute to this project, including:
23
25
 
24
26
  Contributions to the **OSEkit** codebase are done with **GitHub**.
25
27
 
26
- If you're new to this tool, we recommand taking a look at some resources to get you started,
28
+ If you're new to this tool, we recommend taking a look at some resources to get you started,
27
29
  such as the `Introduction to Github interactive course <https://github.com/skills/introduction-to-github>`_.
28
30
 
29
31
  If you want to dig in **OSEkit**'s code to do anything you'd like (adding functionalities, fixing bugs, working on the documentation...),
30
32
  you'll have to submit a new **pull request**.
31
33
 
32
34
  There are lots of great tutorials out there that'll guide you in the process of submitting a pull request.
33
- We recommand you follow one of those, e.g. `DigitalOcean's How To Create a Pull Request on GitHub <https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github>`_.
35
+ We recommend you follow one of those, e.g. `DigitalOcean's How To Create a Pull Request on GitHub <https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github>`_.
34
36
 
35
37
  We use `uv <https://docs.astral.sh/uv/>`_ to manage the project, and suggest that you install the project
36
38
  following the instructions in the :ref:`Install from git <from-git>` section of the documentation.
@@ -1,7 +1,7 @@
1
1
  .. _coreapi:
2
2
 
3
- Core API
4
- ----------
3
+ Core
4
+ ----
5
5
 
6
6
  .. toctree::
7
7
  :maxdepth: 1
@@ -14,7 +14,7 @@ audio (or any other type of) data.
14
14
  Event
15
15
  """""
16
16
 
17
- The :class:`osekit.core_api.event.Event` represent anything that is time-bound: an ``Event`` has a begin and an end, which are described as `pandas Timestamps <https://pandas.pydata.org/docs/reference/api/pandas.Timestamp.html>`_.
17
+ The :class:`osekit.core.event.Event` represent anything that is time-bound: an ``Event`` has a begin and an end, which are described as `pandas Timestamps <https://pandas.pydata.org/docs/reference/api/pandas.Timestamp.html>`_.
18
18
 
19
19
  Almost every other class in **OSEkit** inherits from ``Event``.
20
20
 
@@ -47,9 +47,9 @@ Different type of data
47
47
  Since **OSEkit** provides ways to manipulate different types of data (audio, spectro, etc.), the `Data` <-> `File` operations described in the :ref:`Data and Files <data_files>` section
48
48
  are managed in bases classes:
49
49
 
50
- - :class:`osekit.core_api.base_file.BaseFile` represent any **file**
51
- - :class:`osekit.core_api.base_item.BaseItem` represent any **item**
52
- - :class:`osekit.core_api.base_data.BaseData` represent any **data**
50
+ - :class:`osekit.core.base_file.BaseFile` represent any **file**
51
+ - :class:`osekit.core.base_item.BaseItem` represent any **item**
52
+ - :class:`osekit.core.base_data.BaseData` represent any **data**
53
53
 
54
54
  These base classes are then derived through inheritance to specialized classes for any data type. For example, **audio data** is manipulated through the
55
- :class:`osekit.core_api.audio_data.AudioData` class.
55
+ :class:`osekit.core.audio_data.AudioData` class.
@@ -6,13 +6,13 @@ Usage
6
6
  Audio File
7
7
  ^^^^^^^^^^
8
8
 
9
- To turn an audio file into an **OSEkit** ``AudioFile`` (represented by the :class:`osekit.core_api.audio_file.AudioFile` class), all you need is the path to the file and a begin timestamp.
9
+ To turn an audio file into an **OSEkit** ``AudioFile`` (represented by the :class:`osekit.core.audio_file.AudioFile` class), all you need is the path to the file and a begin timestamp.
10
10
 
11
11
  Such begin timestamp can either be specified (as a :class:`pandas.Timestamp` instance), or parsed from the audio file name by specifing the `strptime format <https://strftime.org/>`_:
12
12
 
13
13
  .. code-block:: python
14
14
 
15
- from osekit.core_api.audio_file import AudioFile
15
+ from osekit.core.audio_file import AudioFile
16
16
  from pathlib import Path
17
17
 
18
18
  af = AudioFile(
@@ -26,18 +26,18 @@ Audio Data
26
26
  Design
27
27
  """"""
28
28
 
29
- The :class:`osekit.core_api.audio_data.AudioData` class represent a chunk of audio taken between two specific timestamps from one or more `AudioFile` instances.
29
+ The :class:`osekit.core.audio_data.AudioData` class represent a chunk of audio taken between two specific timestamps from one or more `AudioFile` instances.
30
30
 
31
31
  This class offers means of easily resample the data and access it on-demand (with an optimized I/O workflow to minimize the file openings/closings).
32
32
 
33
- To create an ``AudioData`` from ``AudioFiles``, use the :meth:`osekit.core_api.audio_data.AudioData.from_files` class method.
33
+ To create an ``AudioData`` from ``AudioFiles``, use the :meth:`osekit.core.audio_data.AudioData.from_files` class method.
34
34
 
35
35
  Example for an ``AudioData`` representing the first 2 seconds of the ``foo/7189.230405154906.wav`` audio file:
36
36
 
37
37
  .. code-block:: python
38
38
 
39
39
  from pandas import Timestamp, Timedelta
40
- from osekit.core_api.audio_data import AudioData
40
+ from osekit.core.audio_data import AudioData
41
41
 
42
42
  ad = AudioData.from_files(
43
43
  files=[af],
@@ -104,16 +104,16 @@ Item 4
104
104
  Reading data
105
105
  """"""""""""
106
106
 
107
- The :meth:`osekit.core_api.audio_data.AudioData.get_value` method returns a `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_ that contains the wav values of the audio data.
107
+ The :meth:`osekit.core.audio_data.AudioData.get_value` method returns a `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_ that contains the wav values of the audio data.
108
108
 
109
- The data is fetched seamlessly on-demand from the audio file(s). The opening/closing of the audio files is optimized thanks to a :class:`osekit.core_api.audio_file_manager.AudioFileManager` instance.
109
+ The data is fetched seamlessly on-demand from the audio file(s). The opening/closing of the audio files is optimized thanks to a :class:`osekit.core.audio_file_manager.AudioFileManager` instance.
110
110
 
111
111
  Eventual time gap between audio items are filled with ``0.`` values.
112
112
 
113
113
  Normalization
114
114
  """""""""""""
115
115
 
116
- The fetched audio data can be normalized according to the presets given by the :class:`osekit.utils.audio_utils.Normalization` flag:
116
+ The fetched audio data can be normalized according to the presets given by the :class:`osekit.utils.audio.Normalization` flag:
117
117
 
118
118
  .. list-table:: Normalization presets
119
119
  :widths: 10 10
@@ -130,13 +130,13 @@ The fetched audio data can be normalized according to the presets given by the :
130
130
  * - ``Normalization.ZSCORE``
131
131
  - :math:`\frac{ x-\overline{x} }{\sigma (x)}`
132
132
 
133
- To normalize the data, simply set the :attr:`osekit.core_api.audio_data.AudioData.normalization` property to the
133
+ To normalize the data, simply set the :attr:`osekit.core.audio_data.AudioData.normalization` property to the
134
134
  requested normalization flag:
135
135
 
136
136
  .. code-block:: python
137
137
 
138
- from osekit.core_api.audio_data.AudioData import AudioData
139
- from osekit.utils.audio_utils.normalization import Normalization
138
+ from osekit.core.audio_data.AudioData import AudioData
139
+ from osekit.utils.audio.normalization import Normalization
140
140
 
141
141
  ad = AudioData(...)
142
142
  ad.normalization = Normalization.ZSCORE # Note: normalization also is a parameter of the AudioData initializer
@@ -149,7 +149,7 @@ requested normalization flag:
149
149
 
150
150
  .. code-block:: python
151
151
 
152
- from osekit.utils.audio_utils.normalization import Normalization
152
+ from osekit.utils.audio.normalization import Normalization
153
153
 
154
154
  dc_peak = Normalization.DC_REJECT | Normalization.PEAK
155
155
 
@@ -159,7 +159,7 @@ requested normalization flag:
159
159
 
160
160
  .. code-block:: python
161
161
 
162
- from osekit.utils.audio_utils.normalization import Normalization
162
+ from osekit.utils.audio.normalization import Normalization
163
163
 
164
164
  incorrect_normalization = Normalization.RAW | Normalization.PEAK
165
165
  incorrect_normalization = Normalization.DC_REJECT | Normalization.RAW | Normalization.PEAK
@@ -169,16 +169,16 @@ requested normalization flag:
169
169
  Calibration
170
170
  """""""""""
171
171
 
172
- The :class:`osekit.core_api.instrument.Instrument` class can be used to provide calibration info to your audio data.
172
+ The :class:`osekit.core.instrument.Instrument` class can be used to provide calibration info to your audio data.
173
173
  This can be used to convert raw WAV data to the recorded acoustic pressure.
174
174
 
175
- An ``Instrument`` instance can be attached to an ``AudioData``. Then, the :meth:`osekit.core_api.audio_data.AudioData.get_value_calibrated` method
175
+ An ``Instrument`` instance can be attached to an ``AudioData``. Then, the :meth:`osekit.core.audio_data.AudioData.get_value_calibrated` method
176
176
  allows for retrieving the data in the shape of the recorded acoustic pressure.
177
177
 
178
178
  .. code-block:: python
179
179
 
180
- from osekit.core_api.audio_data import AudioData
181
- from osekit.core_api.instrument import Instrument
180
+ from osekit.core.audio_data import AudioData
181
+ from osekit.core.instrument import Instrument
182
182
  import numpy as np
183
183
 
184
184
  instrument = Instrument(end_to_end_db = 150) # The raw 1. WAV value equals 150 dB SPL re 1 uPa
@@ -191,13 +191,13 @@ allows for retrieving the data in the shape of the recorded acoustic pressure.
191
191
  Resampling
192
192
  """"""""""
193
193
 
194
- ``AudioData`` can be resampled just by modifying the :attr:`osekit.core_api.audio_data.AudioData.sample_rate` field.
194
+ ``AudioData`` can be resampled just by modifying the :attr:`osekit.core.audio_data.AudioData.sample_rate` field.
195
195
 
196
196
  Modifying the sample rate will not access the data, but the data will be resampled on the fly when it is requested:
197
197
 
198
198
  .. code-block:: python
199
199
 
200
- from osekit.core_api.audio_data import AudioData
200
+ from osekit.core.audio_data import AudioData
201
201
 
202
202
  ad = AudioData(...)
203
203
  ad.sample_rate = 48_000 # Resample the signal at 48 kHz. Nothing happens yet
@@ -207,7 +207,7 @@ Modifying the sample rate will not access the data, but the data will be resampl
207
207
  Audio Dataset
208
208
  ^^^^^^^^^^^^^
209
209
 
210
- The :class:`osekit.core_api.audio_dataset.AudioDataset` class enables the instantiation and manipulation of large amounts of
210
+ The :class:`osekit.core.audio_dataset.AudioDataset` class enables the instantiation and manipulation of large amounts of
211
211
  ``AudioData`` objects with simple operations.
212
212
 
213
213
  Instantiation
@@ -216,14 +216,14 @@ Instantiation
216
216
  The constructor of the ``AudioDataset`` class accepts a list of ``AudioData`` as parameter.
217
217
 
218
218
  But this is not the only way to create an audio dataset.
219
- The :meth:`osekit.core_api.audio_dataset.AudioDataset.from_folder` class method allows to easily instantiate
219
+ The :meth:`osekit.core.audio_dataset.AudioDataset.from_folder` class method allows to easily instantiate
220
220
  an ``AudioDataset`` from a given folder containing audio files:
221
221
 
222
222
  .. code-block:: python
223
223
 
224
224
  from pathlib import Path
225
- from osekit.core_api.audio_dataset import AudioDataset
226
- from osekit.core_api.instrument import Instrument
225
+ from osekit.core.audio_dataset import AudioDataset
226
+ from osekit.core.instrument import Instrument
227
227
  from pandas import Timestamp, Timedelta
228
228
 
229
229
  folder = Path(r"...")
@@ -241,7 +241,7 @@ an ``AudioDataset`` from a given folder containing audio files:
241
241
  The resulting ``AudioDataset`` will contain 10s-long ``AudioData`` ranging from ``2009-01-06 12:00:00`` to ``2009-01-06 14:00:00``.
242
242
 
243
243
  This is the default behaviour, but other ways of computing the ``AudioData`` time locations are available through the
244
- :meth:`osekit.core_api.audio_dataset.AudioDataset.from_folder` ``mode`` parameter (see the API documentation for more info).
244
+ :meth:`osekit.core.audio_dataset.AudioDataset.from_folder` ``mode`` parameter (see the API documentation for more info).
245
245
 
246
246
  You don't have to worry about the shape of the original audio files: audio data will be fetched seamlessly in the corresponding
247
247
  file(s) whenever you need it.
@@ -258,8 +258,8 @@ Each next valid audio file will be considered to start immediately after the end
258
258
  .. code-block:: python
259
259
 
260
260
  from pathlib import Path
261
- from osekit.core_api.audio_dataset import AudioDataset
262
- from osekit.core_api.instrument import Instrument
261
+ from osekit.core.audio_dataset import AudioDataset
262
+ from osekit.core.instrument import Instrument
263
263
  from pandas import Timestamp, Timedelta
264
264
 
265
265
  folder = Path(r"...")
@@ -288,13 +288,13 @@ If one wanted to resample these 10s-long audio data and export them as wav files
288
288
  ads.sample_rate = 48_000 # The sample rate of all AudioData will be edited
289
289
  ads.write(folder / "output") # All audio data will be exported to wav files in that folder
290
290
 
291
- All the ``AudioData`` constituting the ``AudioDataset`` are accessible through the :attr:`osekit.core_api.audio_dataset.AudioDataset.data`
291
+ All the ``AudioData`` constituting the ``AudioDataset`` are accessible through the :attr:`osekit.core.audio_dataset.AudioDataset.data`
292
292
  field:
293
293
 
294
294
  .. code-block:: python
295
295
 
296
296
  # Filtering the ads data to remove data without audio (e.g. between files)
297
- ads.data = [ad for ad in ads.data if not ad.is_empty]
297
+ ads.remove_empty_data(threshold=0.)
298
298
 
299
299
  # Resampling/Exporting only the first audio data
300
300
  ad = ads.data[0]
@@ -305,14 +305,14 @@ field:
305
305
  Spectro Data
306
306
  ^^^^^^^^^^^^
307
307
 
308
- The :class:`osekit.core_api.spectro_data.SpectroData` class allows to perform spectral computations and to plot spectrograms from ``AudioData`` objects.
308
+ The :class:`osekit.core.spectro_data.SpectroData` class allows to perform spectral computations and to plot spectrograms from ``AudioData`` objects.
309
309
 
310
310
  The most straightforward way to instantiate a ``SpectroData`` is from an ``AudioData`` and a `scipy.signal.ShortTimeFFT <https://docs.scipy.org/doc//scipy/reference/generated/scipy.signal.ShortTimeFFT.html>`_ instance:
311
311
 
312
312
  .. code-block:: python
313
313
 
314
- from osekit.core_api.audio_data import AudioData
315
- from osekit.core_api.spectro_data import SpectroData
314
+ from osekit.core.audio_data import AudioData
315
+ from osekit.core.spectro_data import SpectroData
316
316
  from scipy.signal import ShortTimeFFT
317
317
  from scipy.signal.windows import hamming
318
318
 
@@ -331,21 +331,20 @@ Once again, no audio has yet been fetched: everything happens only on-demand.
331
331
  NPZ matrices
332
332
  """"""""""""
333
333
 
334
- The ``SpectroData`` object can be used to compute the spectrum matrices of the ``AudioData`` with the :meth:`osekit.core_api.spectro_data.SpectroData.get_value` method.
334
+ The ``SpectroData`` object can be used to compute the spectrum matrices of the ``AudioData`` with the :meth:`osekit.core.spectro_data.SpectroData.get_value` method.
335
335
 
336
- The :attr:`osekit.core_api.spectro_data.SpectroData.sx_dtype` property can be set to either ``complex`` (default) or ``float`` to return either the spectrum matrices as complex numbers or absolute values, respectively.
336
+ The :attr:`osekit.core.spectro_data.SpectroData.sx_dtype` property can be set to either ``complex`` (default) or ``float`` to return either the spectrum matrices as complex numbers or absolute values, respectively.
337
337
 
338
- The spectrum matrices can be converted to decibels thanks to the :meth:`osekit.core_api.spectro_data.SpectroData.to_db` method.
339
- This method will convert the matrix values either to dB SPL (re ``Instrument.P_REF``) if an :ref:`Instrument <instrument_calibration>` was provided to the ``AudioData`` or to dB FS otherwise.
338
+ The spectrum matrices can be converted to decibels thanks to the :meth:`osekit.core.spectro_data.SpectroData.get_db_value` method.
339
+ This method will convert the spectrum values either to dB SPL (re ``Instrument.P_REF``) if an :ref:`Instrument <instrument_calibration>` was provided to the ``AudioData`` or to dB FS otherwise.
340
340
 
341
- The spectrum matrices can then be exported to npz files thanks to the :meth:`osekit.core_api.spectro_data.SpectroData.write` method.
341
+ The spectrum matrices can then be exported to npz files thanks to the :meth:`osekit.core.spectro_data.SpectroData.write` method.
342
342
 
343
343
  .. code-block:: python
344
344
 
345
345
  sd = SpectroData.from_audio_data(data=ad, fft=sft)
346
346
 
347
- sx = sd.get_value()
348
- sx_db = sd.to_db(sx)
347
+ sx_db = sd.get_db_value() # Use sd.get_value() if you want the complex spectrum
349
348
 
350
349
  # If sx has already been computed, you can pass it as a parameter to avoid re-computing it.
351
350
  # Otherwise, it will just be computed from scratch.
@@ -355,14 +354,14 @@ The spectrum matrices can then be exported to npz files thanks to the :meth:`ose
355
354
  Plot and export
356
355
  """""""""""""""
357
356
 
358
- Spectrograms can be plotted from the ``SpectroData`` objects thanks to the :meth:`osekit.core_api.spectro_data.SpectroData.plot` method.
357
+ Spectrograms can be plotted from the ``SpectroData`` objects thanks to the :meth:`osekit.core.spectro_data.SpectroData.plot` method.
359
358
 
360
359
  OSEkit uses `pyplot <https://matplotlib.org/stable/tutorials/pyplot.html>`_ for plotting spectrograms. A pyplot `Axes <https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes>`_
361
360
  can be provided to the ``SpectroData.plot()`` method to specify an Axes in which to plot the spectrogram:
362
361
 
363
362
  .. code-block:: python
364
363
 
365
- from osekit.core_api.spectro_data import SpectroData
364
+ from osekit.core.spectro_data import SpectroData
366
365
  import matplotlib.pyplot as plt
367
366
 
368
367
  sd = SpectroData(...) # See SpectroData documentation
@@ -377,14 +376,14 @@ can be provided to the ``SpectroData.plot()`` method to specify an Axes in which
377
376
  Custom frequency scales
378
377
  """""""""""""""""""""""
379
378
 
380
- The y-axis of the spectrograms can be parametrized thanks to the :class:`osekit.core_api.frequency_scale.Scale` class.
379
+ The y-axis of the spectrograms can be parametrized thanks to the :class:`osekit.core.frequency_scale.Scale` class.
381
380
 
382
- The custom ``Scale`` is made of ``ScalePart`` (:class:`osekit.core_api.frequency_scale.ScalePart`). Each ``ScalePart``
381
+ The custom ``Scale`` is made of ``ScalePart`` (:class:`osekit.core.frequency_scale.ScalePart`). Each ``ScalePart``
383
382
  correspond to a given frequency range on a given area of the y-axis:
384
383
 
385
384
  .. code-block:: python
386
385
 
387
- from osekit.core_api.frequency_scale import Scale, ScalePart
386
+ from osekit.core.frequency_scale import Scale, ScalePart
388
387
 
389
388
  scale = Scale(
390
389
  [
@@ -424,7 +423,7 @@ The resulting figure presents the full-scale spectrogram at the top (from 0 to 7
424
423
  LTAS Data
425
424
  ^^^^^^^^^
426
425
 
427
- OSEkit provides the :class:`osekit.core_api.ltas_data.LTASData` class for computing and plotting LTAS (**L**\ ong-\ **T**\ erm **A**\ verage **S**\ pectrum).
426
+ OSEkit provides the :class:`osekit.core.ltas_data.LTASData` class for computing and plotting LTAS (**L**\ ong-\ **T**\ erm **A**\ verage **S**\ pectrum).
428
427
 
429
428
  LTAS are suitable when a spectrum is computed over a very long time and that the spectrum matrix time dimension reach a really high value.
430
429
  In that case, time bins can be averaged to form a LTAS, which time resolution is lower than that of the original spectrum.
@@ -435,7 +434,7 @@ The visualization below depicts the process: the LTAS is computed with a target
435
434
  Yellow rectangles depict the audio data (the x-axis being the time axis), and the number in the lower right
436
435
  corner depicts the number of time bins in the spectrum matrix for this audio data.
437
436
  The audio is recursively split in ``n_bins`` parts (it is split in 3 in the
438
- representation instead of 3000 for clarity purposes) until the number of time bins in the matrix gets below ``n_bins``.
437
+ representation instead of 3000 for clarity purposes) until the number of time bins in the spectrum gets below ``n_bins``.
439
438
  Then, these spectrum parts are computed (hatched rectangles) and averaged across the time axis (filled rectangles).
440
439
 
441
440
  .. image:: _static/ltas/ltas.gif
@@ -454,4 +453,4 @@ should be provided:
454
453
  ltas.plot()
455
454
  plt.show()
456
455
 
457
- A ``SpectroData`` object can be turned into a ``LTASData`` thanks to the :meth:`osekit.core_api.ltas_data.LTASData.from_spectro_data` method.
456
+ A ``SpectroData`` object can be turned into a ``LTASData`` thanks to the :meth:`osekit.core.ltas_data.LTASData.from_spectro_data` method.