batdetect2/docs/source/targets/use.md

## Bringing It All Together: The `Targets` Object

### Recap: Defining Your Target Strategy

In the previous sections, we covered the sequential steps to precisely define what your BatDetect2 model should learn, specified within your configuration file:

1.  **Terms:** Establishing the vocabulary for annotation tags.
2.  **Filtering:** Selecting relevant sound event annotations.
3.  **Transforming:** Optionally modifying tags.
4.  **Classes:** Defining target categories, setting priorities, and specifying tag decoding rules.
5.  **ROI Mapping:** Defining how annotation geometry maps to target position and size values.

You define all these aspects within your configuration file (e.g., YAML), which holds the complete specification for your target definition strategy, typically under a main `targets:` key.

### What is the `Targets` Object?

While the configuration file specifies _what_ you want to happen, BatDetect2 needs an active component to actually _perform_ these steps.
This is the role of the `Targets` object.

The `Targets` is an organized container that holds all the specific functions and settings derived from your configuration file (`TargetConfig`).
It's created directly from your configuration and provides methods to apply the **filtering**, **transformation**, **ROI mapping** (geometry to position/size and back), **class encoding**, and **class decoding** steps you defined.
It effectively bundles together all the target definition logic determined by your settings into a single, usable object.

### How is it Created and Used?

For most standard training workflows, you typically won't need to create or interact with the `Targets` object directly in Python code.
BatDetect2 usually handles its creation automatically when you provide your main configuration file during training setup.

Conceptually, here's what happens behind the scenes:

1.  You provide the path to your configuration file (e.g., `my_training_config.yaml`).
2.  BatDetect2 reads this file and finds your `targets:` configuration section.
3.  It uses this configuration to build an instance of the `Targets` object using a dedicated function (like `load_targets`), loading it with the appropriate logic based on your settings.

```python
# Conceptual Example: How BatDetect2 might use your configuration
from batdetect2.targets import load_targets # The function to load/build the object
from batdetect2.targets.types import TargetProtocol # The type/interface

# You provide this path, usually as part of the main training setup
target_config_file = "path/to/your/target_config.yaml"

# --- BatDetect2 Internally Does Something Like This: ---
# Loads your config and builds the Targets object using the loader function
# The resulting object adheres to the TargetProtocol interface
targets_processor: TargetProtocol = load_targets(target_config_file)
# ---------------------------------------------------------

# Now, 'targets_processor' holds all your configured logic and is ready
# to be used internally by the training pipeline or for prediction processing.
```

### What Does the `Targets` Object Do? (Its Role)

Once created, the `targets_processor` object plays several vital roles within the BatDetect2 system:

1.  **Preparing Training Data:** During the data loading and label generation phase of training, BatDetect2 uses this object to process each annotation from your dataset _before_ the final training format (e.g., heatmaps) is generated.
    For each annotation, it internally applies the logic:
    - `targets_processor.filter(...)`: To decide whether to keep the annotation.
    - `targets_processor.transform(...)`: To apply any tag modifications.
    - `targets_processor.encode(...)`: To get the final class name (e.g., `'pippip'`, `'myodau'`, or `None` for the generic class).
    - `targets_processor.get_position(...)`: To determine the reference `(time, frequency)` point from the annotation's geometry.
    - `targets_processor.get_size(...)`: To calculate the _scaled_ width and height target values from the annotation's geometry.
2.  **Interpreting Model Predictions:** When you use a trained model, its raw outputs (like predicted class names, positions, and sizes) need to be translated back into meaningful results.
    This object provides the necessary decoding logic:
    - `targets_processor.decode(...)`: Converts a predicted class name back into representative annotation tags.
    - `targets_processor.recover_roi(...)`: Converts a predicted position and _scaled_ size values back into an estimated geometric bounding box in real-world coordinates (seconds, Hz).
    - `targets_processor.generic_class_tags`: Provides the tags for sounds classified into the generic category.
3.  **Providing Metadata:** It conveniently holds useful information derived from your configuration:
    - `targets_processor.class_names`: The final list of specific target class names.
    - `targets_processor.generic_class_tags`: The tags representing the generic class.
    - `targets_processor.dimension_names`: The names used for the size dimensions (e.g., `['width', 'height']`).

### Why is Understanding This Important?

As a researcher using BatDetect2, your primary interaction is typically through the **configuration file**.
The `Targets` object is the component that materializes your configurations.

Understanding its role can be important:

- It helps connect the settings in your configuration file (covering terms, filtering, transforms, classes, and ROIs) to the actual behavior observed during training or when interpreting model outputs.
  If the results aren't as expected (e.g., wrong classifications, incorrect bounding box predictions), reviewing the relevant sections of your `TargetConfig` is the first step in debugging.
- Furthermore, understanding this structure is beneficial if you plan to create custom Python scripts.
  While standard training runs handle this object internally, the underlying functions for filtering, transforming, encoding, decoding, and ROI mapping are accessible or can be built individually.
  This modular design provides the **flexibility to use or customize specific parts of the target definition workflow programmatically** for advanced analyses, integration tasks, or specialized data processing pipelines, should you need to go beyond the standard configuration-driven approach.

### Summary

The `Targets` object encapsulates the entire configured target definition logic specified in your `TargetConfig` file.
It acts as the central component within BatDetect2 for applying filtering, tag transformation, ROI mapping (geometry to/from position/size), class encoding (for training preparation), and class/ROI decoding (for interpreting predictions).
It bridges the gap between your declarative configuration and the functional steps needed for training and using BatDetect2 models effectively, while also offering components for more advanced, scripted workflows.