diff --git a/README.md b/README.md index ad11a9904f11d34408379fd8cb93f4857efc2204..6c3f2f648d76d10c20fa8866c1ded97c0e722e23 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Preprint BioRXiv [](https://doi.org/10.1101/2024.10.25.620201) #### ```Dataset & pre-trained µPIX Models``` -| | Dataset | pre-trained µPIX Models | +| | Dataset | Pre-trained µPIX Models | |--------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | ```csbdeep``` | [download](https://sync.lis-lab.fr/index.php/s/sy3SrGgqNafbP5X/download) | [download](https://sync.lis-lab.fr/index.php/s/riqZbKBbYwjLK4m/download) | | ```rejuvenation``` | [download](https://sync.lis-lab.fr/index.php/s/kDyLKjCt48BfNMK/download) | [download](https://sync.lis-lab.fr/index.php/s/n2oJAw4LobTCeNZ/download) | @@ -26,7 +26,7 @@ Preprint BioRXiv [ and then : +If you do not have already miniconda installed on your system, please refer to the [officical miniconda documentation](https://docs.anaconda.com/miniconda/install/). Then : -Create a miniconda environment and source it: +1- Create a miniconda environment and source it: ```bash conda create -n mupix_env python=3.11 ``` ```bash source ~/.bashrc ``` -Finally activate the environment: +2- Activate the environment: ```bash conda activate mupix_env ``` -Clone this repository to download µPIX sources : +3 - Clone this repository to download µPIX sources : ```bash git clone https://gitlab.lis-lab.fr/sicomp/mupix ``` -and then proceed to the installation of required Python packages: + +4- Install the required Python packages: ```bash pip install -r mupix/requirements.txt @@ -67,12 +68,12 @@ pip install -r mupix/requirements.txt -## Use Case n°1 - Use a pre-trained µPIX model to denoise an image dataset ([Tutorial VIDEO](https://sync.lis-lab.fr/index.php/s/ftw9fdGacJyyfBq)) +## Use Case #1 - Use a pre-trained µPIX model to denoise an image dataset ([Tutorial VIDEO](https://sync.lis-lab.fr/index.php/s/ftw9fdGacJyyfBq)) <details> <summary>Click to expand</summary> -µPIX comes with 3 ptre-trained models along with their respective datasets: +µPIX comes with 3 Pre-trained models along with their respective datasets: | | Dataset | pre-trained µPIX Models | |--------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| @@ -81,7 +82,7 @@ pip install -r mupix/requirements.txt | ```metrology``` | [download](https://sync.lis-lab.fr/index.php/s/mYDRTeAQxMxNPPJ/download) | [download](https://sync.lis-lab.fr/index.php/s/degZsCxN7ZXxeB6/download) | -For this example, we will use a pre-trained µPIX model on the ```metrology``` dataset and we will use it to denoise the ```metrology``` test dataset. +For this example, we will use a pre-trained µPIX model on the ```metrology``` training dataset to denoise the ```metrology``` test dataset. First, move to the `mupix` directory: ```bash @@ -91,7 +92,7 @@ cd mupix ### 1 - Download and unzip the pre-trained µPIX ```metrology``` model -To download the ```metrology``` model, type in your Terminal: +To download the ```metrology``` model, type the following command in your Terminal: ```bash curl -o metrology_model.zip https://sync.lis-lab.fr/index.php/s/degZsCxN7ZXxeB6/download -q @@ -101,7 +102,7 @@ curl -o metrology_model.zip https://sync.lis-lab.fr/index.php/s/degZsCxN7ZXxeB6/ unzip -qq metrology_model.zip -d metrology_model ``` -The model is now stored inside ```./metrology_model``` folder. +The model is now stored in the ```./metrology_model``` folder. ### 2 - Download and unzip the ```metrology``` dataset @@ -139,10 +140,10 @@ The ```new_experiment.py``` script allows you to set up a new experiment by spec | `--test_data_path` *(optional)* | Path to the test dataset (if available). | -In our case, as we want just to use the pre-trained µPIX ```metrology``` model in inference (no training), we don't need to provide the ```clean_data_path``` and ```noisy_data_path``` parameters so we left it empty. +In this case, since we are using the pre-trained µPIX ```metrology``` model in inference (no training), we do not need to provide the ```clean_data_path``` and ```noisy_data_path``` parameters so we left it empty. Nevertheless, we have to indicate the path that contains the test data image we want to denoise using µPIX using the ```test_data_path``` parameter, and the ```experiment_name``` we want to create as well as the location where the experiment will be stored using the ```experiment_path``` parameter. -Type the following to create experiment: +Type the following command to create a µPIX experiment: ```bash python new_experiment.py --experiment_name "metrology_experiment" --experiment_path "./experiments" --clean_data_path "" --noisy_data_path "" --test_data_path "./metrology/test" @@ -175,12 +176,12 @@ For our example, here is the command you need to type to start the inference usi python mupixinfer.py --experiment_path "./experiments/metrology_experiment/" ``` -Once finished, the denoised images are stored inside ```./experiments/metrology_experiment/predictions/``` directory. +Once completed, the denoised images are stored in the ```./experiments/metrology_experiment/predictions/``` directory. </details> -## Use Case n°2 - Train a µPIX model from scratch using a custom dataset +## Use Case #2 - Train a µPIX model from scratch using a custom dataset <details> <summary>Click to expand</summary> @@ -281,7 +282,7 @@ For information, here is the ```hyperparameters.json``` file created by default | `batch_size` | `int` | Number of samples per batch. | | `num_epochs` | `int` | Total number of training epochs. | | `loss_weight` | `int` | Weight factor for µPIX loss calculation. | -| `tile_size` | `int` | Size of image tiles used for training. | +| `tile_size` | `int` | Size of the image tiles used for training. | | `patience` | `int` | Number of epochs to wait before triggering µPIX early stopping if no improvement. | | `valid_size` | `float` | Proportion of the dataset used for validation. | | `seed` | `int` | Random seed for reproducibility. | @@ -304,7 +305,7 @@ python mupixtraining.py --experiment_path EXPERIMENT_PATH [--retrain] | Argument | Description | |--------------------------|-------------| | `--experiment_path` | Path to the previously created experiment. | -| `--retrain` *(optional)* | Use this flag to continue training an existing µPIX model located inside the experiment path. | +| `--retrain` *(optional)* | Use this flag to continue training an existing µPIX model located in the experiment path. | For our example, here is the command you need to type to start the training of a µPIX model for the ```metrology``` dataset: @@ -346,11 +347,11 @@ Step>3, Generator loss : 1.941e+05 ... ... ``` -By default, the model is trained for 100 epochs (see ```hyperparameters.json```) but contains an ```EarlyStopping``` mechanisms (See the paper methods section pour details) governed by the ```patience``` parameters (see ```hyperparameters.json```). +By default, the model is trained for 100 epochs (see ```hyperparameters.json```) but it includes an ```EarlyStopping``` mechanism (See the paper methods section pour details) governed by the ```patience``` parameters (see ```hyperparameters.json```). -You can stop the training anytime. The best checkpoints of your model is available inside ```experiments/metrology_experiment/results/networks/``` +You can stop the training at anytime. The best checkpoints of your model is available in the ```experiments/metrology_experiment/results/networks/``` directory. -If the training stops because it reached the maximum number of epochs defined inside the ```hyperparameters.json``` configuration file, and you want to continue to train your model for more epochs, you can use the ```--retrain``` parameters to resume the training where it stops: +If the training stops because it has reached the maximum number of epochs defined into the ```hyperparameters.json``` configuration file, and you want to continue training your model for more epochs, you can use the ```--retrain``` parameters to resume the training where it stops: ```bash python mupixtraining.py --experiment_path "./experiments/metrology_experiment" --retrain @@ -358,7 +359,7 @@ python mupixtraining.py --experiment_path "./experiments/metrology_experiment" - ### 2.4 - Inference on the test dataset -The `mupixinfer.py` script allows you to use a pre-trained µPIX model to denoise a dataset located in the `test` directory inside the experiment path. +The `mupixinfer.py` script allows you to use a pre-trained µPIX model to denoise a dataset located within the `test` directory inside the experiment path. #### Usage @@ -372,7 +373,7 @@ For our example, here is the command you need to type to start the inference usi python mupixinfer.py --experiment_path "./experiments/metrology_experiment/" ``` -Once done you can see that the predictions has been stored inside ```./experiments/metrology_experiment/predictions/``` directory: +Once done you can see that the predictions has been stored in the ```./experiments/metrology_experiment/predictions/``` directory: ``` Saved weights to ./experiments/metrology_experiment/results/networks/Generator.h5 1/1 [==============================] - 7s 7s/step @@ -404,4 +405,4 @@ If you would like to cite this work, please use the following BibTeX entry: </details> ## License -This code repository is release under the [CC BY-NS-SA 4.0](https://gitlab.lis-lab.fr/sicomp/mupix/-/blob/main/LICENSE?ref_type=heads) +This code repository is released under the [CC BY-NS-SA 4.0](https://gitlab.lis-lab.fr/sicomp/mupix/-/blob/main/LICENSE?ref_type=heads)