README.md 4.74 KB
Newer Older
Paul McCarthy's avatar
Paul McCarthy committed
1
# 2020 WIN PyTreat
Paul McCarthy's avatar
readme  
Paul McCarthy committed
2
3


Paul McCarthy's avatar
Paul McCarthy committed
4
This repository contains Jupyter notebooks and data for the 2020 WIN PyTreat.
Paul McCarthy's avatar
Paul McCarthy committed
5
6
7
8
It contains the following:

- The `talks` directory contains some (but not all) of the _Topyc_ talks that
  will be given throughout the week.
9
10
11
12
13
14
15
16
17
18
19

- 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_topics` 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.


Paul McCarthy's avatar
Paul McCarthy committed
20
The practicals have been written under the assumption that FSL 6.0.3 is
21
22
23
24
25
26
installed.


## For attendees


27
These notebooks can be run in the `fslpython` environment using:
28
29
30


```
31
git clone https://git.fmrib.ox.ac.uk/fsl/pytreat-practicals-2020.git
Paul McCarthy's avatar
Paul McCarthy committed
32
cd pytreat-practicals-2020
33
fslpython -m notebook
34
35
```

36
37
38
39
40
41
42
A page should open in your web browser - to access the practicals, navigate
into one of the `getting_started` or `advanced_topics` directories, and click
on the `.ipynb` file you are interested in. Some of the talks are also
presented in notebook form - navigate to the talk you are interested in
(within the `talks` directory), and click on the `.ipynb` file to follow
along.

43

Paul McCarthy's avatar
Paul McCarthy committed
44
45
46
47
48
49
Throughout the week we might make changes to this repository. When this
happens, we will ask you to update your local clone of the repository with the
following command:


```
Paul McCarthy's avatar
Paul McCarthy committed
50
git stash save
Paul McCarthy's avatar
Paul McCarthy committed
51
git pull origin master
Paul McCarthy's avatar
Paul McCarthy committed
52
git stash pop
Paul McCarthy's avatar
Paul McCarthy committed
53
54
55
```


56
57
58
59
Have fun!


## For contributors
Paul McCarthy's avatar
readme  
Paul McCarthy committed
60
61


Paul McCarthy's avatar
Paul McCarthy committed
62
The main repository can be found at:
Paul McCarthy's avatar
Paul McCarthy committed
63

Paul McCarthy's avatar
Paul McCarthy committed
64
https://git.fmrib.ox.ac.uk/fsl/pytreat-practicals-2020
Paul McCarthy's avatar
readme  
Paul McCarthy committed
65
66


Paul McCarthy's avatar
Paul McCarthy committed
67
Updates to the master branch should occur via merge requests. You can choose
Paul McCarthy's avatar
Paul McCarthy committed
68
69
to either work on a branch within this repository  (recommended), or on a fork of this
repository (advanced).
Paul McCarthy's avatar
Paul McCarthy committed
70

Paul McCarthy's avatar
Paul McCarthy committed
71
### Using a branch within this repository (recommended)
Paul McCarthy's avatar
Paul McCarthy committed
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

1. Make a local clone of the repository:

    ```
    git clone https://git.fmrib.ox.ac.uk/fsl/pytreat-practicals-2020.git
    ```

2. Create a branch for your work:

    ```
    git checkout -b my_cool_branch origin/master
    ```

3. Make your changes on this branch.

87
88
89
90
91
    ```
    git add <my_new_and_changed_files>
    git commit -m 'super cool updates'
    ```

Paul McCarthy's avatar
Paul McCarthy committed
92
93
94
95
96
97
98
99
100
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.

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
101
102
    https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html

Paul McCarthy's avatar
Paul McCarthy committed
103

Paul McCarthy's avatar
Paul McCarthy committed
104
### Using a fork of this repository (advanced)
Paul McCarthy's avatar
readme  
Paul McCarthy committed
105

Paul McCarthy's avatar
Paul McCarthy committed
106
1. Fork the upstream repository on gitlab
Paul McCarthy's avatar
readme  
Paul McCarthy committed
107

Paul McCarthy's avatar
Paul McCarthy committed
108
2. Make a local clone of your fork:
Paul McCarthy's avatar
readme  
Paul McCarthy committed
109

Paul McCarthy's avatar
Paul McCarthy committed
110
    ```
