Program

Pre-Built Program

acoupi_batdetect2.program

Batdetect2 Program.

This module builds the BatDetect2 Program to record, detect and classify, as well as manage and send messages of UK bat calls. The program extends the DetectionProgram and MessagingProgram from the acoupi package by adding the BatDetect2 model and integrating users' custom configuration schema.

Key Elements:

• BatDetect2_ConfigSchema: Defines the configuration for the BatDetect2 program, including the audio recording, model setup, file management, messaging, and summariser settings.

Program Tasks:

• recording_task: Records audio from a microphone and saves the audio files in a temporary directory until they have been processed by the detection and management tasks. Based on the SavingFilters configuration, recordings will either saved or deleted.
• detection_task: Runs the BatDetect2 model on the audio recordings, processes the detections, and can use a custom ModelOutputCleaner to filter out unwanted detections (e.g., low-confidence results). The filtered detections are saved in a metadata.db file.
• management_task: Performs periodically file management operations, such as moving recording to permanent storage, or deleting unnecessary ones.
• messaging_task: Send messages stored in the message store using a configured protocol (HTTP or MQTT).
• summary_task: Periodically creates summaries of the detections.

Customisation Options:

• ModelConfig: Set the detection_threshold to clean out the output of the BatDetect2 model. Detections with a confidence score below this threshold will be excluded from the store and from the message content.

• SaveRecordingManager: Define where recordings are stored, the naming format, and the minimum confidence score for saving recordings. Recordings with confidence scores below the saving_threshold will not be saved. The saving_threshold can be set lower than the detection_threshold to save recordings with uncertain detections. Recordings with detections above the detection_threshold will be saved in the true_dir directory, while recordings with detections below the detection_threshold but above the saving_threshold will be saved in the false_dir directory.

• SaveRecordingFilter: Define additional saving filters for saving recordings.

  1. A timeinterval interval fitler that saves recordings whthin a specific time window, set by the starttime and endtime parameters.
  2. A frequency filter that saves recordings for a specific duration (in minutes) at defined interval (in minutes), set by the frequency_duration and frequency_interval parameters.
  3. A before dawn/dusk filter to save recording for a defined duration (in minutes) before dawn and dusk, set by the before_dawndusk_duration.
  4. An after dawn/dusk filter to save recording for a defined duration (in minutes) after dawn and dusk, set by the after_dawndusk_duration.
  5. A saving threshold filter to save recording with detection above a specific treshold, set by the saving_filter parameter.

• SummariserConfig: Define the interval for summarising detections. By default, the summariser calculates the minimum, maximum, and average confidence scores of the total number of detections for each time interval. If the low_band_threshold, mid_band_threshold, and high_band_threshold are set to values greater than 0.0, it also summarises the number of detections in each band (low, mid, high).

Classes:

Name	Description
BatDetect2_Program	BatDetect2 Program Configuration.

Classes

BatDetect2_Program

Bases: DetectionProgram[BatDetect2_ConfigSchema]

BatDetect2 Program Configuration.

Methods:

Name	Description
configure_model	Configure the BatDetect2 model.
get_file_managers	Get the file managers for the BatDetect2 Program.
get_message_factories	Get the message factories for the BatDetect2 Program.
get_recording_filters	Get the recording filters for the BatDetect2 Program.
get_summarisers	Get the summarisers for the BatDetect2 Program.
setup	Set up the BatDetect2 Program.

Attributes:

Name	Type	Description
config_schema

Attributes

config_schema = BatDetect2_ConfigSchema class-attribute instance-attribute

Functions

configure_model(config)

Configure the BatDetect2 model.

Returns:

Type	Description
BatDetect2	The BatDetect2 model instance.

get_file_managers(config)

Get the file managers for the BatDetect2 Program.

Parameters:

Name	Type	Description	Default
config	BatDetect2_ConfigSchema	The configuration schema for the acoupi_batdetect2 program defined in the configuration.py file and configured by a user via the CLI.	required

Returns:

Type	Description
list[RecordingSavingManager]	A list of file managers for the batdetect2 program.

get_message_factories(config)

Get the message factories for the BatDetect2 Program.

Parameters:

Name	Type	Description	Default
config	BatDetect2_ConfigSchema	The configuration schema for the acoupi_batdetect2 program defined in the configuration.py file and configured by a user via the CLI.	required

Returns:

Type	Description
list[MessageBuilder]	A list of message factories for the batdetect2 program. By default, the message factory will use the detection_threshold parameter for buildling messages.

get_recording_filters(config)

Get the recording filters for the BatDetect2 Program.

Parameters:

Name	Type	Description	Default
config	BatDetect2_ConfigSchema	The configuration schema for the acoupi_batdetect2 program defined in the configuration.py file and configured by a user via the CLI.	required

Returns:

Type	Description
list[RecordingSavingFilter]	A list of recording filters for the batdetect2 program. If no saving filters are defined, the method will not save any recordings.

get_summarisers(config)

Get the summarisers for the BatDetect2 Program.

Parameters:

Name	Type	Description	Default
config	BatDetect2_ConfigSchema	The configuration schema for the acoupi_batdetect2 program defined in the configuration.py file and configured by a user via the CLI.	required

Returns:

Type	Description
list[Summariser]	A list of summarisers for the batdetect2 program. By default, the summariser will use the summariser_config.interval parameter for summarising the detections and calculating the minimum, maximum, and average confidence scores of the detections in each interval.

setup(config)

Set up the BatDetect2 Program.

This method initialises the batdetect2 program, registers the recording, detection, management, messaging, and summariser tasks, and performs any necessary setup for the program to run.