README.md 4.52 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
17
- The `applications` directory contains a series of practicals which focus
  on using Python to accomplish specific tasks.
18

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


23
## Instructions for attendees
24
25


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


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

35
A page should open in your web browser - to access the practicals, navigate
36
37
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
38

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
39
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
40

41
42
43
Have fun!


44
## Instructions for contributors
Paul McCarthy's avatar
readme    
Paul McCarthy committed
45
46


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

49
https://git.fmrib.ox.ac.uk/fsl/win-pytreat
Paul McCarthy's avatar
readme    
Paul McCarthy committed
50
51


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

Paul McCarthy's avatar
Paul McCarthy committed
56
### Using a branch within this repository (recommended)
Paul McCarthy's avatar
Paul McCarthy committed
57
58
59
60

1. Make a local clone of the repository:

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

2. Create a branch for your work:

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

3. Make your changes on this branch.

72
73
74
75
76
    ```
    git add <my_new_and_changed_files>
    git commit -m 'super cool updates'
    ```

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

Paul McCarthy's avatar
Paul McCarthy committed
88

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

Paul McCarthy's avatar
Paul McCarthy committed
91
1. Fork the upstream repository on gitlab
Paul McCarthy's avatar
readme    
Paul McCarthy committed
92

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

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

3. Add the upstream repository as a remote:

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

4. Make your changes on your local repository

107
108
109
110
111
    ```
    git add <my_new_and_changed_files>
    git commit -m 'super cool updates'
    ```

Paul McCarthy's avatar
Paul McCarthy committed
112
5. Push your changes to your fork:
Paul McCarthy's avatar
Paul McCarthy committed
113

Paul McCarthy's avatar
Paul McCarthy committed
114
    ```
Paul McCarthy's avatar
Paul McCarthy committed
115
    git push origin master
Paul McCarthy's avatar
Paul McCarthy committed
116
    ```
Paul McCarthy's avatar
Paul McCarthy committed
117
118
119

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

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
121
    https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html
Paul McCarthy's avatar
Paul McCarthy committed
122
123


Paul McCarthy's avatar
Paul McCarthy committed
124
### Updating your local repository
Paul McCarthy's avatar
Paul McCarthy committed
125

Paul McCarthy's avatar
Paul McCarthy committed
126
127
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
128

Paul McCarthy's avatar
Paul McCarthy committed
129
130
```
git fetch --all
Paul McCarthy's avatar
Paul McCarthy committed
131

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
132
```
Paul McCarthy's avatar
Paul McCarthy committed
133

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

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

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

Paul McCarthy's avatar
Paul McCarthy committed
148
149
150
151
152
153
154

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


Paul McCarthy's avatar
Paul McCarthy committed
162
163
164
### 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
165

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

171
172
173
174
175
`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
176
177
178


```
179
fslnotedown my_markdown_file.md > my_notebook.ipynb
Paul McCarthy's avatar
Paul McCarthy committed
180
```