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


4
5
This repository contains Python practicals for the WIN PyTreat series.  It
contains the following:
6
7
8
9
10

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

11
12
13
14
- 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.
15

16
- The `applications` directory contains a series of practicals which focus
Paul McCarthy's avatar
Readme    
Paul McCarthy committed
17
18
  on using Python to accomplish specific tasks, and practicals which introduce
  a range of useful Python-based libraries.
19

20
The practicals have been written under the assumption that FSL 6.0.4 is
21
22
23
installed.


24
## Instructions for attendees
25
26


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


```
31
32
git clone https://git.fmrib.ox.ac.uk/fsl/win-pytreat.git
cd win-pytreat
33
fslpython -m notebook
34
35
```

36
A page should open in your web browser - to access the practicals, navigate
37
38
into one of the `getting_started`, `advanced_programming`, or `applications`
directories, and click on the `.ipynb` file you are interested in.
Paul McCarthy's avatar
Paul McCarthy committed
39

Paul McCarthy's avatar
Readme    
Paul McCarthy committed
40
41
42
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 **before running the notebooks**.
Paul McCarthy's avatar
Paul McCarthy committed
43

44
45
46
Have fun!


47
## Instructions for contributors
Paul McCarthy's avatar
readme  
Paul McCarthy committed
48
49


50
The main Pytreat practical repository can be found at:
Paul McCarthy's avatar
Paul McCarthy committed
51

52
https://git.fmrib.ox.ac.uk/fsl/win-pytreat
Paul McCarthy's avatar
readme  
Paul McCarthy committed
53
54


Paul McCarthy's avatar
Paul McCarthy committed
55
Updates to the master branch should occur via merge requests. You can choose
56
57
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
58

Paul McCarthy's avatar
Paul McCarthy committed
59
### Using a branch within this repository (recommended)
Paul McCarthy's avatar
Paul McCarthy committed
60
61
62
63

1. Make a local clone of the repository:

    ```
64
    git clone https://git.fmrib.ox.ac.uk/fsl/win-pytreat.git
Paul McCarthy's avatar
Paul McCarthy committed
65
66
67
68
69
70
71
72
73
74
    ```

2. Create a branch for your work:

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

3. Make your changes on this branch.

75
76
77
78
79
    ```
    git add <my_new_and_changed_files>
    git commit -m 'super cool updates'
    ```

Paul McCarthy's avatar
Paul McCarthy committed
80
81
82
83
84
85
86
87
88
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
89
90
    https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html

Paul McCarthy's avatar
Paul McCarthy committed
91

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

Paul McCarthy's avatar
Paul McCarthy committed
94
1. Fork the upstream repository on gitlab
Paul McCarthy's avatar
readme  
Paul McCarthy committed
95

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

Paul McCarthy's avatar
Paul McCarthy committed
98
    ```
99
    git clone https://git.fmrib.ox.ac.uk/<your_username>/win-pytreat.git
Paul McCarthy's avatar
Paul McCarthy committed
100
    ```
Paul McCarthy's avatar
Paul McCarthy committed
101
102
103

3. Add the upstream repository as a remote:

Paul McCarthy's avatar
Paul McCarthy committed
104
    ```
105
    git remote add upstream https://git.fmrib.ox.ac.uk/fsl/win-pytreat.git
Paul McCarthy's avatar
Paul McCarthy committed
106
    ```
Paul McCarthy's avatar
Paul McCarthy committed
107
108
109

4. Make your changes on your local repository

110
111
112
113
114
    ```
    git add <my_new_and_changed_files>
    git commit -m 'super cool updates'
    ```

Paul McCarthy's avatar
Paul McCarthy committed
115
5. Push your changes to your fork:
Paul McCarthy's avatar
Paul McCarthy committed
116

Paul McCarthy's avatar
Paul McCarthy committed
117
    ```
Paul McCarthy's avatar
Paul McCarthy committed
118
    git push origin master
Paul McCarthy's avatar
Paul McCarthy committed
119
    ```
Paul McCarthy's avatar
Paul McCarthy committed
120
121
122

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

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
124
    https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html
Paul McCarthy's avatar
Paul McCarthy committed
125
126


Paul McCarthy's avatar
Paul McCarthy committed
127
### Updating your local repository
Paul McCarthy's avatar
Paul McCarthy committed
128

Paul McCarthy's avatar
Paul McCarthy committed
129
130
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
131

Paul McCarthy's avatar
Paul McCarthy committed
132
133
```
git fetch --all
Paul McCarthy's avatar
Paul McCarthy committed
134

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
135
```
Paul McCarthy's avatar
Paul McCarthy committed
136

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

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
139
140
141
```
# make sure you are on the correct local branch:
git checkout my_cool_branch
Paul McCarthy's avatar
Paul McCarthy committed
142
git merge origin/master
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
143
```
Paul McCarthy's avatar
Paul McCarthy committed
144

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
145
146
147
Or, do this if you are working on a fork of the main repository:
```
git checkout master
Paul McCarthy's avatar
Paul McCarthy committed
148
git merge upstream/master
Paul McCarthy's avatar
Paul McCarthy committed
149
```
Paul McCarthy's avatar
Paul McCarthy committed
150

Paul McCarthy's avatar
Paul McCarthy committed
151
152
153
154
155
156
157

> 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
158
> git checkout <remote_name>/master
Paul McCarthy's avatar
Paul McCarthy committed
159
160
161
162
>
> # replace <remote_name> with the main repository name
> git rebase <remote_name>/master
> ```
Paul McCarthy's avatar
Paul McCarthy committed
163
164


Paul McCarthy's avatar
Paul McCarthy committed
165
166
167
### 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
168

Paul McCarthy's avatar
Paul McCarthy committed
169
```
Paul McCarthy's avatar
Paul McCarthy committed
170
$FSLDIR/fslpython/bin/conda install -n fslpython -c conda-forge notedown
Paul McCarthy's avatar
Paul McCarthy committed
171
172
173
ln -s $FSLDIR/fslpython/envs/fslpython/bin/notedown $FSLDIR/bin/fslnotedown
```

174
175
176
177
178
`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
179
180
181


```
182
fslnotedown my_markdown_file.md > my_notebook.ipynb
Paul McCarthy's avatar
Paul McCarthy committed
183
```