Paul McCarthy's avatar
Paul McCarthy committed
111
    git clone https://git.fmrib.ox.ac.uk/<your_username>/pytreat-practicals-2020.git
Paul McCarthy's avatar
Paul McCarthy committed
112
    ```
Paul McCarthy's avatar
Paul McCarthy committed
113
114
115

3. Add the upstream repository as a remote:

Paul McCarthy's avatar
Paul McCarthy committed
116
    ```
117
    git remote add upstream https://git.fmrib.ox.ac.uk/fsl/pytreat-practicals-2020.git
Paul McCarthy's avatar
Paul McCarthy committed
118
    ```
Paul McCarthy's avatar
Paul McCarthy committed
119
120
121

4. Make your changes on your local repository

122
123
124
125
126
    ```
    git add <my_new_and_changed_files>
    git commit -m 'super cool updates'
    ```

Paul McCarthy's avatar
Paul McCarthy committed
127
5. Push your changes to your fork:
Paul McCarthy's avatar
Paul McCarthy committed
128

Paul McCarthy's avatar
Paul McCarthy committed
129
    ```
Paul McCarthy's avatar
Paul McCarthy committed
130
    git push origin master
Paul McCarthy's avatar
Paul McCarthy committed
131
    ```
Paul McCarthy's avatar
Paul McCarthy committed
132
133
134

6. In gitlab, submit a merge request from your fork back to the upstream
   repository.
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
135
136
    
    https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html
Paul McCarthy's avatar
Paul McCarthy committed
137
138


Paul McCarthy's avatar
Paul McCarthy committed
139
### Updating your local repository
Paul McCarthy's avatar
Paul McCarthy committed
140

Paul McCarthy's avatar
Paul McCarthy committed
141
142
To bring in the changes that other people have contributed to the main
repository into your local repository:
Paul McCarthy's avatar
Paul McCarthy committed
143

Paul McCarthy's avatar
Paul McCarthy committed
144
145
```
git fetch --all
Paul McCarthy's avatar
Paul McCarthy committed
146

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
147
```
Paul McCarthy's avatar
Paul McCarthy committed
148

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
149
Then, do this if you are working on a branch within the main repository:
Paul McCarthy's avatar
Paul McCarthy committed
150

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
151
152
153
```
# make sure you are on the correct local branch:
git checkout my_cool_branch
Paul McCarthy's avatar
Paul McCarthy committed
154
git merge origin/master
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
155
```
Paul McCarthy's avatar
Paul McCarthy committed
156

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
157
158
159
Or, do this if you are working on a fork of the main repository:
```
git checkout master
Paul McCarthy's avatar
Paul McCarthy committed
160
git merge upstream/master
Paul McCarthy's avatar
Paul McCarthy committed
161
```
Paul McCarthy's avatar
Paul McCarthy committed
162

Paul McCarthy's avatar
Paul McCarthy committed
163
164
165
166
167
168
169

> Or, if you are comfortable with git, `rebase` is so much cooler:
>
> ```
> git fetch --all
>
> # replace <branch_name> with your local branch name
Paul McCarthy's avatar
Paul McCarthy committed
170
> git checkout <remote_name>/master
Paul McCarthy's avatar
Paul McCarthy committed
171
172
173
174
>
> # replace <remote_name> with the main repository name
> git rebase <remote_name>/master
> ```
Paul McCarthy's avatar
Paul McCarthy committed
175
176


Paul McCarthy's avatar
Paul McCarthy committed
177
178
179
### Writing your talk as a Jupyter notebook

You may wish to install [`notedown`](https://github.com/aaren/notedown):
Paul McCarthy's avatar
Paul McCarthy committed
180

Paul McCarthy's avatar
Paul McCarthy committed
181
```
Paul McCarthy's avatar
Paul McCarthy committed
182
$FSLDIR/fslpython/bin/conda install -n fslpython -c conda-forge notedown
Paul McCarthy's avatar
Paul McCarthy committed
183
184
185
ln -s $FSLDIR/fslpython/envs/fslpython/bin/notedown $FSLDIR/bin/fslnotedown
```

186
187
188
189
190
`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:
Paul McCarthy's avatar
Paul McCarthy committed
191
192
193


```
194
fslnotedown my_markdown_file.md > my_notebook.ipynb
Paul McCarthy's avatar
Paul McCarthy committed
195
```