From f5953b2ffca001c69bac9cfcdc7c028d43a07df4 Mon Sep 17 00:00:00 2001
From: Paul Best <paul.best@lis-lab.fr>
Date: Fri, 12 Aug 2022 12:31:52 +0200
Subject: [PATCH] Update README.md

---
 README.md | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index efaddd2..29f678f 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,29 @@
-# carimam_cnn
+# CETA CNNs
 
-Convolutionnal neural networks for humpback whale vocalisations and delphinid whistles.
+## Project description
+This project allows to detect the vocalizations from several cetacean species in acoustic signals using Convolutionnal Neural Networks (CNNs).
 
-Call either run_CNN_HB.py for humpback whales or run_CNN_delphi.py for delphinid whistles.
+CNN architectures with pretrained weights are available for inference through a python interface for the following species / signals:
+- Humpback whale calls (*Megatera novaeangliae*, trained on recordings from the Caribbean Sea)
+- Dolphin whistles (*Delphinid*, trained on recordings from the Caribbean Sea)
+- Sperm whale clicks (*Physeter macrocephalus*, trained on recordings from the Mediterranean Sea)
+- Fin whale 20Hz pulses (*Balaenoptera physalus*, trained on recordings from the Mediterranean Sea)
+- Orcas pulsed calls (*Orcinus orca*, trained on recordings from the North-Eastern Pacific Ocean)
 
-Call the python script followed by the list of wav files you would like to process, and optionnaly an output filename.
-For example : 
-`python run_CNN_HB.py file1.wav file2.wav -outfn predictions.pkl`
+For the detection of Antarctic fin whale and and Antarctic blue whale vocalizations, see https://gitlab.lis-lab.fr/paul.best/at_bluefin
 
-This script relies on torch, pandas, numpy, scipy, and tqdm to run. Install dependencies with pip or conda.
+## Usage
+Use python to run the script forward_CNN.py along with a target specie and a folder of audio files to analyse. A tabular file will be saved with the model's predictions for the corresponding signal to detect (probability of presence).
+
+Run `python run_CNN.py -h` for a detailled API.
+
+The output file with predictions can be read in python using pandas : `pandas.read_pickle('filename.pkl')`
+
+## Dependencies
+This script relies on `torch`, `pandas`, `numpy`, `scipy`, `soundfile` and `tqdm` to run. You can install them using pip or conda.
 If a GPU and cuda are available on the current machine, processes will run on GPU for faster computation.
 
-paul.best@univ-tln.fr for more information
+
+## Contact
+You can reach me at paul.best@univ-tln.fr for more information
+
-- 
GitLab