BatBot API

BatBot is the machine learning interface for the Kitware BatAI project. This page specifies the Python API to interact with all of the algorithms and machine learning models that have been pretrained for inference in a production environment.

Environment Variables

The BatBot API and CLI have two environment variables (envars) that allow you to configure global settings and configurations.

• VERBOSE (default: not set)

  A verbosity flag that can be set to turn on debug logging. Defaults to “not set”, which translates to no debug logging. Setting this value to anything will turn on debug logging (e.g., VERBOSE=1).

Spectrogram

batbot.spectrogram.calculate_astar_grid_and_endpoints(segment, index, segmentmask, peak, canvas, kernel=7, output_path='.')

batbot.spectrogram.calculate_harmonic_and_echo_flags(original, index, segmentmask, harmonic, echo, canvas, kernel=5, output_path='.')

batbot.spectrogram.calculate_mean_within_stddev_window(values, window)

batbot.spectrogram.calculate_window_and_stride(stft_db, duration, window_size_ms=12, strides_per_window=3, time_vec=None)

batbot.spectrogram.compute(*args, **kwargs)

batbot.spectrogram.compute_wrapper(wav_filepath, out_file_stem=None, output_folder=None, fast_mode=False, force_overwrite=False, quiet=False, annotations=None, bitdepth=16, mask_secondary_effects=False, plot_uncompressed_amplitude=False, include_original_sr=False, time_buffer_ms=1.0, debug=False, **kwargs)

Compute the spectrograms for a given input WAV and saves them to disk.

If a given spectrogram has already been rendered to disk, it will not be recomputed.

Parameters:

• wav_filepath (str) – WAV filepath (relative or absolute) to compute spectrograms for.

• ext (str, optional) – The file extension of the resulting spectrogram files. If this value is not specified, it will use the same extension as wav_filepath. Passed as input to batbot.spectrogram.spectrogram_filepath(). Defaults to None.

• **kwargs – keyword arguments passed to batbot.spectrogram.spectrogram_grid()

Returns:

• the original WAV file’s sample rate.

• the original WAV file’s duration in seconds.

• tuple of spectrogram’s (width, height) in pixels

• tuple of spectrogram’s (min, max) frequency

• list of spectrogram filepaths, split by 50k horizontal pixels

Return type:

tuple ( int, float, tuple (int), list ( str ) )

batbot.spectrogram.create_coarse_candidates(stft_db, window, stride, threshold_stddev=3.0, min_band_idx=None)

batbot.spectrogram.create_contour_debug_canvas(segment, index, output_path='.')

batbot.spectrogram.create_masked_image(stft_db, costs, kernel=11)

batbot.spectrogram.extract_contour_keypoints(path, canvas, index, peak, contour_smoothing_sigma=5, output_path='.')

batbot.spectrogram.extract_contour_path(grid, begin, end, canvas, index, output_path='.')

batbot.spectrogram.filter_candidates_to_ranges(stft_db, candidates, window=16, skew_stddev=2.0, area_percent=0.1, min_band_idx=None, output_path=None, fast_mode=False, quiet=False)

batbot.spectrogram.filter_contour(segment, index, med_db=None, std_db=None, kernel=5, output_path='.')

batbot.spectrogram.find_contour_and_peak(segment, index, max_locations, peak_db=None, peak_db_std=None, threshold_std=2.0, sigma=5, output_path='.', threshold=None)

batbot.spectrogram.find_contour_connected_components(segment, index, locations, sequence=4, output_path='.')

batbot.spectrogram.find_echo(segmentmask, index, kernel=15, output_path='.')

batbot.spectrogram.find_harmonic(segmentmask, index, freq_offset, kernel=15, output_path='.')

batbot.spectrogram.find_max_locations(data)

batbot.spectrogram.gain_stft(stft_db, gain_db=120.0, autogain_stddev=5.0, max_band_idx=None)

batbot.spectrogram.generate_waveplot(waveform, stft_db, hop_length=16, size_multiplier=4, bg_color=(240, 255, 255), fg_color=(237, 149, 100), zero_color=(0, 0, 0))

batbot.spectrogram.get_debug_path(output_folder, wav_filepath, enabled, purge=True, ensure=True)

batbot.spectrogram.get_islands(data)

batbot.spectrogram.get_slope_islands(slope_flags)

batbot.spectrogram.load_stft(wav_filepath, sr=250000.0, n_fft=512, window='blackmanharris', win_length=256, hop_length=16, fast_mode=False, use_original_sr=False)

batbot.spectrogram.merge_ranges(ranges, max_val)

batbot.spectrogram.morph_open_contour(segment, index, output_path='.')

batbot.spectrogram.normalize_contour(segment, index, dtype=None, blur=True, kernel=5, output_path='.')

batbot.spectrogram.normalize_skew(skews, skew_thresh)

batbot.spectrogram.normalize_stft(data, value=1.0, dtype=None)

batbot.spectrogram.plot_chirp_candidates(stft_db, candidate_dbs, ranges, reject_idxs, output_path='.', output_filename='candidates.png')

batbot.spectrogram.plot_histogram(image, ignore_zeros=False, max_val=None, smoothing=128, min_band_idx=None, csum_threshold=0.95, output_path='.', output_filename='histogram.png')

