Merge pull request #12 from zoccoler/update_docs

Update documentation

Author: zoccoler

README.md

@@ -8,43 +8,59 @@
 [![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-signal-classifier)](https://napari-hub.org/plugins/napari-signal-classifier)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17727926.svg)](https://doi.org/10.5281/zenodo.17727926)
 
-A napari plugin that classifies annotated signals stored in a table in the .features of a Labels layer using scikit-learn RandomForest classifier.
+A napari plugin that classifies annotated signals stored in a table in the `.features` of a `Labels` layer using a classifier.
 
-It also provides a sub-signal classifier that can be used to classify sub-signals inside time-series. First it detects sub-sginals with a template matching algorithm and then classifies them also using scikit-learn RandomForest classifier.
+It also provides a sub-signal classifier that can be used to classify local patterns inside longer time-series. First it detects sub-sginals with a template matching algorithm based on annotated sub-signals. Then, it trains and run predictions with a chosen classifier. At the moment, only  [scikit-learn RandomForest classifier](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html) option is implemented.
 
-This plugin employs and works in synergy with the [napari-signal-selector plugin](https://github.com/zoccoler/napari-signal-selector?tab=readme-ov-file#napari-signal-selector). Take a look at it to see how to annotate signals in a plotter linked to a napari Labels layer with the .features attribute.
+This plugin employs and works in synergy with the [napari-signal-selector plugin](https://github.com/zoccoler/napari-signal-selector?tab=readme-ov-file#napari-signal-selector). Take a look at it to see how to annotate signals in a plotter linked to a napari `Labels` layer with signals table stored in the `.features` attribute.
 
 [Jump to Intallation](#installation)
 
 # Usage
 
 ## Napari Signal Classifier
 
-After having annotated signals in the .features of a Labels layer (check the [napari-signal-selector plugin](https://github.com/zoccoler/napari-signal-selector?tab=readme-ov-file#napari-signal-selector)), you can train a signal classifier and predict the labels of unannotated signals.
+After having annotated signals in the `.features` of a `Labels` layer (check the [napari-signal-selector plugin](https://github.com/zoccoler/napari-signal-selector?tab=readme-ov-file#napari-signal-selector)), you can train a signal classifier and predict the labels of unannotated signals.
 
-Open the "Signal Classifier Widget" from the napari in "Layers > Classify > Signal / Time-series > Train and Predict Signal Classifier". The widget will appear in the right panel of napari.
+Open the `Train and Predict Signal Classifier` widget from the napari menus in `Layers > Classify > Signal / Time-series > Train and Predict Signal Classifier`. The widget will appear in the right panel of napari (see image below). It will also cast the `Signal Selector and Annotator` widget from napari-signal-selector to display the signals (remember to update the comboboxes to display the signals).
 
-Choose the Labels layer containing the annotated signals to classify (the annotations should have been previsouly done with the napari-signal-selector plugin). Choose the classifier (currently only RandomForest is implemented). Optionally provide a path to a folder where to save the trained model, select the number of trees (estimators) of the RandomForest, the random state for reproducibility, and the training percentage (the percentage of annotated signals that will be used for training, the rest will be used for testing the model and showing the accuracy, intially 80%). Finally click on "Train and Predict".
+![signal_classifier_widget](https://github.com/zoccoler/napari-signal-classifier/raw/main/images/signal_classifier_widget.png)
 
-Several signal features will be calculated automatically from the signals in the .features of the Labels layer, a RandomForest classifier will be trained on the annotated signals, and the labels of unannotated signals will be predicted. The predicted labels will be stored in a new column in the .features of the Labels layer called "Predictions". The accuracy of the model on the test set will be printed in the napari console.
+1. Choose the right `Labels` layer in the `Labels Layer with Signals Table` field.
+2. Choose the classifier (currently only RandomForest is implemented).
+3. Optionally provide a path to a folder where to save the trained model. The model file name is unique and automatically generated. If you provide here a link to a `.pkl` file previously trained with this plugin, it will just run predictions using the provided classifier.
+4. Select the number of trees (estimators) of the RandomForest.
+5. Choose a number for the random state for reproducibility. Choosing `-1` will pass `None` to `random_state` of scikit-learn's [](https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html) and [RamdomForest](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html), meaning the outcome will not be deterministic.
+6. Set the training percentage (the percentage of annotated signals that will be used for training, the rest will be used for testing the model and showing the accuracy) The initial value is 70%.
+7. Check the "Stratify" checkbox to perform stratified splitting of the annotated signals into train and test sets. This is recommended when you have imbalanced classes in your annotations.
+8. Click on "Train and Predict".
+
+Be patient as several signal features will be calculated automatically from the signals and the classifier will be trained on the annotated signals training set and evaluated on the test set. Also, the labels of unannotated signals will be predicted. The predicted labels will be stored in a new column, called "Predictions", in the `.features` of the same `Labels` layer. All parameters and the model's accuracy on the train and test sets will be printed in the napari console and saved as a `.json` file in the same place and with the same name as the trained classifier. A new `Labels` layer will be created to show the predicted labels on the signals.
 
 ![demo](https://github.com/zoccoler/napari-signal-classifier/raw/main/images/signal_classifier_demo.gif)
 
-The resulting .features table can be viewed via the native napari features table widget ("Layers > Visualize > Features Table Widget") and exported to a CSV file from there for further analysis.
+The resulting `.features` table can be viewed via the native napari features table widget (`Layers > Visualize > Features Table Widget`) and exported to a `.csv` file from there for downstream analysis.
 
 ## Napari Sub-Signal Classifier
 
-After having annotated signals in the .features of a Labels layer (check the [napari-signal-selector plugin](https://github.com/zoccoler/napari-signal-selector?tab=readme-ov-file#napari-signal-selector)), you can train a sub-signal classifier to classify sub-signals inside time-series.
+After having annotated signals in the `.features` of a `Labels` layer (check the [napari-signal-selector plugin](https://github.com/zoccoler/napari-signal-selector?tab=readme-ov-file#napari-signal-selector)), you can train a sub-signal classifier to classify local patterns (sub-signals) inside time-series.
+
+Open the `Train and Predict Sub-Signal Classifier` widget from the napari menus in `Layers > Classify > Signal / Time-series > Train and Predict Sub-Signal Classifier`. The widget will appear in the right panel of napari. It will also cast the `Signal Selector and Annotator` widget from napari-signal-selector to display the signals (remember to update the comboboxes to display the signals).
 
-Open the "Sub-Signal Classifier Widget" from the napari in "Layers > Classify > Signal / Time-series > Train and Predict Sub-Signal Classifier". The widget will appear in the right panel of napari.
+![sub_signal_classifier_widget](https://github.com/zoccoler/napari-signal-classifier/raw/main/images/sub_signal_classifier_widget.png)
 
-Choose the same parameters as the Signal Classifier Widget, plus a few additional parameters related to sub-signal detection and merging: the detection threshold for the template matching algorithm (default 0.8), the detrend option (default False) and smooth factor (default 0) for the template generation and the merging overlap threshold (default 0.5) for merging overlapping detected sub-signals. Finally click on "Train and Predict".
+Choose the same parameters as the [Napari Signal Classifier](#napari-signal-classifier), plus a few additional parameters related to sub-signal detection and merging: 
+1. Choose the "Detection Threshold" for the template matching algorithm (default 0.8, ranging from 0 to 1). This can be seen as a sensitivity to detection parameter. Sub-signals will be disconsidered if peaks in the cross-correlation with template are lower than this value.
+2. Choose whether to apply detrending to the annotated sub-signals (default unchecked). If checked, the first order derivative of each annotated sub-signal will be calculated and used for aligning sub-signals of the same class to generate the template.
+3. If "Detrend" is checked, choose a smooth factor (default 0.1, ranging from 0 to 0.5) to be applied to the first order derivative. It corresponds to the fraction of the highest frequencies removed. 
+4. Choose the "Merging Overlap Threshold" (default 0.5) for merging overlapping detected sub-signals. This is the minimal amount of overlap (Jaccard-index) in time between detected sub-signals to have them merged and considered a single detection. Increase this if you have sub-signals too close to each other and want to have them separated.
+5. Click on "Train and Predict".
 
-A signal template for each class will be generated by the median sub-signal of annotated sub-signals and a cross-correlation based template matching algorithm will be used to detect sub-signals in unannotated time-series. Several signal features will be calculated automatically from the detected sub-signals, a RandomForest classifier will be trained on the annotated sub-signals, and the detected unannotated sub-signals will be predicted. The predicted labels will be stored in a new column in the .features of the Labels layer called "Predictions". The accuracy of the model on the test set will be printed in the napari console.
+Be patient as a signal template for each class will be generated by the median of annotated sub-signals and a cross-correlation based template matching algorithm will be used to detect these templates in each unannotated time-series (signal). Several signal features will be calculated automatically from the detected sub-signals, a classifier will be trained on the annotated sub-signals training set and evaluated on the test set. Also, the detection + classification algorithms will be applied to all unannotated signals. The predicted labels will be stored in a new column in the `.features` of the `Labels` layer called "Predictions". All parameters and the model's accuracy on the train and test sets will be printed in the napari console and saved as a `.json` file in the same place and with the same name as the trained classifier. A new `Labels` layer will be created to show the predicted labels on the signals.
 
 ![demo](https://github.com/zoccoler/napari-signal-classifier/raw/main//images/sub_signal_classifier_demo.gif)
 
-Again, the resulting .features table can be viewed via the native napari features table widget ("Layers > Visualize > Features Table Widget") and exported to a CSV file from there for further analysis.
+Again, the resulting `.features` table can be viewed via the native napari features table widget (`Layers > Visualize > Features Table Widget`) and exported to a `.csv` file from there for downstream analysis.
 
 ----------------------------------