Data from: Automated Counting of Fish in moving Diver Operated Videos (DOV) for Biodiversity Assessments

Automated Counting of Fish in moving Diver Operated Videos (DOV) for Biodiversity AssessmentsAutomated Fish Counting in DOV DescriptionThis repository functions as the code and script database for the publication:[Made available once published] The detailed vignette can be found here:Find a comprehensive guide on the GitHub repository and in the file 'Vignette_Tutorial.pdf' provided. File Structure:```fishCount_in_DOV/├── 01_Scripts_Python/ # All Python scripts├── 02_Scripts_R/ # All R scripts├── 03_Datasets/ # Folder for datasets│ ├── boundingboxes_joined_3heads.csv # CSV for TCN training│ ├── dataset_1/ # Diplodus vulgaris│ ├── dataset_13/ # Epinephelus marginatus│ ├── dataset_17/ # Sciaena umbra│ └── overall/│ ├── 01.1_labels_groundtruth_test/ # Test labels (manual verification)│ ├── 01.1_labels_groundtruth_train/ # Train labels (manual calibration)│ ├── 01.2_labels_predictions/ # Predicted labels│ ├── 01.3_labels_groundtruth_train_test/ # Combined labels│ └── 02_boundingboxes/ # Folder for bounding boxes├── 04_Results/ # CSVs with results (Actual, Nmax, NCluster, NHeuristic, NTCN)├── 05_Models/ # Trained models per scenario│ └── 01_TCN_Models/ # Models for the study├── 06_Imgs/ # Shape outlines for R visualisations├── 1_NHeuristic_Thresholding.ipynb├── 1_NHeuristic_Thresholding_groundtruth.ipynb├── 2.1_TCN_FC_joinedSpecies_3heads.ipynb├── requirements.txt└── README.md``` --- Installation ## Clone the repository```bashgit clone [website available after publication]cd fishCount_in_DOV``` ## Create virtual environment```bashconda create -n fishCountEnvconda activate fishCountEnv``` ## Install Python dependencies```bashpip install -r requirements.txt``` ## Install R dependenciesRequired R libraries:```ggplot2, readr, tidyr, stringr, dplyr, reshape2,Metrics, cowplot, magick, rstudioapi, tibble``` --- # Alternative I: Docker 0. Add your `class_names.txt` to the root directory and labels to `./03_Datasets/overall/01.2_labels_predictions` 1. Build the Docker image:```bashdocker build -t nheuristic-processor .``` 2. Run the container:```bashdocker run -e PYTHONUNBUFFERED=1 --rm -v "$PWD":/app nheuristic-processor --base_dir /app --threshold 5 --nFrames 60 --confidence_threshold 0.5 --currentClass 13``` 3. Verify that the NHeuristic counts are correctly saved under:```./04_Results/class_[class]_nheuristic_onDetections.csv``` --- # Alternative II: CleverFishCleverFish is a tool that facilitates the use of NHeuristic and can be used to extract the counts directly: \[website available after publication] --- # Preparing the labels Copy your labels into `./03_Datasets/overall/01.1_labels_groundtruth` or `./03_Datasets/overall/01.2_labels_predictions` depending on the scenario you are running. Format of your YOLO labels:```[class | x_center | y_center | width | height | confidence (only in preds)]``` To prepare the actual count files (`Nact`), provide a CSV file with this format and exact column names:```videoname | category | Nact```Saved as:```./04_Results/class_[class]_nact.csv``` --- NHeuristic The NHeuristic method estimates fish counts by utilising two species-psecific parameters calibrated on the training data. ### Calibration Procedure 1. **Summarize annotated labels** Place annotated YOLO labels in: ``` ./03_Datasets/overall/01.1_labels_groundtruth_train ``` Run the Python script: ```bash python ./01_Scripts_Python/calculate_bounding_boxes_groundtruth.py ``` Bounding box summaries will be generated under: ``` ./03_Datasets/dataset_[class]/boundingboxes_class[class]_groundtruth.csv ``` 2. **Calibrate heuristic thresholds** Open and execute the notebook: ```bash jupyter notebook ./1_NHeuristic_Thresholding_groundtruth.ipynb ``` Adjust parameters in the second cell: - `threshold`: minimum number of detections for a group - `nFrames`: frame interval threshold The notebook explores parameter combinations and outputs performance metrics. 3. **Evaluate calibration performance** Aggregate calibration results in R: ```r source("./02_Scripts_R/concatenate_calibrationFiles.R") ``` Metrics are saved under: ``` ./04_Results/class_metrics/metrics_class_[class].csv ``` ### Prediction Workflow 1. **Prepare predicted labels** Save YOLO predictions to: ``` ./03_Datasets/overall/01.2_labels_predictions ``` Then summarise detections: ```bash python ./01_Scripts_Python/calculate_bounding_boxes_predictions.py ``` 2. **Apply calibrated heuristic** Run the notebook: ```bash jupyter notebook ./1_NHeuristic_Thresholding.ipynb ``` Update parameters in the second cell: ```python currentClass = [your_class_id] threshold = [optimal_threshold] nFrames = [optimal_nFrames] confidence_threshold = [confidence_from_previous_step] ``` Results are saved to: ``` ./04_Results/class_[class]_nheuristic.csv ``` --- NTCN The NTCN method uses a Temporal Convolutional Network to model species-specific movement patterns across frames. ### Prepare Input Data 1. Save YOLO prediction outputs to: ``` ./03_Datasets/overall/01.3_labels_groundtruth_train_test ``` Summarise detections: ```bash python ./01_Scripts_Python/calculate_bounding_boxes_groundtruth.py ``` Ensure bounding boxes are saved under: ``` ./03_Datasets/overall/02_boundingboxes/bounding_boxes_groundtruth/class_[class].csv ``` 2. Combine all species bounding boxes: ```r source("./02_Scripts_R/create_joined_file.R") ``` Produces: ``` ./03_Datasets/boundingboxes_joined_3heads.csv ``` ### Train and Evaluate the TCN Run the notebook:```bashjupyter notebook ./2.1_TCN_FC_joinedSpecies_3heads.ipynb```Models are automatically trained and saved to:```./05_Models/```Final counts are saved as:```./04_Results/class_[class]_Ntcn.csv``` --- Nmax and NCluster These rule-based approaches complement the NHeuristic and NTCN methods. 1. Save YOLO predictions to: ``` ./03_Datasets/overall/01.2_labels_predictions ``` Summarise detections: ```bash python ./01_Scripts_Python/calculate_bounding_boxes_predictions.py ``` 2. Run the R script to compute counts: ```r source("./02_Scripts_R/get_NCluster_NMax.R") ``` Results are saved as: ``` ./04_Results/class_[class]_nMax.csv ./04_Results/class_[class]_nCluster.csv ``` --- Summary After running all methods, you will obtain four complementary abundance metrics for each species:- **Nmax:** Single-frame maximum count - **NCluster:** Cluster-based counting for the fish schools - **NHeuristic:** Calibrated more intuitive and heuristic temporal merging - **NTCN:** Learned temporal deep learning approach These can be combined or compared to assess consistency and accuracy in biodiversity analyses. --- FAQ Q: What data formats are supported? \A: The tool supports the CSV format as an input. Q: The script calculate_bounding_boxes_groundtruth_OVERALL.py doesn't work with the error: \Traceback (most recent call last): \ File "/mnt/Internal/01_PhD/19_biomass_estimation_with_AI/98_NewGitTest/fishCount_in_DOV-main/./01_Scripts_Python/calculate_bounding_boxes_predictions_OVERALL.py", line 153, in main() \ File "/mnt/Internal/01_PhD/19_biomass_estimation_with_AI/98_NewGitTest/fishCount_in_DOV-main/./01_Scripts_Python/calculate_bounding_boxes_predictions_OVERALL.py", line 141, in main \ header = ["videoname"] + [f"frame_{i}" for i in range(1, max(len(sa) for sa in video_surface_areas.values()) + 1)] \ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ \A: The scripts need to be run in the perspective subfolders, otherwise the paths don't work. ---