batbot.spectrogram.refine_contour(segment, index, max_locations, segmentmask, peak, output_path='.')

batbot.spectrogram.refine_segmentmask(segmentmask, index, output_path='.')

batbot.spectrogram.remove_harmonic_and_echo(segment, index, harmonic, echo, threshold, med_db=None, std_db=None, kernel=15, output_path='.')

batbot.spectrogram.scale_pdf_contour(segment, index, min_band_idx=None, output_path='.')

batbot.spectrogram.significant_contour_path(begin, end, freq_step, time_step, min_bandwidth_khz=6000.0, min_duration_ms=2.0)

batbot.spectrogram.threshold_contour(segment, index, output_path='.')

batbot.spectrogram.tighten_ranges(stft_db, ranges, window, duration, skew_stddev=2.0, min_duration_ms=2.0, extra_buffer_pix=0.0, output_path='.', quiet=False)

batbot.spectrogram.write_contour_debug_image(segment, index, counter, tag, output_path='.')

Pipeline

The above components must be run in the correct order, but BatBot also offers a processing pipeline.

The machine learning (ML) model can be pre-downloaded and fetched by a single call to batbot.fetch() and the unified pipeline can be run by the function batbot.pipeline(). Below is example code for how these components interact.

Furthermore, there is an application demo file (app.py) that shows how the entire pipeline can be run on WAV files.

# Get WAV filepath
filepath = '/path/to/file.wav'

# Run tiling
output_paths, metadata_path, metadata = spectrogram.compute(filepath)

batbot.__init__.batch(filepaths, config=None, clean=True)

Run the ML pipeline on a given batch of WAV filepaths and return the detections in a corresponding list. The output is a list of outputs matching the output of batbot.pipeline(), except the processing is done in batch and is much faster.

The final output is a list of lists of dictionaries, each representing a single detection. Each dictionary has a structure with the following keys:

{
    'l': class_label (str)
    'c': confidence (float)
    'x': x_top_left (float)
    'y': y_top_left (float)
    'w': width (float)
    'h': height (float)
}

Parameters:

• filepaths (list) – list of str WAV filepath (relative or absolute)

• config (str or None, optional) – the configuration to use. Defaults to None.

• classifier_thresh (float or None, optional) – the confidence threshold for the Classifier’s predictions. Defaults to the default configuration setting.

• clean (bool, optional) – a flag to clean up any on-disk spectrograms that were generated. Defaults to True.

Returns:

corresponding list of classifier scores, corresponding list of lists of predictions

Return type:

tuple ( list ( float ), list ( list ( dict ) )

batbot.__init__.example()

Run the pipeline on an example WAV with the default configuration

batbot.__init__.fetch(pull=False, config=None)

Fetch the Classifier ONNX model file from a CDN if it does not exist locally.

This function will throw an AssertionError if the download fails or the file otherwise does not exist locally on disk.

Parameters:

• pull (bool, optional) – If True, force using the downloaded version stored in the local system’s cache. Defaults to False.

• config (str or None, optional) – the configuration to use. Defaults to None.

Returns:

None

Raises:

AssertionError – If the model cannot be fetched.

batbot.__init__.parallel_pipeline(in_file_chunks, out_stem_chunks=None, fast_mode=False, force_overwrite=False, num_workers=0, threaded=False, quiet=False, desc=None)

batbot.__init__.pipeline(filepath, out_file_stem=None, output_folder=None, fast_mode=False, force_overwrite=False, quiet=False, plot_uncompressed_amplitude=False, include_original_sr=False, time_buffer_ms=1.0, debug=False)

Run the ML pipeline on a given WAV filepath and return the classification results

The final output is a list of time windows where a bat exists. Each dictionary has a structure with the following keys:

{
    'l': class_label (str)
    'c': confidence (float)
    'x': x_top_left (float)
    'y': y_top_left (float)
    'w': width (float)
    'h': height (float)
}

Parameters:

• filepath (str) – WAV filepath (relative or absolute)

• config (str or None, optional) – the configuration to use. Defaults to None.

• classifier_thresh (float or None, optional) – the confidence threshold for the classifier’s predictions. Defaults to the default configuration setting.

• clean (bool, optional) – a flag to clean up any on-disk spectrograms that were generated. Defaults to True.

Returns:

classifier score, list of time windows

Return type:

tuple ( float, list ( dict ) )

batbot.__init__.pipeline_multi_wrapper(filepaths, out_file_stems=None, fast_mode=False, force_overwrite=False, worker_position=None, quiet=False, tqdm_lock=None)

Fault-tolerant wrapper for multiple inputs.

Parameters:

• filepaths (_type_) – _description_

• out_file_stems (_type_, optional) – _description_. Defaults to None.

• fast_mode (bool, optional) – _description_. Defaults to False.

• force_overwrite (bool, optional) – _description_. Defaults to False.

Returns:

_description_

Return type:

_type_

Utilities

BatBot utilities file for common and handy functions.

batbot.utils.init_logging()

Setup Python’s built in logging functionality with on-disk logging, and prettier logging with Rich