Skip to content
This repository has been archived by the owner on Mar 17, 2021. It is now read-only.

Commit

Permalink
Merge pull request #303 from NifTK/179-model-zoo-docs
Browse files Browse the repository at this point in the history 
fixes #179; fixes NifTK/NiftyNetModelZoo#8
  • Loading branch information
@wyli
wyli committed Dec 18, 2018
2 parents 6b8debe + 28bb235 commit c093006
Show file tree
Hide file tree
Showing 2 changed files with 234 additions and 54 deletions.
168 changes: 118 additions & 50 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,13 @@ The source code for NiftyNet is released via [GitHub][github-niftynet].
- [Submitting bug reports and feature requests](#submitting-bug-reports-and-feature-requests)
- [Submitting merge requests](#submitting-merge-requests)
- Python style guide
- Testing your changes
- Creating GitHub pull requests
- Test your changes
- Create GitHub pull requests
- [Submitting model zoo entries](#submitting-model-zoo-entries)
- Fork the model zoo repo
- Create new folder and add model zoo data
- Update documentation
- Create GitHub pull requests
- [Writing unit tests](#writing-unit-tests)
- Determine which module to test
- File an issue
Expand Down Expand Up @@ -50,7 +55,7 @@ In particular (from the guide):
[pep8]: https://www.python.org/dev/peps/pep-0008/


### 2. Testing your changes
### 2. Test your changes

Please submit merge requests from your branch to the `dev` branch.

Expand All @@ -62,7 +67,7 @@ cd NiftyNet/
sh run_test.sh
```

### 3. Creating GitHub pull requests
### 3. Create GitHub pull requests
1. **[on GitHub]** Sign up/in [GitHub.com](https://github.com/) (The rest steps assume GitHub user id: `nntestuser`).
1. **[on GitHub]** Go to [https://github.com/NifTK/NiftyNet](https://github.com/NifTK/NiftyNet), click the 'Fork' button.
1. Download the repo:
Expand All @@ -82,6 +87,113 @@ sh run_test.sh
1. **[on GitHub]** Create a pull request by clicking the 'pull request' button.


## Submitting model zoo entries
NiftyNet provides a version-controlled model zoo deployed on GitHub,
we welcome new model zoo entry submissions!

The model zoo is itself a GitHub project, the workflow of submitting new entries is in general the same as sending a
[GitHub pull request](https://help.github.com/articles/fork-a-repo/).

The following is a step-by-step guide for submitting a new entry named `foo_bar_model_zoo`.
After finishing these steps, all users will be able to download the model by running
NiftyNet command `net_download foo_bar_model_zoo`.

*`foo_bar_model_zoo` is a model zoo entry ID for demo purposes only, normally we prefer meaningful IDs,
which should briefly indicate the method, network architecture, and the task name.*

#### 1. Fork the model zoo repo
NiftyNet model zoo uses [Git Large File Storage -- git-lfs](https://git-lfs.github.com/) for large file (such as trained network weights) versioning.
Make sure you have installed `git-lfs` and file archiving tool `tar` beforehand.

[Fork and `git clone` the repo](https://help.github.com/articles/fork-a-repo/)
to your local machine, create a new folder called `foo_bar` within the codebase.
This folder will hold all the new content of the proposed entry.

#### 2. Create new folder and add model zoo data
Create a new folder `foo_bar_model_zoo` in the project folder where `foo_bar_model_zoo`
will be the model ID. When the model files are available in the repo,
the other users will download the model by running `net_download foo_bar_model_zoo`.

The new entry can be NiftyNet application configuration files, demo image data, or some trained weights,
or a combination of these data. These data should be archived into three `.tar.gz` files:
- `data.tar.gz`: for training/inference images, this will eventually go to the user's `~/niftynet/data/foo_bar` folder by default.
- `config.tar.gz`: for customised Python code, such as new loss functions, image samplers, as well as application configuration file.
This will go to the users `~/niftynet/extensions/foo_bar` folder by default.
- `weights.tar.gz`: for the trained weights, this will go to the user's `~/niftynet/models/foo_bar` folder by default.

We recommend that the `.tar.gz` files to be created by running, for example
```bash
tar -cvzf ../data.tar.gz ./input_demo_data.nii
```
The command will create an archive outside the current directory which contains the image `input_demo_data.nii` .
Un-archiving this file will output the images `input_demo_data.nii`

Similarly this can be done for the configuration files as well as Python codes:
```bash
tar -cvzf ../config.tar.gz ./myconfig*.ini
```

For the trained weights, we require the following specific folder structure:
```
└── highres3dnet_brain_parcellation
├── databrain_std_hist_models_otsu.txt
└── models
├── model.ckpt-33000.data-00000-of-00001
├── model.ckpt-33000.index
└── model.ckpt-33000.meta
```
Where `databrain_std_hist_models_otsu.txt` is a label or intensity histogram mapping file generated by NiftyNet;
`models` and `model.ckpt-*` names are compulsory: NiftyNet will always look for the `models` folder when reading the model zoo entry.

After having this folder structure, the archive file can be created by running:
```bash
cd highres3dnet_brain_parcellation/
tar -cvzf ../weights.tar.gz ./*
```

The outcome of this step should be several `.tar.gz` files within the `foo_bar` folder, within the cloned model zoo GitHub project:
```
└── foo_bar
├── data.tar.gz
├── config.tar.gz
└── weights.tar.gz
```

#### 2.5 Make a `main.ini`
Within `foo_bar` folder, create a `main.ini` file, with optional sections of
`[code]`, `[data]`, and `[weights]`. So that the end-users' `net_download` command
knows where to fetch and un-archive the shared data.

Each section should have the following values
```ini
[code]
# indicating the model zoo's ID
local_id = foo_bar
# the actual url for the .tar.gz
url = https://github.com/NifTK/NiftyNetModelZoo/raw/5-reorganising-with-lfs/foo_bar/config.tar.gz
# `action` is a reserved keyword, only `expanding` action is currently supported
action = expand
# available options are [models|extensions|data]
destination = models
```

#### 3. Update documentation
Make a readme file named `README.md` in the `foo_bar` folder, make sure that you included
appropriate references, licenses information about the data you're sharing.

#### 4. Create GitHub pull requests
As a result of the previous steps, you should have created a new `foo_bar` entry with the following folder structure:
```
└── foo_bar
├── main.ini
├── README.md
├── data.tar.gz
├── config.tar.gz
└── weights.tar.gz
```
Now you can [send a pull request](https://help.github.com/articles/creating-a-pull-request/) to https://github.com/NifTK/NiftyNetModelZoo.


## Writing unit tests
*This section describes steps to create unit tests for NiftyNet.*

Expand Down Expand Up @@ -128,7 +240,7 @@ If the unit tests write files locally, please ensure it's writing to `NiftyNet/t
#### 4. Run tests locally
In NiftyNet source code folder, run:
```bash
python -m tests.[name]_test
python -m tests.[name]_test.py
```
make sure the test works locally.
The test should finish in a few seconds (using CPU). If it takes significantly longer, please set it as `slow test` in the file:
Expand Down Expand Up @@ -158,22 +270,9 @@ Please send a merge request with only relevant changes to a particular unit test

## NiftyNet admin tasks

### Adding release notes

The notes for NiftyNet releases are kept in the [NiftyNet changelog][changelog], and follow the ["keep a changelog"
standards][keep-a-changelog]. Notes should be added for each release, highlighting the changes in the appropriate
sections. See for instance [this commit][sample-changelog-commit]. Following the tagging of the new release on GitHub
(see the section below), the release notes can be synchronised with the [GitHub release page][github-release-page]
using [chandler][chandler]

[sample-changelog-commit]: https://github.com/NifTK/NiftyNet/commit/1d936d3b9cebb79cd58982863d8d5b97d3293511
[keep-a-changelog]: http://keepachangelog.com/
[github-release-page]: https://github.com/NifTK/NiftyNet/releases
[chandler]: https://github.com/mattbrictson/chandler

### Making a release

NiftyNet versions are numbered following [Semantic Versioning (semver)](https://semver.org/spec/v2.0.0.html).
NiftyNet versions are numbered following [Semantic Versioning (semver)](http://semver.org/spec/v2.0.0.html).
After adding notes for the current release to the [NiftyNet changelog][changelog], the current release should be [tagged][git-tag] with a [PEP440][pep440]-compliant semver number preceded by the letter `v` (for "version").

[pep440]: https://www.python.org/dev/peps/pep-0440/
Expand Down Expand Up @@ -234,34 +333,3 @@ For a practical example see [how the `net_segment` CLI command is implemented][n

[net-segment-entry]: https://github.com/NifTK/NiftyNet/blob/v0.3.0/setup.py#L107


## Bundling a pip installer

The NiftyNet pip installer gets bundled automatically for [Git tags][git-tag] starting with a `v` (for "version").
The [wheel version][wheel-version-tag] is determined automatically as part of this process.
The last few lines of the CI build log show the location of the bundled pip installer on the server, e.g.:

```bash
$ echo "Camera-ready pip installer bundle (wheel) created:"
Camera-ready pip installer bundle (wheel) created:
$ echo "$(ls $camera_ready_dir/*.whl)"
/home/gitlab-runner/environments/niftynet/pip/camera-ready/NiftyNet-0.2.0-py2.py3-none-any.whl
Job succeeded
```

In particular, bundling a pip installer boils down to running the command [`python setup.py bdist_wheel`][python-setuptools] in the top-level directory.
This creates a [wheel binary package][wheel-binary] in a newly created `dist` directory, e.g. `dist/NiftyNet-0.2.0-py2.py3-none-any.whl`.

[git-tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging
[python-setuptools]: https://packaging.python.org/tutorials/distributing-packages/#wheels
[wheel-binary]: https://www.python.org/dev/peps/pep-0491/


**If you have made changes to the pip installer, please test these.**
For instance if you have added a new [CLI entry point][pip-console-entry] (i.e. a new "command" - also see the respective section below),
make sure you include the appropriate tests in the [GitLab CI configuration][gitlab-ci-yaml].
For an example how to do this please see [lines 223 to 270 in the `.gitlab-ci.yml` file][gitlab-ci-pip-installer-test].

[pip-console-entry]: http://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-console-scripts-entry-point
[gitlab-ci-yaml]: https://docs.gitlab.com/ce/ci/yaml/
[gitlab-ci-pip-installer-test]: https://github.com/niftk/NiftyNet/blob/940d7a827d6835a4ce10637014c0c36b3c980476/.gitlab-ci.yml#L223
120 changes: 116 additions & 4 deletions doc/source/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,13 @@ The source code for NiftyNet is released via [GitHub][github-niftynet].
- [Submitting bug reports and feature requests](#submitting-bug-reports-and-feature-requests)
- [Submitting merge requests](#submitting-merge-requests)
- Python style guide
- Testing your changes
- Creating GitHub pull requests
- Test your changes
- Create GitHub pull requests
- [Submitting model zoo entries](#submitting-model-zoo-entries)
- Fork the model zoo repo
- Create new folder and add model zoo data
- Update documentation
- Create GitHub pull requests
- [Writing unit tests](#writing-unit-tests)
- Determine which module to test
- File an issue
Expand Down Expand Up @@ -50,7 +55,7 @@ In particular (from the guide):
[pep8]: https://www.python.org/dev/peps/pep-0008/


### 2. Testing your changes
### 2. Test your changes

Please submit merge requests from your branch to the `dev` branch.

Expand All @@ -62,7 +67,7 @@ cd NiftyNet/
sh run_test.sh
```

### 3. Creating GitHub pull requests
### 3. Create GitHub pull requests
1. **[on GitHub]** Sign up/in [GitHub.com](https://github.com/) (The rest steps assume GitHub user id: `nntestuser`).
1. **[on GitHub]** Go to [https://github.com/NifTK/NiftyNet](https://github.com/NifTK/NiftyNet), click the 'Fork' button.
1. Download the repo:
Expand All @@ -82,6 +87,113 @@ sh run_test.sh
1. **[on GitHub]** Create a pull request by clicking the 'pull request' button.


## Submitting model zoo entries
NiftyNet provides a version-controlled model zoo deployed on GitHub,
we welcome new model zoo entry submissions!

The model zoo is itself a GitHub project, the workflow of submitting new entries is in general the same as sending a
[GitHub pull request](https://help.github.com/articles/fork-a-repo/).

The following is a step-by-step guide for submitting a new entry named `foo_bar_model_zoo`.
After finishing these steps, all users will be able to download the model by running
NiftyNet command `net_download foo_bar_model_zoo`.

*`foo_bar_model_zoo` is a model zoo entry ID for demo purposes only, normally we prefer meaningful IDs,
which should briefly indicate the method, network architecture, and the task name.*

#### 1. Fork the model zoo repo
NiftyNet model zoo uses [Git Large File Storage -- git-lfs](https://git-lfs.github.com/) for large file (such as trained network weights) versioning.
Make sure you have installed `git-lfs` and file archiving tool `tar` beforehand.

[Fork and `git clone` the repo](https://help.github.com/articles/fork-a-repo/)
to your local machine, create a new folder called `foo_bar` within the codebase.
This folder will hold all the new content of the proposed entry.

#### 2. Create new folder and add model zoo data
Create a new folder `foo_bar_model_zoo` in the project folder where `foo_bar_model_zoo`
will be the model ID. When the model files are available in the repo,
the other users will download the model by running `net_download foo_bar_model_zoo`.

The new entry can be NiftyNet application configuration files, demo image data, or some trained weights,
or a combination of these data. These data should be archived into three `.tar.gz` files:
- `data.tar.gz`: for training/inference images, this will eventually go to the user's `~/niftynet/data/foo_bar` folder by default.
- `config.tar.gz`: for customised Python code, such as new loss functions, image samplers, as well as application configuration file.
This will go to the users `~/niftynet/extensions/foo_bar` folder by default.
- `weights.tar.gz`: for the trained weights, this will go to the user's `~/niftynet/models/foo_bar` folder by default.

We recommend that the `.tar.gz` files to be created by running, for example
```bash
tar -cvzf ../data.tar.gz ./input_demo_data.nii
```
The command will create an archive outside the current directory which contains the image `input_demo_data.nii` .
Un-archiving this file will output the images `input_demo_data.nii`

Similarly this can be done for the configuration files as well as Python codes:
```bash
tar -cvzf ../config.tar.gz ./myconfig*.ini
```

For the trained weights, we require the following specific folder structure:
```
└── highres3dnet_brain_parcellation
├── databrain_std_hist_models_otsu.txt
└── models
├── model.ckpt-33000.data-00000-of-00001
├── model.ckpt-33000.index
└── model.ckpt-33000.meta
```
Where `databrain_std_hist_models_otsu.txt` is a label or intensity histogram mapping file generated by NiftyNet;
`models` and `model.ckpt-*` names are compulsory: NiftyNet will always look for the `models` folder when reading the model zoo entry.

After having this folder structure, the archive file can be created by running:
```bash
cd highres3dnet_brain_parcellation/
tar -cvzf ../weights.tar.gz ./*
```

The outcome of this step should be several `.tar.gz` files within the `foo_bar` folder, within the cloned model zoo GitHub project:
```
└── foo_bar
├── data.tar.gz
├── config.tar.gz
└── weights.tar.gz
```

#### 2.5 Make a `main.ini`
Within `foo_bar` folder, create a `main.ini` file, with optional sections of
`[code]`, `[data]`, and `[weights]`. So that the end-users' `net_download` command
knows where to fetch and un-archive the shared data.

Each section should have the following values
```ini
[code]
# indicating the model zoo's ID
local_id = foo_bar
# the actual url for the .tar.gz
url = https://github.com/NifTK/NiftyNetModelZoo/raw/5-reorganising-with-lfs/foo_bar/config.tar.gz
# `action` is a reserved keyword, only `expanding` action is currently supported
action = expand
# available options are [models|extensions|data]
destination = models
```

#### 3. Update documentation
Make a readme file named `README.md` in the `foo_bar` folder, make sure that you included
appropriate references, licenses information about the data you're sharing.

#### 4. Create GitHub pull requests
As a result of the previous steps, you should have created a new `foo_bar` entry with the following folder structure:
```
└── foo_bar
├── main.ini
├── README.md
├── data.tar.gz
├── config.tar.gz
└── weights.tar.gz
```
Now you can [send a pull request](https://help.github.com/articles/creating-a-pull-request/) to https://github.com/NifTK/NiftyNetModelZoo.


## Writing unit tests
*This section describes steps to create unit tests for NiftyNet.*

Expand Down

0 comments on commit c093006

Please sign in to comment.