britekit 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

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.

Potentially problematic release.


This version of britekit might be problematic. Click here for more details.

Files changed (46) hide show
  1. britekit/__about__.py +1 -1
  2. britekit/cli.py +6 -1
  3. britekit/commands/__init__.py +2 -1
  4. britekit/commands/_analyze.py +37 -11
  5. britekit/commands/_audioset.py +8 -8
  6. britekit/commands/_calibrate.py +8 -8
  7. britekit/commands/_ckpt_ops.py +6 -6
  8. britekit/commands/_db_add.py +12 -12
  9. britekit/commands/_db_delete.py +15 -15
  10. britekit/commands/_embed.py +4 -4
  11. britekit/commands/_ensemble.py +7 -7
  12. britekit/commands/_extract.py +158 -19
  13. britekit/commands/_find_dup.py +5 -5
  14. britekit/commands/_inat.py +4 -4
  15. britekit/commands/_init.py +1 -1
  16. britekit/commands/_pickle.py +13 -7
  17. britekit/commands/_plot.py +26 -26
  18. britekit/commands/_reextract.py +6 -6
  19. britekit/commands/_reports.py +22 -22
  20. britekit/commands/_search.py +12 -12
  21. britekit/commands/_train.py +6 -6
  22. britekit/commands/_tune.py +13 -13
  23. britekit/commands/_wav2mp3.py +2 -2
  24. britekit/commands/_xeno.py +7 -7
  25. britekit/commands/_youtube.py +3 -3
  26. britekit/core/analyzer.py +43 -13
  27. britekit/core/audio.py +14 -14
  28. britekit/core/augmentation.py +24 -0
  29. britekit/core/data_module.py +2 -2
  30. britekit/core/dataset.py +1 -4
  31. britekit/core/plot.py +8 -8
  32. britekit/core/predictor.py +51 -23
  33. britekit/core/reextractor.py +6 -6
  34. britekit/core/util.py +44 -8
  35. britekit/models/base_model.py +0 -1
  36. britekit/occurrence_db/occurrence_data_provider.py +13 -13
  37. britekit/testing/per_recording_tester.py +2 -2
  38. britekit/training_db/extractor.py +65 -30
  39. britekit/training_db/training_data_provider.py +1 -1
  40. britekit/training_db/training_db.py +97 -100
  41. britekit-0.1.5.dist-info/METADATA +299 -0
  42. {britekit-0.1.3.dist-info → britekit-0.1.5.dist-info}/RECORD +45 -45
  43. britekit-0.1.3.dist-info/METADATA +0 -290
  44. {britekit-0.1.3.dist-info → britekit-0.1.5.dist-info}/WHEEL +0 -0
  45. {britekit-0.1.3.dist-info → britekit-0.1.5.dist-info}/entry_points.txt +0 -0
  46. {britekit-0.1.3.dist-info → britekit-0.1.5.dist-info}/licenses/LICENSE.txt +0 -0
