How to add a review

The process for adding reviews is git-centric. Basically, you just need to add a file to the repo and make a pull request. Let’s go into the details :

  1. Send an e-mail to Pierre-Marc Jodoin asking him to include you as a member of the organization.
  2. Clone the repo on your computer.
  3. Set up the pre-commit hooks by executing the utils/ script.
  4. Determine the category in which you will add your post. Categories are managed using folders :

    _posts/           # A post added here will have no category
        _posts/       # A post added here will be in the "course" category
        _posts/       # Same thing for the "machine-learning" category
    ...               # There are other categories, you can add one too.
  5. Create a file YYYY-MM-DD-title-of-your-review.markdown and put it in right folder (see above).
    It is important that you respect this format : date at the beginning and no spaces. Else the page won’t build properly. Here is an example of a valid name : 2017-01-31-going-deeper-with-convolutions.markdown.
  6. Use the review template file in the templates as a starting point and do your review.

    A minimal working review example may look like:

    layout: review
    title: U-Net Convolutional Networks for Biomedical Image Segmentation
    tags: deep-learning CNN segmentation medical essentials
        authors: "O. Ronneberger, P. Fischer, T. Brox"
        title:   "U-Net: Convolutional Networks for Biomedical Image Segmentation"
        venue:   "Proceedings of MICCAI 2015, p.234-241"
    pdf: ""
    # Introduction
    Famous 2D image segmentation CNN made of a series of convolutions and
    deconvolutions. The convolution feature maps are connected to the deconv maps of
    the same size. The network was tested on the 2 class 2D ISBI cell segmentation
    Used the crossentropy loss and a lot of data augmentation.
    The network architecture:
    A U-Net is based on Fully Convolutional Networks (FCNNs)[^1].
    The loss used is a cross-entropy:
    $$ E = \sum_{x \in \Omega} w(\bold{x}) \log (p_{l(\bold{x})}(\bold{x})) $$
    The U-Net architecture is used by many authors, and has been re-visited in
    many reviews, such as in [this one](
    # References
    [^1]: Jonathan Long, Evan Shelhamer, and Trevor Darrell. Fully convolutional
          networks for semantic segmentation (2014). arXiv:1411.4038.

    The list of available tags can be modified to include new tags. The current ones are:

action-recognition active-learning adversarial attention
attention-maps auto-ml autoencoder benchmarking
blog bounding-boxes brain caption
cardiac classification clustering codebook
course ct-scan dMRI data-augmentation
dataset deep-learning denoising detection
dimensionality-reduction domain-adaptation essentials face-detection
few-shot-learning genetic-algorithm graph-cut hyperspectral
imitation-learning inpainting k-means layers
localization machine-learning medical meta-learning
motion-detection multi-agent multi-task multi-task-learning
multiple-sclerosis network-compression network-pruning neural-network
one-shot-segmentation optimization pedestrian-detection point-cloud
pruning-acceleration reinforcement remote-sensing representation-learning
segmentation self-supervised semi-supervised sequence
shape-analysis siamese surveillance survey
synthesis tractography tractometry traffic
transfer-learning transformer unsupervised video-analysis
weakly-supervised white-matter

NOTE: the essentials tags is used for any paper considered as being a “must-read”.

For further information about Jekyll’s syntax, visit the documentation page. However, note that Jekyll’s syntax may change in newer versions, and the site’s version is freezed. Hence, although Liquid tags could be used for links, for example, plain old links are used to avoid issues building the site.

You can preview your post while you write it ; see the next section about this.\

  1. Make a new branch, commit your file and push your branch.
  2. Create a pull request on the repo’s github page.
  3. Add reviewers: everyone that you think are knowledgeable about the subject or simply would be interested in your review.
  4. When every reviewer approved your branch, merge your branch and delete it.

How to preview your post locally

This site is built around Jekyll. Jekyll takes all the markdown files and generates a static html website.

  1. Install Ruby using rbenv. Don’t use apt-get since its version of Ruby is too old.
  2. Install bundler by running : gem install bundler:2.1.4.
  3. Go where you cloned the VITAL literature review repository and run : bundle install. This will install the dependencies for our Jekyll site.
  4. Run a local webserver using : bundle exec jekyll serve.
  5. Access the site locally at :

Note that the site is automatically rebuilt when a file has been modified.


Running bundle install or bundle exec jekyll serve does not work

If you previously installed a version of this repo and it now does not work, you may have a version mismatch. To clean and reinstall, try to comment all gems specification in Gemfile and then run

$ bundle clean --force

then uncomment your changes in Gemfile and run

$ bundle install

If that does not resolve your problem, you may have a tooling version mismatch. The error messages following bundle install should provide some information. Otherwise, do not hesitate to create an issue on Github or leave a message of the VITAL slack to get some help.

Running bundle install has modified Gemfile.lock

This is likely happening because you don’t have Ruby 2.7.1. Confirm by running git diff. If you see something like this:

-   ruby 2.7.1
+   ruby 2.4.0p0

it confirms that you need to upgrade ruby. To do so, run the following commands:

rbenv install 2.7.1
rbenv global 2.7.1
rbenv uninstall 2.4.0  # you can uninstall the old version
gem install bundler:2.1.4  # need to install bundler after upgrading ruby
bundle install

After this, there shouldn’t be changes on Gemfile.lock.