update readme

Author: jizong

README.md

@@ -0,0 +1,47 @@
+## Boosting Semi-supervised Image Segmentation with Global and Local Mutual Information Regularization
+
+This is the minimal reproduce code for the paper "Boosting Semi-supervised Image Segmentation with Global
+and Local Mutual Information Regularization" recently submitted to a journal. 
+
+
+We release the code, together with the well-preprocessed `ACDC` dataset for reviewers. The dataset should be keep private based on the dataset agreement and I will delete it once the reviewer process finishes.
+
+Our code is based on `deepclustering2` package, which is a personal research framework. It will automatically install all dependency on a conda virtual environment and without resorting to `requirement.txt`.
+
+
+-----------------
+##### Basic script for setting a conda-based virtual environment.
+```bash
+conda create -p ./venv python=3.7
+
+conda activate ./venv
+
+conda install pytorch torchvision cudatoolkit=10.2 -c pytorch  # install pytorch 1.6.0
+pip install deepclustering2-2.0.0-py3-none-any.whl
+python setup.py install  
+# all packages should be set properly automatically.
+```
+In case of failure of running the experiments, please refer to `requirement.txt` to see the packages
+
+----------------
+##### Basic script to start training 
+```bash
+cd semi_seg
+# our proposed method
+python main.py  Data.labeled_data_ratio=0.05  Data.unlabeled_data_ratio=0.95  Trainer.num_batches=300  Trainer.max_epoch=100  Data.name=acdc  Arch.num_classes=4  Optim.lr=0.0000001000 Trainer.name=udaiic Trainer.save_dir=udaiic/10.0_0.1  IICRegParameters.weight=0.1 UDARegCriterion.weight=10.0 
+# ps baseline (lower bound)
+python main.py  Data.labeled_data_ratio=0.05  Data.unlabeled_data_ratio=0.95  Trainer.num_batches=300  Trainer.max_epoch=100  Data.name=acdc  Arch.num_classes=4  Optim.lr=0.0000001000 Trainer.name=partial Trainer.save_dir=ps  
+# fs baseline (upper bound)
+python main.py  Data.labeled_data_ratio=1.0  Data.unlabeled_data_ratio=0.0  Trainer.num_batches=300  Trainer.max_epoch=100  Data.name=acdc  Arch.num_classes=4  Optim.lr=0.0000001000 Trainer.name=partial Trainer.save_dir=fs  
+```
+One can change the parameters on the cmd if needed.
+Please refer to the default configuration in `config/semi.yaml` all set of controllable hyperparameters. All of them can be changed using cmd as above.
+
+
+---------------------
+##### Performance
+Based on different random seed, the ACDC performance varies within 1% in terms of DSC. Above scripts gives a DSC of ~85.5% for our proposed method vs 62.0% for ps and 89.2% for fs.
+
+
+
+

config/config.yaml

@@ -0,0 +1,74 @@
+absl-py==0.10.0
+aiohttp==3.6.2
+async-timeout==3.0.1
+attrs==20.2.0
+behave==1.2.6
+cachetools==4.1.1
+certifi==2020.6.20
+chardet==3.0.4
+cycler==0.10.0
+decorator==4.4.2
+deepclustering2 @ file:///home/jizong/Workspace/release-code/deepclustering2-2.0.0-py3-none-any.whl
+easydict==1.9
+filelock==3.0.12
+future==0.18.2
+gdown==3.12.2
+google-auth==1.22.0
+google-auth-oauthlib==0.4.1
+GPUQueue==0.0.3
+grpcio==1.32.0
+idna==2.10
+imageio==2.9.0
+importlib-metadata==2.0.0
+joblib==0.16.0
+kiwisolver==1.2.0
+Markdown==3.2.2
+matplotlib==3.3.2
+MedPy==0.4.0
+mkl-fft==1.2.0
+mkl-random==1.1.1
+mkl-service==2.3.0
+msgpack==1.0.0
+multidict==4.7.6
+networkx==2.5
+numpy @ file:///tmp/build/80754af9/numpy_and_numpy_base_1596233707986/work
+oauthlib==3.1.0
+olefile==0.46
+opencv-python==4.4.0.44
+pandas==1.1.2
+parse==1.18.0
+parse-type==0.5.2
+Pillow @ file:///tmp/build/80754af9/pillow_1594307325547/work
+protobuf==3.13.0
+py==1.9.0
+pyasn1==0.4.8
+pyasn1-modules==0.2.8
+pyparsing==2.4.7
+python-dateutil==2.8.1
+pytorch-ranger==0.1.1
+pytz==2020.1
+PyWavelets==1.1.1
+PyYAML==5.3.1
+requests==2.24.0
+requests-oauthlib==1.3.0
+rsa==4.6
+scikit-image==0.17.2
+scikit-learn==0.23.2
+scipy==1.5.2
+SimpleITK==2.0.0
+six==1.15.0
+tensorboard==2.3.0
+tensorboard-plugin-wit==1.7.0
+tensorboardX==2.1
+termcolor==1.1.0
+threadpoolctl==2.1.0
+tifffile==2020.10.1
+torch==1.6.0
+torch-optimizer==0.0.1a15
+torchvision==0.7.0
+tqdm==4.50.0
+typing-extensions==3.7.4.3
+urllib3==1.25.10
+Werkzeug==1.0.1
+yarl==1.6.0
+zipp==3.2.0