README.md

WIN PyTreat series

This repository contains Python practicals for the WIN PyTreat series. It contains the following:

• The getting_started directory contains a series of practicals intended for those of you who are new to the Python programming language, or need a refresher.

• The advanced_programming directory contains a series of practicals on various aspects of the Python programming language - these are intended for those of you who are familiar with the basics of Python, and want to learn more about the language.

• The applications directory contains a series of practicals which focus on using Python to accomplish specific tasks.

The practicals have been written under the assumption that FSL 6.0.4 is installed.

Instructions for attendees

These notebooks can be run in the fslpython environment using:

git clone https://git.fmrib.ox.ac.uk/fsl/win-pytreat.git
cd win-pytreat
fslpython -m notebook

A page should open in your web browser - to access the practicals, navigate into one of the getting_started, advanced_programming, or applications directories, and click on the .ipynb file you are interested in.

Some practical sub-directories will also contain a README.md file with additional information specific to the practical. Make sure you read this as well.

Have fun!

Instructions for contributors

The main Pytreat practical repository can be found at:

https://git.fmrib.ox.ac.uk/fsl/win-pytreat

Updates to the master branch should occur via merge requests. You can choose to either work on a branch within this repository (recommended), or on a fork of this repository (advanced).

Using a branch within this repository (recommended)

1. Make a local clone of the repository:

   git clone https://git.fmrib.ox.ac.uk/fsl/win-pytreat.git

2. Create a branch for your work:

   git checkout -b my_cool_branch origin/master

3. Make your changes on this branch.

   git add <my_new_and_changed_files>
   git commit -m 'super cool updates'

4. Push your changes to the gitlab repository:

   git push origin my_cool_branch

5. In gitlab, submit a merge request from your branch onto the master branch.

   https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html

Using a fork of this repository (advanced)

1. Fork the upstream repository on gitlab

2. Make a local clone of your fork:

   git clone https://git.fmrib.ox.ac.uk/<your_username>/win-pytreat.git

3. Add the upstream repository as a remote:

   git remote add upstream https://git.fmrib.ox.ac.uk/fsl/win-pytreat.git

4. Make your changes on your local repository

   git add <my_new_and_changed_files>
   git commit -m 'super cool updates'

5. Push your changes to your fork:

   git push origin master

6. In gitlab, submit a merge request from your fork back to the upstream repository.

   https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html

Updating your local repository

To bring in the changes that other people have contributed to the main repository into your local repository:

git fetch --all

Then, do this if you are working on a branch within the main repository:

# make sure you are on the correct local branch:
git checkout my_cool_branch
git merge origin/master

Or, do this if you are working on a fork of the main repository:

git checkout master
git merge upstream/master

Or, if you are comfortable with git, rebase is so much cooler:

git fetch --all

# replace <branch_name> with your local branch name
git checkout <remote_name>/master

# replace <remote_name> with the main repository name
git rebase <remote_name>/master

Writing your talk as a Jupyter notebook

You may wish to install notedown:

$FSLDIR/fslpython/bin/conda install -n fslpython -c conda-forge notedown
ln -s $FSLDIR/fslpython/envs/fslpython/bin/notedown $FSLDIR/bin/fslnotedown

notedown is a handy tool which allows you to convert a markdown (.md) file to a Jupyter notebook (.ipynb) file. So you can write your practical in your text editor of choice, and then convert it into a notebook, instead of writing the practical in the web browser interface. If you install notedown as suggested in the code block above, you can run it on a markdown file like so:

fslnotedown my_markdown_file.md > my_notebook.ipynb