@@ -0,0 +1,299 @@
1
+ Metadata-Version: 2.4
2
+ Name: britekit
3
+ Version: 0.1.5
4
+ Summary: Core functions for bioacoustic recognizers.
5
+ Project-URL: Documentation, https://github.com/jhuus/BriteKit#readme
6
+ Project-URL: Issues, https://github.com/jhuus/BriteKit/issues
7
+ Project-URL: Source, https://github.com/jhuus/BriteKit
8
+ Author-email: Jan Huus <jhuus1@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE.txt
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Programming Language :: Python
13
+ Classifier: Programming Language :: Python :: 3.8
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: Implementation :: CPython
19
+ Classifier: Programming Language :: Python :: Implementation :: PyPy
20
+ Requires-Python: >=3.8
21
+ Requires-Dist: click<8.3,>=8.1
22
+ Requires-Dist: librosa<2.0,>=0.10
23
+ Requires-Dist: lightning<2.6,>=2.5
24
+ Requires-Dist: matplotlib<3.11,>=3.8
25
+ Requires-Dist: numpy<2.4,>=2.0
26
+ Requires-Dist: omegaconf<2.4,>=2.3
27
+ Requires-Dist: onnx<2.0,>=1.18
28
+ Requires-Dist: pandas<2.3,>=2.0
29
+ Requires-Dist: pyinaturalist<1.0,>=0.20
30
+ Requires-Dist: pytorch-lightning<2.6,>=2.5
31
+ Requires-Dist: scipy<2.0,>=1.13
32
+ Requires-Dist: soundfile<1.0,>=0.13
33
+ Requires-Dist: tensorboard<3.0,>=2.19
34
+ Requires-Dist: timm<2.0,>=1.0.17
35
+ Requires-Dist: torch<2.9,>=2.5
36
+ Requires-Dist: torchaudio<2.9,>=2.5
37
+ Requires-Dist: yt-dlp>=2025.6.25
38
+ Description-Content-Type: text/markdown
39
+
40
+ # BriteKit
41
+
42
+ -----
43
+
44
+ ## Getting Started
45
+
46
+ - [Introduction](#introduction)
47
+ - [License](#license)
48
+ - [Installation](#installation)
49
+ - [Configuration](#configuration)
50
+ - [Downloading Recordings](#downloading-recordings)
51
+ - [Managing Training Data](#managing-training-data)
52
+ - [Training](#training)
53
+ - [Testing](#testing)
54
+ - [Tuning](#tuning)
55
+ - [Ensembling](#ensembling)
56
+ - [Calibrating](#calibrating)
57
+
58
+ ## More Information
59
+
60
+ - [Spectrograms](#spectrograms)
61
+ - [Backbones and Classifier Heads](#backbones-and-classifier-heads)
62
+ - [Metrics (PR-AUC and ROC-AUC)](#metrics-pr-auc-and-roc-auc)
63
+ - [Data Augmentation](#data-augmentation)
64
+ - [Development Environment](#development-environment)
65
+
66
+ ## Reference Guides
67
+
68
+ - [Command Reference](https://github.com/jhuus/BriteKit/blob/master/command-reference.md)
69
+ - [Command API Reference](https://github.com/jhuus/BriteKit/blob/master/command-api-reference.md)
70
+ - [General API Reference](https://github.com/jhuus/BriteKit/blob/master/api-reference.md)
71
+ - [Configuration Reference](https://github.com/jhuus/BriteKit/blob/master/config-reference.md)
72
+
73
+ # Getting Started
74
+
75
+ -----
76
+
77
+ ## Introduction
78
+ BriteKit (Bioacoustic Recognizer Technology Kit) is a Python package that facilitates the development of bioacoustic recognizers using deep learning.
79
+ It provides a command-line interface (CLI) as well as a Python API, to support functions such as:
80
+ - downloading recordings from Xeno-Canto, iNaturalist, and YouTube (optionally using Google Audioset metadata)
81
+ - managing training data in a SQLite database
82
+ - training models
83
+ - testing, tuning and calibrating models
84
+ - reporting
85
+ - deployment and inference
86
+
87
+ To view a list of BriteKit commands, type `britekit --help`. You can also get help for individual commands, e.g. `britekit train --help` describes the `train` command.
88
+ When accessing BriteKit from Python, the `britekit.commands` namespace contains a function for each command, as documented [here](command-api-reference.md).
89
+ The classes used by the commands can also be accessed, and are documented [here](api-reference.md).
90
+ ## License
91
+ BriteKit is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
92
+ ## Installation
93
+ It is best to install BriteKit in a virtual environment, such as a [Python venv](https://docs.python.org/3/library/venv.html). Once you have that set up, install the BriteKit package using pip:
94
+ ```console
95
+ pip install britekit
96
+ ```
97
+ In Windows environments, you then need to uninstall and reinstall PyTorch:
98
+ ```
99
+ pip uninstall -y torch torchvision torchaudio
100
+ pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
101
+ ```
102
+ Note that cu126 refers to CUDA 12.6.\
103
+ Once BriteKit is installed, initialize a working environment using the `init` command:
104
+ ```console
105
+ britekit init --dest=<directory path>
106
+ ```
107
+ This creates the directories needed and installs sample files. If you omit `--dest`, it will create
108
+ directories under the current working directory.
109
+ ## Configuration
110
+ Configuration parameters are documented [here](config-reference.md). After running `britekit init`, the file `yaml/base_config.yaml` contains all parameters in YAML format.
111
+ Most CLI commands have a `--config` argument that allows you to specify the path to a YAML file that overrides selected parameters. For example, when running the [train](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-train) command,
112
+ you could provide a YAML file containing the following:
113
+ ```
114
+ train:
115
+ model_type: "effnet.4"
116
+ learning_rate: .002
117
+ drop_rate: 0.1
118
+ num_epochs: 20
119
+ ```
120
+ This overrides the default values for `model_type`, `learning_rate`, `drop_rate` and `num_epochs`. When using the API, you can update configuration parameters like this:
121
+ ```
122
+ import britekit as bk
123
+ cfg = bk.get_config()
124
+ cfg.train.model_type = "effnet.4"
125
+ ```
126
+ ## Downloading Recordings
127
+ The [inat](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-inat), [xeno](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-xeno) and [youtube](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-youtube) commands make it easy to download recordings from Xeno-Canto, iNaturalist and YouTube. For iNaturalist it is important to provide the scientific name. For example, to download recordings of the American Green Frog (lithobates clamitans), type:
128
+ ```
129
+ britekit inat --name "lithobates clamitans" --output <output-path>
130
+ ```
131
+ For Xeno-Canto, use `--name` for the common name or `--sci` for the scientific name. For YouTube, specify the ID of the corresponding video. For example, specify `--id K_EsxukdNXM` to download the audio from https://www.youtube.com/watch?v=K_EsxukdNXM.
132
+
133
+ The [audioset](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-audioset) command lets you download using [Google Audioset](https://research.google.com/audioset/), which is metadata that classifies sounds in YouTube videos. Audioset was released in March 2017, so any videos uploaded later than that are not included. Also, some videos that are tagged in Audioset are no longer available. Type `britekit audioset --help` for more information.
134
+ ## Managing Training Data
135
+ Once you have a collection of recordings, the steps to prepare it for training are:
136
+ 1. Extract spectrograms from recordings and insert them into the training database.
137
+ 2. Curate the training spectrograms.
138
+ 3. Create a pickle file from the training data.
139
+ Then provide the path to the pickle file when running training.
140
+
141
+ Suppose we have a folder called `recordings/cow`. To generate spectrograms and insert them into the training database, we could type `britekit extract-all --name Cow --dir recordings/cow`. This will create a SQLite database in `data/training.db` and populate it with spectrograms using the default configuration.
142
+ To browse the database, you can use [DB Browser for SQLite](https://sqlitebrowser.org/), or a similar application.
143
+ That will reveal the following tables:
144
+ - Class: classes that the recognizer will be trained to identify, e.g. American Robin
145
+ - Category: categories such as Bird, Mammal or Amphibian
146
+ - Source: sources of recordings, e.g. Xeno-Canto or iNaturalist.
147
+ - Recording: individual recordings
148
+ - Segment: fixed-length sections of recordings
149
+ - SpecGroup: groups of spectrograms that share spectrogram parameters
150
+ - SpecValue: spectrograms, each referencing a Segment and SpecGroup
151
+ - SegmentClass: associations between Segment and Class, to identify the classes that occur in a segment
152
+
153
+ There are commands to add or delete database records, e.g. [add-cat](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-add-cat) and [del-cat](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-del-cat) to add or delete a category record. In addition, specifying the `--cat` argument with the [extract-all](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-extract-all) or [extract-by-image](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-extract-by-image) commands will add the required category record if it does not exist. You can plot database spectrograms using [plot-db](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-plot-db), or plot spectrograms for recordings using [plot-rec](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-plot-rec) or [plot-dir](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-plot-dir). Once you have a folder of spectrogram images, you can manually delete or copy some of them. The [extract-by-image](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-extract-by-image) command will then extract only the spectrograms corresponding to the given images. Similarly, the [del-seg](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-del-seg) command will delete segments, and their spectrograms, corresponding to the images in a directory.
154
+
155
+ It is important to tune spectrogram parameters such as height, width, maximum/minimum frequency and window length for your specific application. This is discussed more in the [tuning](#Tuning) section below, but for now be aware that you can set specific parameters in a YAML file to pass to an extract or plot command. For example:
156
+ ```
157
+ audio:
158
+ min_freq: 350
159
+ max_freq: 4000
160
+ win_length: .08
161
+ spec_height: 192
162
+ spec_width: 256
163
+ ```
164
+ The FFT window length is specified as a fraction of a second: .08 seconds in this example. That way the real window length does not vary if you change the sampling rate. As a rule of thumb, the sampling rate should be about 2.1 times the maximum frequency. Before training your first model, it is advisable to examine some spectrogram images and choose settings that seem reasonable as a starting point. For example, the frequency range needed for your application may be greater or less than the defaults.
165
+
166
+ The SpecGroup table allows you to easily experiment with different spectrogram settings. Running [extract-all](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-extract-all) or [extract-by-image](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-extract-by-image) creates spectrograms assigned to the default SpecGroup, if none is specified. Once you have curated some training data, use the [reextract](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-reextract) command to create another set of spectrograms, assigned to a different SpecGroup. That way you can keep spectrograms with different settings for easy experimentation.
167
+ ## Training
168
+ The [pickle](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-pickle) command creates a binary pickle file (`data/training.pkl` by default), which is the source of training data for the [train](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-train) command. Reading a binary file is much faster than querying the database, so this speeds up the training process. Also, this provides a simple way to select a SpecGroup, and/or a subset of classes for training. For training, you should always provide a config file to override some defaults. Here is an expanded version of the earlier example:
169
+ ```
170
+ train:
171
+ train_pickle: "data/low_freq.pkl"
172
+ model_type: "effnet.4"
173
+ head_type: "basic_sed"
174
+ learning_rate: .002
175
+ drop_rate: 0.1
176
+ drop_path_rate: 0.1
177
+ val_portion: 0.1
178
+ num_epochs: 20
179
+ ```
180
+ The `model_type` parameter can be "timm.x" for any model x supported by [timm](https://github.com/huggingface/pytorch-image-models). However, many bioacoustic recognizers benefit from a smaller model than typical timm models. Therefore BriteKit provides a set of scalable models, such as "effnet.3" and "effnet.4", where larger numbers indicate larger models. The scalable models are:
181
+ | Model | Original Name | Comments | Original Paper |
182
+ |---|---|---|---|
183
+ | dla | DLA | Slow and not good for large models, but works well for some very small models. | [here](https://arxiv.org/abs/1707.06484) |
184
+ | effnet | EfficientNetV2 | Medium speed, widely used, useful for all sizes. | [here](https://arxiv.org/abs/2104.00298) |
185
+ | gernet | GerNet | Fast, useful for all but the smallest models. | [here](https://arxiv.org/abs/2006.14090) |
186
+ | hgnet | HgNetV2| Fast, useful for all but the smallest models. | not published |
187
+ | vovnet | VovNet | Medium-fast, useful for all sizes. | [here](https://arxiv.org/abs/1904.09730) |
188
+
189
+ For very small models, say with less than 10 classes and just a few thousand training spectrograms, DLA and VovNet are good candidates. As model size increases, DLA becomes slower and less appropriate. Of course, it is best to try different models and model sizes to see which works best for your application.
190
+
191
+ If `head_type` is not specified, BriteKit uses the default classifier head defined by the model. However, you can also specify any of the following head types:
192
+ | Head Type | Description |
193
+ |---|---|
194
+ | basic | A basic non-SED classifier head. |
195
+ | effnet | The classifier head used in EfficientNetV2. |
196
+ | hgnet | The classifier head used in HgNetV2. |
197
+ | basic_sed | A basic SED head. |
198
+ | scalable_sed | The basic_sed head can be larger than desired, and this one allows you to control the size. |
199
+
200
+ Specifying `head_type="effnet"` is sometimes helpful for other models such as DLA and VovNet. See the discussion of [Backbones and Classifier Heads](#backbones-and-classifier-heads) below for more information.
201
+
202
+ You can specify `val_portion` > 0 to run validation on a portion of the training data, or `num_folds` > 1 to run k-fold cross-validation. In the latter case, training output will be in logs/fold-0/version_x etc. Otherwise it is under logs/version_x. Output from the first training run is saved in version_0, and the version number is incremented in subsequent runs. To view graphs of the loss and learning rate, type `tensorboard --logdir <log directory>`. This will launch an embedded web server and display a URL that you can use to view graphs such as the learning rate in a web browser.
203
+
204
+ ## Testing
205
+ To run a test, you need to annotate a set of test recordings, analyze them with your model or ensemble, and then run the [rpt-test](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-rpt-test) command. Annotations must be saved in a CSV file with a defined format. For initial testing and tuning it is best to annotate each relevant sound (per-segment), but for later usage you may wish to use per-block (e.g. minute) or per-recording annotations. Per-recording annotations are defined in a CSV file with these columns:
206
+ | Column | Description |
207
+ |---|---|
208
+ | recording | Just the stem of the recording name, e.g. XC12345, not XC12345.mp3. |
209
+ | classes | Defined classes found in the recording, separated by commas. For example: AMCR,BCCH,COYE.
210
+
211
+ Per-block annotations are defined in a CSV file with these columns:
212
+ | Column | Description |
213
+ |---|---|
214
+ | recording | Just the stem of the recording name, as above. |
215
+ | block | 1 for the first block (e.g. minute), 2 for the second, etc. |
216
+ | classes | Defined classes found in that block, if any, separated by commas.
217
+
218
+ Per-segment annotations are recommended, and are defined in a CSV file with these columns:
219
+ | Column | Description |
220
+ |---|---|
221
+ | recording | Just the stem of the recording name, as above. |
222
+ | class | Identified class.
223
+ | start_time | Where the sound starts, in seconds from the start of the recording.
224
+ | end_time | Where the sound ends, in seconds from the start of the recording.
225
+
226
+ Use the [analyze](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-analyze) command to analyze the recordings with your model or ensemble. For testing, be sure to specify `--min_score 0`. That way all predictions will be saved, not just those above a particular threshold, which is important when calculating metrics. See [Metrics (PR-AUC and ROC-AUC)](#metrics-pr-auc-and-roc-auc) for more information.
227
+
228
+ It's usually best for a test to consist of a single directory of recordings, containing a file called annotations.csv. If that directory is called recordings and you run analyze specifying `--output recordings/labels`, you could generate test reports as follows:
229
+ ```
230
+ britekit rpt-test -a recordings/annotations.csv -l labels -o <output-dir>
231
+ ```
232
+ If your annotations were per-block or per-recording, you would specify the `--granularity block` or `--granularity recording` argument (`--granularity segment` is the default).
233
+ ## Tuning
234
+ Before tuning your model, you need to create a good test, as described in the previous section. Then you can use the [tune](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-tune) command to find optimal settings for a given test. If you are only tuning inference parameters, you can run many iterations very quickly, since no training is needed. To tune training hyperparameters, many training runs are needed, which takes longer. You can also use the [tune](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-tune) command to tune audio and spectrogram settings. In that case, every iteration extracts a new set of spectrograms, which takes even longer.
235
+
236
+ Here is a practical approach:
237
+ 1. Review spectrogram plots with different settings, especially `spec_duration`, `spec_width`, `spec_height`, `min_frequency`, `max_frequency` and `win_length`. Then choose reasonable-looking initial settings. For example, if all the relevant sounds fall between 1000 and 5000 Hz, set min and max frequency accordingly.
238
+ 2. Tune the main training hyperparameters, especially `model_type`, `head_type` and `num_epochs`.
239
+ 3. Tune the audio/spectrogram hyperparameters.
240
+ 4. Tune data augmentation hyperparameters, which are described in the [Data Augmentation](#data-augmentation) section below.
241
+ 5. Tune the inference `audio_power` hyperparameter.
242
+ 6. Perform a second tuning pass, starting at step 2 above.
243
+
244
+ This usually leads to a substantial improvement in scores (see [Metrics (PR-AUC and ROC-AUC)](#metrics-pr-auc-and-roc-auc). If you are using a SED classifier head, it is also worth tuning `segment_len` and `overlap`.
245
+
246
+ To run the [tune](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-tune) command, you would typically use a config YAML file as described earlier, plus a special tuning YAML file, as in this example:
247
+ ```
248
+ - name: spec_width
249
+ type: int
250
+ bounds:
251
+ - 256
252
+ - 512
253
+ step: 64
254
+ ```
255
+ This gives the name of the parameter to tune, its data type, and the bounds and step sizes to try. In this case, we want to try `spec_width` values of 256, 320, 384, 448 and 512. You can also tune multiple parameters at the same time, by simply appending more definitions similar to this one. Parameters that have a choice of defined values rather than a range are specified like this:
256
+ ```
257
+ - name: head_type
258
+ type: categorical
259
+ choices:
260
+ - "effnet"
261
+ - "hgnet"
262
+ - "basic_sed"
263
+ ```
264
+ When running the [tune](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-tune) command, you can ask it to test all defined combinations based on the input, or to test a random sample. To try 100 random combinations, add the argument `--tries 100`. To tune audio/spectrogram parameters, add the `--extract` argument. To tune inference only, add the `--notrain` argument.
265
+
266
+ Training is non-deterministic, and results for a given group of settings can vary substantially across multiple training runs. Therefore it is important to specify the `--runs` argument, indicating how often training should be run for a given set of values.
267
+
268
+ As an example, to find the best `spec_width` value, we could type a command like this:
269
+ ```
270
+ britekit tune -c yaml/my_train.yml -p yaml/my_tune.yml -a my_test/annotations.csv -o output/tune-spec-width --runs 5 --extract
271
+ ```
272
+ This will perform an extract before each trial, and use the average score from 5 training runs in each case. Scores will be based on the given test, using macro-averaged ROC-AUC, although this can be changed with the `--metric` argument.
273
+
274
+ ## Ensembling
275
+ Combining multiple checkpoints in an ensemble is a quick and easy way to improve classifier results. This can be especially powerful when different model architectures are used, but even with the same model type and training protocol, ensembling almost always improves results.
276
+
277
+ Using an ensemble is very easy - just copy all the ensemble checkpoint files to the data/ckpt directory (or whichever directory is specified by the `ckpt_folder` configuration parameter). With too many models in an ensemble, inference will become very slow, and at some point there is no benefit to adding more checkpoints anyway. In most cases an ensemble of 3-6 checkpoints is best.
278
+
279
+ Given a per-segment test and a directory containing checkpoints, use the [ensemble](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-ensemble) command to find the highest-scoring ensemble of a given size.
280
+
281
+ ## Calibrating
282
+ By default, the scores or predictions generated by your models may not align well with probabilities. Ideally, a score of .8 should be correct about 80% of the time, but for a given ensemble it might actually be correct 70% or 90% of the time. Aligning output predictions with probabilities is called calibration.
283
+
284
+ Use the [calibrate](https://github.com/jhuus/BriteKit/blob/master/command-reference.md#britekit-calibrate) command to calibrate your model or ensemble. Given a per-segment test and inference output it will generate a graph showing the uncalibrated and calibrated scores. Calibrated scores are based on a corresponding scaling coefficient and intercept. To use these values, set the `scaling_coefficient` and `scaling_intercept` parameters in your inference configuration.
285
+
286
+ # More Information
287
+
288
+ -----
289
+
290
+ ## Spectrograms
291
+ TBD
292
+ ## Backbones and Classifier Heads
293
+ TBD
294
+ ## Metrics (PR-AUC and ROC-AUC)
295
+ TBD
296
+ ## Data Augmentation
297
+ TBD
298
+ ## Development Environment
299
+ TBD
@@ -1,20 +1,20 @@
1
- britekit/cli.py,sha256=nnrCMfw3-1GJ4rKFpqTLu8JcBGxTocMn7nwzU4OSaew,3080
2
- britekit/core/analyzer.py,sha256=0OYVxuwYx_R36MZwIlVgPMWQ1udZ_tdgYODJyEVDJm0,5604
3
- britekit/core/audio.py,sha256=2WINXunumjcbFlTd0Yngg8MmBy9O3dQWGosVCJmkryI,16397
4
- britekit/core/augmentation.py,sha256=5_wyB-6gt7uM68Zl-rO_fPu1D6tlsd2m5oWhA6l0W9Q,5721
1
+ britekit/cli.py,sha256=J2bsfbbykQJ8FuZ2a_4Nh0Hm1ytGOuEDDtewh6gh_Is,3155
2
+ britekit/core/analyzer.py,sha256=x2d2gu3TWV0ebFk3FYNMrMqT3PZuMgL_F0tUsxjiAII,6584
3
+ britekit/core/audio.py,sha256=X9e6n1O9zD1IlRIG5co_Nf_CTeUvWSDGL9z13TBnx64,16357
4
+ britekit/core/augmentation.py,sha256=uS2jOAHdrEpAlZIWZH8c2lmvqIlQ9DfzkgjjgUMUi0k,6673
5
5
  britekit/core/base_config.py,sha256=uRHlfV_ni1Pj93_f4H0Jj87ytt08zcKxgBBE_Pk_W6o,8831
6
6
  britekit/core/config_loader.py,sha256=mDmLwKYXsWb9FRk12q9Rj2rVdvbCVCI3QTdsZSnUBCY,1339
7
- britekit/core/data_module.py,sha256=0DkOZTTGymZ7JjukucDuAq-nXS_KPhqV7KFPhmMoQDw,9105
8
- britekit/core/dataset.py,sha256=R_NDaFljl4IMKxGWWWm1PMkYCcfrEaiJU1NrVswt6eM,5801
7
+ britekit/core/data_module.py,sha256=zb-8x97SvmBc02hmmD1S5_Xi2TSBljkVZs11x1-snz8,9101
8
+ britekit/core/dataset.py,sha256=dECrwaGvC2WRHpaJTwsp5DWji9kD_DJpN2exMGJlrps,5650
9
9
  britekit/core/exceptions.py,sha256=ti_ve7ZdhDmzgTuspXXqyw__SUt5NoAXGEwoe3agPU8,443
10
10
  britekit/core/pickler.py,sha256=72hiqOiIbBeXvHGwmHAOODr9wGdyBwj4NUYecxIhtCE,5775
11
- britekit/core/plot.py,sha256=H-SB2ooe2LT0j1KoXs2PgT3t05oAB4CWkYX_HvGMO_c,5329
12
- britekit/core/predictor.py,sha256=9Heue3ku9rw4OfE0SWuWLKBLW-aMw8PXqWlBB4GUCbw,22911
13
- britekit/core/reextractor.py,sha256=UqWLapReNhEne0dykBCN_UIpLOHkZxJMw4RAlG70nzI,8393
11
+ britekit/core/plot.py,sha256=BmFZ08B2WlrKvPis-6B1irAJFaLXyIRD3fD_pOHjDAQ,5309
12
+ britekit/core/predictor.py,sha256=geWSLUKdAYwn2TqxDKrqzNjuZoCu4J_CN9ABM8FqcEo,23899
13
+ britekit/core/reextractor.py,sha256=pxVCCBH4XKWOY8Le2wTfetrRGvL27eEFUP3ElrikNuU,8381
14
14
  britekit/core/trainer.py,sha256=SrAYZEmFa4Ba5Fa1wuY-hO8dCW9IF-yIOq9qs0kIYkU,6513
15
15
  britekit/core/tuner.py,sha256=LoQi7jwIwqv2DY7MgupG32PdD6QiuneQrgRgxq8ANlk,16422
16
- britekit/core/util.py,sha256=JKT-yqFPA9FBMT1-YsGvNE8E21242MYAsXvRGSgTNYg,19163
17
- britekit/models/base_model.py,sha256=PpKbN99BYgzh4M1AMDGNjXb4QPFi1KNXq6_bfYRGJTY,16917
16
+ britekit/core/util.py,sha256=hEcz2nTncohbm_E8dRsg6NRfQRw6XwzkAXV27S-bsoE,20126
17
+ britekit/models/base_model.py,sha256=jVYSIrXAmeAer6MTFg177YoDBn00_HzluDdEAZH1qpQ,16881
18
18
  britekit/models/dla.py,sha256=ALMY997AbERN7-sHqQuE5e43llRjpUDPZSFGL-Flv4M,3137
19
19
  britekit/models/effnet.py,sha256=e7WdZMsLPXe8jcWChk6n97c8DMV0YyGV6lDP_Jv6Wz4,3129
20
20
  britekit/models/gernet.py,sha256=7MEUZaDTfr-6oa8eE8dyDQb2LgahGBOEp1pTZSu1KOE,7022
@@ -23,16 +23,16 @@ britekit/models/hgnet.py,sha256=sgnNMpn98QI7JrytqOUzbAxngk_AIp5gKvsmu31hOzE,7125
23
23
  britekit/models/model_loader.py,sha256=wws7sWBXskcjsxEsohXz2ZdBa-DdNNp39fu9WMqz2Hc,4362
24
24
  britekit/models/timm_model.py,sha256=enGaxF-hV69Y3sn7axp8hYyL2GW2OMWwjk9gWzrGEAI,1465
25
25
  britekit/models/vovnet.py,sha256=s8z5QaGO6zPNSN0e0CrgAPYd5qLxC7FNvxe4w7ZmkM4,5504
26
- britekit/occurrence_db/occurrence_data_provider.py,sha256=1YR4Ubk1KPqLaTGp9Y8_VM-CQth1Am7X-hEl0I4ocT4,5967
26
+ britekit/occurrence_db/occurrence_data_provider.py,sha256=jj1rQCYUX5GK6SxnKN4U1o9vFwn37E7BWatI5q2ByRA,5941
27
27
  britekit/occurrence_db/occurrence_db.py,sha256=-726UfhjppeIpDQ96VPtC675suk-7yR4Vgq3qMwFurM,11219
28
28
  britekit/testing/base_tester.py,sha256=AHogaBK7wOICqtWUr6reuJK6IpV5F0HOXI2aBovXWIY,46182
29
29
  britekit/testing/per_block_tester.py,sha256=TaGzm_w_TV6JxJAxCLdEaUwychvACMbhwSw_5axVLRc,31714
30
- britekit/testing/per_recording_tester.py,sha256=7Qzb3kyMDDXc1n9MACbht1xkgeZgDlU-eQX4Jw8I7bY,21726
30
+ britekit/testing/per_recording_tester.py,sha256=MXlWvDVdBhCw1E96oESHK8ETqCBoNDlVY6lXef2KhQ4,21742
31
31
  britekit/testing/per_segment_tester.py,sha256=5zFpe8wVEEtVjthKKFRb0dwE9T0v4JIll9Tto4KDYbo,37066
32
- britekit/training_db/extractor.py,sha256=yblYTco9b-bZhBTOkGkNANOabsNo8IfQGJxPvh_eJyo,8406
33
- britekit/training_db/training_data_provider.py,sha256=V5aBjsCvrWViZ0Jv05hgcKRizcAXmqoj4q3hAHedoD8,5651
34
- britekit/training_db/training_db.py,sha256=xZqN1sMC2yFMEDm9rOrCigN3CUfUzTaTUkX3IZ_zHRc,64922
35
- britekit/__about__.py,sha256=BJUjeba3XcMD4b86TL-kBaUorobAzsMSsLBrlMCy-sQ,122
32
+ britekit/training_db/extractor.py,sha256=hAX4l4Wcao82uWyNwbzR2koyIgzCEhtMEuxkgZl0OjE,9794
33
+ britekit/training_db/training_data_provider.py,sha256=FvXsKhMqRMEwFThCclIvop1TRx8lvWHUvjCmraTcU4Y,5649
34
+ britekit/training_db/training_db.py,sha256=Wq9NoRe22Eq_s8DUaRCFXvSmsXuxopT3boEfP9PKJV8,64638
35
+ britekit/__about__.py,sha256=aK3E-kkejR98DjviEfXrfce3TWiWeCajtpyMIc_8NY8,122
36
36
  britekit/__init__.py,sha256=cE3XmXwVJ0G0TvubGysOseYighjYrLP5RzG163Fv3_I,2022
37
37
  britekit/install/data/classes.csv,sha256=OdTZ8oQdx7N-HKyhftxZStGZYsjhCy4UbanwtQJ2wBM,54
38
38
  britekit/install/data/ignore.txt,sha256=RbKvEHtUCbgRYolwR1IucClwyD3q7l2s6QuRjph-Us4,68
@@ -64,32 +64,32 @@ britekit/install/yaml/samples/tune_dropout.yaml,sha256=f3QEfPOZecjwthqzAWodI8-PX
64
64
  britekit/install/yaml/samples/tune_learning_rate.yaml,sha256=UTtpsJwO33UWW0oecGR_LV3nQPtyC1dbpkkJpGOlI68,83
65
65
  britekit/install/yaml/samples/tune_optimizer.yaml,sha256=VtGlZmMJ22gaZWJ7CPLNHRZ-8EHeB5GmxywQm1Iy1MM,73
66
66
  britekit/install/yaml/samples/tune_smooth.yaml,sha256=IZq2lohiJWVdzPl-i3aCEwEsJLmG_bg7EvyBUSI-R0o,83
67
- britekit/commands/__init__.py,sha256=mms49ChyrGj4zzeUge6bl7uiPhOMjFm37NTk23ZFmXw,1586
68
- britekit/commands/_analyze.py,sha256=CmdtqYHQOm2MFIqjSRg_OtcPXRASJ2u6if1SzGUpkrU,4987
69
- britekit/commands/_audioset.py,sha256=BqmAJq6yWpyqBYIUWt9d0khBTQRa3vgUMdCS4U0fxvA,9957
70
- britekit/commands/_calibrate.py,sha256=338dRyGRj-Bw_4wFxiANDCbo-lZgdl0OR2gD8PmLv8U,4912
71
- britekit/commands/_ckpt_ops.py,sha256=2l-eJuxGBTHtQZ2Nked82KeSbP7WIwZ-yAYuM4v4HlU,5778
72
- britekit/commands/_db_add.py,sha256=brUCb7LZVJ7XezlSmpaKilz9hYoII_DvfjhS1v64cr0,7249
73
- britekit/commands/_db_delete.py,sha256=ziqxnQhBOjHgqlu0uk6GA8A7I9FOMYcPEscmPxThAVY,14520
74
- britekit/commands/_embed.py,sha256=gTQK4YOilwsZCY2r8HhaWUZBpMkA-OEZsR5RkNV1euM,4388
75
- britekit/commands/_ensemble.py,sha256=jssoAKvKgy2KNAQ2-tIapQgo_YfywwxSnPRnIwnmC38,8427
76
- britekit/commands/_extract.py,sha256=iz9VG1KnV-d7cFliQpmWiSi6Ezt9hCm5Iur9r-XBb20,8859
77
- britekit/commands/_find_dup.py,sha256=Zig-s04BUQzeY4s7DjEQM53-e6KgCXxSw05R6BfSkNw,6350
78
- britekit/commands/_inat.py,sha256=ojTre5BCj_jmEh6x2kzNhcminLN6h5bzsYpxyrxGRdQ,4164
79
- britekit/commands/_init.py,sha256=RS7A74XVQql6tszOmROgu2P5RLlJCN7M6_-CSJe3o8E,2901
80
- britekit/commands/_pickle.py,sha256=5ZlAHlyR5Hdb4SOnJ-9qBaSZkSvi98fgkIV13KN5jSU,3485
81
- britekit/commands/_plot.py,sha256=Jhzeo7_FJxBfJWPNVZaLn9QA8w9O3nMO1HtA0C3M48Q,13075
82
- britekit/commands/_reextract.py,sha256=zth_E3IyBlrJ-ovHxzpyZntbamEDwelBZ3QrzozFwkA,3767
83
- britekit/commands/_reports.py,sha256=hSzfP_3dKYXwTaTdc8PKmzAjNVFzb9pdLhBeaP5ztTw,22366
84
- britekit/commands/_search.py,sha256=b7cIFSI3AuPhreYGO8HGqX12TKaOJ5uoc1uiqid04Mk,9988
85
- britekit/commands/_train.py,sha256=40Zdu9FZkmdA0bIuTK-oADw-4X6aMQYS1XGigheocdo,4152
86
- britekit/commands/_tune.py,sha256=CFEY08SsPF_2s_fknUHJLEsho6vL_it8NoOhB2RoVU0,7468
87
- britekit/commands/_wav2mp3.py,sha256=2Q4cjT6OhJmBPTNzGRMrDd6dSdBBufuQdjhH1V8ghLo,2167
88
- britekit/commands/_xeno.py,sha256=4qS2iXeGMl0jYvTAvhSvX0VvIlp7STlX27o273WwBHk,6165
89
- britekit/commands/_youtube.py,sha256=_u1LrwY_2GxllKd505N_2ArFMbACQ_PtVxuqUCYxFe0,2214
67
+ britekit/commands/__init__.py,sha256=nr8c8af2RJtMfdmgEmvjxswp3lCeTj39kLQ8RWisNOQ,1624
68
+ britekit/commands/_analyze.py,sha256=x8n00WkJYzd5T2h1ycoWqaxSFNwv_Qawtn0V8lSW_98,5979
69
+ britekit/commands/_audioset.py,sha256=wvkCjHJ4HpH7wW9Nm6oX-ds2X7rWQWWkYVG86tL_T6U,9941
70
+ britekit/commands/_calibrate.py,sha256=VRzNXKzr8jia4MsmhyasnAFDcv1YB9k-IJ6m615bDqQ,4896
71
+ britekit/commands/_ckpt_ops.py,sha256=tiXw4wV20wl1xQsIUtn3ghOjoOsSg0zRfu6G9c5cg9M,5741
72
+ britekit/commands/_db_add.py,sha256=rstmRtl5ahSeNC17dHqXzUjZSZulgp1g5OBtQZbmvEc,7225
73
+ britekit/commands/_db_delete.py,sha256=Lgv0L4izKYIf-ef84av2xxbTdCDXSZAEBAXrRfIVrYA,14490
74
+ britekit/commands/_embed.py,sha256=dVa_Xrapyp-a1Ah7DrCVGX0VZv3dIJkeOd1IPS7_Fm4,4380
75
+ britekit/commands/_ensemble.py,sha256=lY8fzNqrFtlbs47QNIBQx1wjkmgdDGN7Fan_IBu_tTQ,8413
76
+ britekit/commands/_extract.py,sha256=awsn5lrUJPwkUruxFvk8_SJnWC72cGHjQ7nbsMZe830,13489
77
+ britekit/commands/_find_dup.py,sha256=ue7xNT2jjWVZ2aRiuoA0ZNCUFeXcLbt3j_e59O8gYv0,6340
78
+ britekit/commands/_inat.py,sha256=3jauLzwoXyKgx3ojjg46wyW6BEB0vJeMXBHZFVUZCAI,4156
79
+ britekit/commands/_init.py,sha256=C7fBWcPftuflxcwLAblLbIshKAYZcx90JSur52D-DJw,2899
80
+ britekit/commands/_pickle.py,sha256=8FCmureh_dHTuMRfuHdAT6Nixu31ZPXG74aw9-eY-E8,3620
81
+ britekit/commands/_plot.py,sha256=3OgMDz3xUuNuuVmQdA8Hg4ATiDXxB6FjG4F9gnVRU5M,13032
82
+ britekit/commands/_reextract.py,sha256=IG-62d65c437maGKzTcRBtZmdQrf8kJjk5sIX-Ofmb4,3755
83
+ britekit/commands/_reports.py,sha256=JEjMiMFPYtNSneOh8vnPugUA_2mfv9eTOH9HrQQRPBo,22332
84
+ britekit/commands/_search.py,sha256=RzTVl6Pag4XQbEuY0Ovpgsq51SAZ9aOs3jwl-QLeaMQ,9964
85
+ britekit/commands/_train.py,sha256=JlxyjvnN3RGznpQATgkXwkvDwGCvvMK_z8JXswH0v84,4078
86
+ britekit/commands/_tune.py,sha256=z8yeah5pw7pmqviLjNU7jao17Uqt3t8vWYATA1lH_ao,7415
87
+ britekit/commands/_wav2mp3.py,sha256=FQ7YVY4W7ZdA1wd6z7UEqBKEKvi0hwiuXiua-YRDZik,2163
88
+ britekit/commands/_xeno.py,sha256=A8OGnfNcRyM6ah4PmWX5KiZEdQvDofshItA4mUyGCE4,6151
89
+ britekit/commands/_youtube.py,sha256=MoRz8Bq_Eg2kpORGKSZxCN2PyXjMhP_mezSV2w3Dmgk,2208
90
90
  britekit/core/__init__.py,sha256=QcjcFyvO5KqJLF_HBeqiCk925uU5jTUjIV5lJix9XY4,556
91
- britekit-0.1.3.dist-info/METADATA,sha256=ON7_OiyYD57djRMo7nI3NtoGaUr7s8YHQyoYRV10HOc,18552
92
- britekit-0.1.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
93
- britekit-0.1.3.dist-info/entry_points.txt,sha256=ycnPy5DLX14RTf7lKfkQAVyIf1B1zTL1gMsHm455wmg,46
94
- britekit-0.1.3.dist-info/licenses/LICENSE.txt,sha256=kPoHm6iop8-CUa_720Tt8gqyvLD6D_7218u1hCCpErk,1092
95
- britekit-0.1.3.dist-info/RECORD,,
91
+ britekit-0.1.5.dist-info/METADATA,sha256=92Ze4h2wySZ3IwcoptgYtCCYWmrGEEydDkefImwTUyc,22545
92
+ britekit-0.1.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
93
+ britekit-0.1.5.dist-info/entry_points.txt,sha256=ycnPy5DLX14RTf7lKfkQAVyIf1B1zTL1gMsHm455wmg,46
94
+ britekit-0.1.5.dist-info/licenses/LICENSE.txt,sha256=kPoHm6iop8-CUa_720Tt8gqyvLD6D_7218u1hCCpErk,1092
95
+ britekit-0.1.5.dist-info/RECORD,,