Skip to content

Commit 09b0b7c

Browse files
hsteptoehsteptoe
authored
Merge v1.0 Develop into Master (#29)
* Issue #11, Implemented the changes proposed in Issue #11 * genraly style improvement and fixed a bug in the naming of the output files * implemented the changes suggested by Hamish in the pull request comments for issue#11 * corrected typos, made the style more consistent and added addtional description for clarity * code changes up to section 3.1c, where it is failing with a ValueError * Updates to worksheet 1 file locations to reflect corrected pp files * Add images * Other minor corrections to worksheet 1 * Add processing of cahpb to worksheet 1 * Add data retrieval scripts * Updates to python3 + consistency checks * Minor fix to outfile naming in worksheet 1 * Add code to remove extraneous metadata to make cube comparisons easier later * Clear all output * Add script to make future data for Sec. 2.9 * Update MASS retrieval scripts * Updates to 2b to reflect new file paths + other consistency edits * Add code for making data specific to 2b * Updates to data paths and minor plotting changes up to 3.1(b) * Fixes up to 3.3, plus try adding Contents links * Split final exercise of worksheet 3 into new worksheet 4 * Remove last section into worksheet 4. Other minor formatting changes * Add Contents cell to each worksheet * Add data compression settings on saving netcdf files * Update .gitignore * ÂRemove worksheet3 cell output * Add descriptions of available data and extreme indicies * Remove notebook checkpoints * Remove old 2017 notebooks * Add generator for chunking large daily future cube * Fix/structure final-draft edits (#28) Squashing and merging all changes following reviews by @rosannaamato and @cathrynjfox (covered in ticket #21 and pull request #28) in `develop` * Add environment.yml for python env building and Binder set-up * Add MO branding to all notebooks * Formatting updates and reorder info * Add conda environment details * Add worksheet summary and re-structure info * Update README.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Amended licence text * Create data README * Remove obsolete files from data dir * Update .gitignore with additional ipynb location * Initial commit of notebook style guide * Add info on CONTRIBUTING.ipynb * Update Contribution section * Add info on data
1 parent efe517a commit 09b0b7c

30 files changed

Lines changed: 5108 additions & 6024 deletions

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1+
.ipynb_checkpoints/
12
notebooks/.ipynb_checkpoints/
3+
/data/stash_select
24
*.pyc

‎CONTRIBUTING.ipynb‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# PyPRECIS Notebook Style Guide\n",
8+
"\n",
9+
"Thanks for showing the enthusiasm to help develop the PyPRECIS notebooks. Please use this style guide as a reference when creating or modifying content...\n",
10+
"\n",
11+
"## Worksheet Title\n",
12+
"\n",
13+
"All worksheets should start with a title formatted as a level 1 heading:\n",
14+
"\n",
15+
"```md\n",
16+
"# Worksheet ?: All Worksheets Should Have a Clear Title\n",
17+
"```\n",
18+
"\n",
19+
"Worksheet titles should be followed with a short description of the worksheet.\n",
20+
"\n",
21+
"## Learning Aims\n",
22+
"\n",
23+
"This followed by a list of 3 to 4 learning aims for the worksheet. We use the HTML `div class=\"alert alert-block alert-warning\"` to colour this is a nice way:\n",
24+
"\n",
25+
"```md\n",
26+
"<div class=\"alert alert-block alert-warning\">\n",
27+
"<b>By the end of this worksheet you should be able to:</b><br> \n",
28+
"- Identify and list the names of PRECIS output data in PP format using standard Linux commands.<br>\n",
29+
"- Use basic Iris commands to load data files, and view Iris cubes. <br>\n",
30+
"- Use Iris commands to remove the model rim, select data variables and save the output as NetCDF files.\n",
31+
"</div>\n",
32+
"```\n",
33+
"\n",
34+
"When rendered, it looks like this:\n",
35+
"\n",
36+
"<div class=\"alert alert-block alert-warning\">\n",
37+
"<b>By the end of this worksheet you should be able to:</b><br> \n",
38+
"- Identify and list the names of PRECIS output data in PP format using standard Linux commands.<br>\n",
39+
"- Use basic Iris commands to load data files, and view Iris cubes. <br>\n",
40+
"- Use Iris commands to remove the model rim, select data variables and save the output as NetCDF files.\n",
41+
"</div>\n",
42+
"\n",
43+
"Remember to start each learning aim with a verb. Keep them short and to the point. If you have more than 3 to 4 learning aims, consider whether there is too much content in the workbook.\n",
44+
"\n",
45+
"## Notes\n",
46+
"\n",
47+
"You may wish to use a Note box to draw the learners attention to particular actions or points to note. Note boxes are created using `div class=\"alert alert-block alert-info\"`\n",
48+
"\n",
49+
"```md\n",
50+
"<div class=\"alert alert-block alert-info\">\n",
51+
"<b>Note:</b> In the boxes where there is code or where you are asked to type code, click in the box, then press <kbd>Ctrl</kbd> + <kbd>Enter</kbd> to run the code. <br>\n",
52+
"<b>Note:</b> An percentage sign <code>%</code> is needed to run some commands on the shell. It is noted where this is needed.<br>\n",
53+
"<b>Note:</b> A hash <code>#</code> denotes a comment; anything written after this character does not affect the command being run. <br>\n",
54+
"</div>\n",
55+
"```\n",
56+
"\n",
57+
"Which looks like:\n",
58+
"\n",
59+
"<div class=\"alert alert-block alert-info\">\n",
60+
"<b>Note:</b> In the boxes where there is code or where you are asked to type code, click in the box, then press <kbd>Ctrl</kbd> + <kbd>Enter</kbd> to run the code. <br>\n",
61+
"<b>Note:</b> An percentage sign <code>%</code> is needed to run some commands on the shell. It is noted where this is needed.<br>\n",
62+
"<b>Note:</b> A hash <code>#</code> denotes a comment; anything written after this character does not affect the command being run. <br>\n",
63+
"</div>\n",
64+
"\n",
65+
"## Contents\n",
66+
"\n",
67+
"Immediately following the Learning Aims (or Note box if used) add a list of contents.\n",
68+
"\n",
69+
"```md\n",
70+
"## Contents\n",
71+
"### [1.1: Data locations and file names](#1.1) \n",
72+
"### ...additional headings\n",
73+
"```\n",
74+
"\n",
75+
"Items in the contents list are formatted as level 3 headings. Note the `[Link Name](Link location)` syntax. Each subsequent heading in the notebook needs to have a `id` tag associated with it for the links to work. These are formatted like this:\n",
76+
"\n",
77+
"```md\n",
78+
"<a id='1.1'></a>\n",
79+
"## 1.1 Data locations and file names\n",
80+
"```\n",
81+
"\n",
82+
"Remember that the `id` string must match the link location otherwise the link won't work. Remember to update both the link title numbering and the link id numbering if you are reordering content.\n",
83+
"\n",
84+
"## Section Headings\n",
85+
"\n",
86+
"To help users navigate round the document use section headings to break the content into sections. As detailed above, each section heading needs to have an `id` tag associated with it to build the Contents links.\n",
87+
"\n",
88+
"If you want to further subdivide each section, use bold letters with a parentheses:\n",
89+
"\n",
90+
"```md\n",
91+
"**a)** Ordinary section text continues...\n",
92+
"```\n",
93+
"\n",
94+
"## General Formatting\n",
95+
"\n",
96+
"Use links to point learners to additional learning resources. These follow the standard markdown style: `[Link text](Link location)`, eg.\n",
97+
"\n",
98+
"```md\n",
99+
"[Iris](http://scitools.org.uk/iris/docs/latest/index.html)\n",
100+
"```\n",
101+
"\n",
102+
"gives\n",
103+
"\n",
104+
"[Iris](http://scitools.org.uk/iris/docs/latest/index.html)\n",
105+
"\n",
106+
"Format key commands using bold back-ticks: \n",
107+
"\n",
108+
"```md\n",
109+
"**`cd`**\n",
110+
"```\n",
111+
"\n",
112+
"Where certain keyboard combinations are necessary to execute commands, use the `<kbd>` html formatting.\n",
113+
"\n",
114+
"\n",
115+
"```md\n",
116+
"<kbd>Ctrl</kbd> + <kbd>Enter</kbd>\n",
117+
"```\n",
118+
"\n",
119+
"which gives:\n",
120+
"\n",
121+
"<kbd>Ctrl</kbd> + <kbd>Enter</kbd>\n",
122+
"\n",
123+
"Code blocks are entered in new notebook cells, with the `Code` style. Remember, all python should be **Python 3**."
124+
]
125+
},
126+
{
127+
"cell_type": "code",
128+
"execution_count": 1,
129+
"metadata": {},
130+
"outputs": [],
131+
"source": [
132+
"# This is a code block\n",
133+
"# Make sure you include comments with your code to help explain what you are doing\n",
134+
"\n",
135+
"# Leave space if you want learners to complete portions of code\n",
136+
"\n"
137+
]
138+
},
139+
{
140+
"cell_type": "markdown",
141+
"metadata": {},
142+
"source": [
143+
"<div class=\"alert alert-block alert-info\">\n",
144+
"<b>Note:</b> Remember you can use additional Note blocks at any time to highlight important points!\n",
145+
"</div>\n",
146+
"\n",
147+
"If you want to add pictures, place image files in the `/notebooks/img` folder. Use html image formatting tags to control the position of the image in the rendered notebook cell:\n",
148+
"\n",
149+
"```md\n",
150+
"<p><img src=\"notebooks/img/python_and_iris.png\" alt=\"python + iris logo\" style=\"float: center; height: 100px;\"/></p>\n",
151+
"```\n",
152+
"\n",
153+
"gives\n",
154+
"\n",
155+
"<p><img src=\"notebooks/img/python_and_iris.png\" alt=\"python + iris logo\" style=\"float: center; height: 100px;\"/></p>\n",
156+
"\n",
157+
"Images can also be places in Note and Question blocks in the same manner. See Worksheet 1 for an example.\n",
158+
"\n",
159+
"## Questions\n",
160+
"\n",
161+
"Asking questions is a key part of the learning process. Questions blocks use the `div class=\"alert alert-block alert-success\"` style, and should be visually separated from the main text using horizontal rules above and below the question section:\n",
162+
"\n",
163+
"```md\n",
164+
"---\n",
165+
"<div class=\"alert alert-block alert-success\">\n",
166+
"<b>Question:</b> How many pp files are in this directory, in total?\n",
167+
"<br>How many of these pp files contain the string 'sep'; relating to September? What command do you need to use to find this out?\n",
168+
"</div>\n",
169+
"\n",
170+
"<b>Answer</b>: \n",
171+
"<br>*Total number of pp files: \n",
172+
"<br>Number of September pp files:\n",
173+
"<br>Command used to find number of september pp files:*\n",
174+
"\n",
175+
"---\n",
176+
"```\n",
177+
"\n",
178+
"This renders as:\n",
179+
"\n",
180+
"---\n",
181+
"<div class=\"alert alert-block alert-success\">\n",
182+
"<b>Question:</b> How many pp files are in this directory, in total?\n",
183+
"<br>How many of these pp files contain the string 'sep'; relating to September? What command do you need to use to find this out?\n",
184+
"</div>\n",
185+
"\n",
186+
"<b>Answer</b>: \n",
187+
"<br>*Total number of pp files: \n",
188+
"<br>Number of September pp files:\n",
189+
"<br>Command used to find number of september pp files:*\n",
190+
"\n",
191+
"---\n",
192+
"\n",
193+
"Make sure to put your _answer_ section in a different notebook cell from the _question_ section to avoid learners accidently editing the question blocks. Questions may also include code blocks. Remember to use a horizonal rule `---` to show where the question section starts and stops.\n",
194+
"\n",
195+
"## Worksheet footer\n",
196+
"\n",
197+
"At the end of the worksheet, summarise the content using a `div class=\"alert alert-block alert-warning\"`\n",
198+
"\n",
199+
"```md\n",
200+
"<center>\n",
201+
"<div class=\"alert alert-block alert-warning\">\n",
202+
"<b>This completes worksheet 1.</b> <br>You have created pre-processed files (rim removed, individual variables, concenated over time, in NetCDF format). <br>\n",
203+
"In worksheet 2, you will begin to analyse these files.\n",
204+
"</div>\n",
205+
"</center>\n",
206+
"```\n",
207+
"\n",
208+
"<center>\n",
209+
"<div class=\"alert alert-block alert-warning\">\n",
210+
"<b>This completes worksheet 1.</b> <br>You have created pre-processed files (rim removed, individual variables, concenated over time, in NetCDF format). <br>\n",
211+
"In worksheet 2, you will begin to analyse these files.\n",
212+
"</div>\n",
213+
"</center>\n",
214+
"\n",
215+
"Finally, a copyright statement and the Met Office logo should be added to all notebooks:\n",
216+
"\n",
217+
"```md\n",
218+
"<p><img src=\"img/MO_MASTER_black_mono_for_light_backg_RBG.png\" alt=\"python + iris logo\" style=\"float: center; height: 100px;\"/></p>\n",
219+
"<center>© Crown Copyright 2019, Met Office</center>\n",
220+
"```"
221+
]
222+
},
223+
{
224+
"cell_type": "markdown",
225+
"metadata": {},
226+
"source": [
227+
"<p><img src=\"notebooks/img/MO_MASTER_black_mono_for_light_backg_RBG.png\" alt=\"Met Office logo\" style=\"float: center; height: 100px;\"/></p>\n",
228+
"<center>© Crown Copyright 2019, Met Office</center>"
229+
]
230+
}
231+
],
232+
"metadata": {
233+
"kernelspec": {
234+
"display_name": "Python 3",
235+
"language": "python",
236+
"name": "python3"
237+
},
238+
"language_info": {
239+
"codemirror_mode": {
240+
"name": "ipython",
241+
"version": 3
242+
},
243+
"file_extension": ".py",
244+
"mimetype": "text/x-python",
245+
"name": "python",
246+
"nbconvert_exporter": "python",
247+
"pygments_lexer": "ipython3",
248+
"version": "3.6.8"
249+
}
250+
},
251+
"nbformat": 4,
252+
"nbformat_minor": 2
253+
}

‎CONTRIBUTING.md‎

Lines changed: 55 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,70 @@
11
# Contributing Guidelines
22

3-
Please take note of the following guidelines when contributing to the PyPRECIS repository:
3+
You'd like to help? Great! :tada:
44

5-
* Please do **not** make changes to the `master` branch. The `master` branch is reserved for files and code that has been fully tested and reviewed. If you think something is ready to be pushed to the `master` branch please check with Saeed or Hamish first.
6-
* The `develop` branch contains the latest holistic version of the `PyPRECIS` repository. Please branch off `develop` to fix a particular issue or add a new feature.
7-
* Please use the following tokens at the start of a new branch name to help sign-post and group branches:
5+
[Clone your own local copy](https://help.github.com/en/articles/cloning-a-repository) of this repositry run the following in your terminal:
6+
7+
```shell
8+
git clone git@github.com:MetOffice/PyPRECIS.git
89
```
9-
new Branch adding new code/files that don't exist in the repo.
10-
fix Branch modifying code/files that already exist in the repo.
11-
junk Throwaway branch created to experiment
10+
11+
Consider [creating a conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) from the PyPRECIS dependencies specified in the `environment.yml` file:
12+
```shell
13+
conda env create -f environment.yml
1214
```
13-
Git can pattern match branches to to give you an overview of all (e.g. fix) branches:
14-
```
15+
Remember to activate your new environment:
16+
```shell
17+
conda activate pyprecis-environment
18+
```
19+
20+
:exclamation: *Note: As of v1.0 we are unable to provison the model data necessary for reproducing the full PyPRECIS learning environment via github due to it's substanation size. Contact the PRECIS team for more information.*
21+
22+
## Before you start...
23+
Read through the current issues to see what you can help with. If you have your own ideas for improvements, please start a new issues so we can track and discuss your improvement. You must create a new branch for any changes you make.
24+
25+
**Please take note of the following guidelines when contributing to the PyPRECIS repository.**
26+
27+
* Please do **not** make changes to the `master` branch. The `master` branch is reserved for files and code that has been fully tested and reviewed. Only the core PyPRECIS developers can/should push to the `master` branch.
28+
29+
* The `develop` branch contains the latest holistic version of the `PyPRECIS` repository. Please branch off `develop` to fix a particular issue or add a new feature.
30+
* Please use the following tokens at the start of a new branch name to help sign-post and group branches:
31+
32+
Name | Description
33+
---- | -----------
34+
new | Branch adding new code/files that don't exist in the repo
35+
fix | Branch modifying code/files that already exist in the repo.
36+
junk | Throwaway branch created to experiment
37+
38+
* Git can pattern match branches to to give you an overview of all (e.g. fix) branches:
39+
```shell
1540
git branch --list "fix/*"
1641
```
1742
* Use a forward slash to separate the token from the branch name. For example:
1843
```
19-
new/Worksheet5
20-
fix/worksheet2aUnits
44+
new/Wks10
45+
fix/Wks2_units
2146
```
47+
* When you think your branch is ready to be merged into `develop`, open a new pull request.
48+
49+
## Signposting
50+
* **Issues** are tracked and discussed under the Issues tab. Please use issues to disucss proposed changes or capture improvements needed to work towards the next milestone. Issues or improvements that contribute to the next milestone to be captured in thr Wiki tab.
51+
* **Pull requests** show branches that are currently under review. New pull requests are created in reponse to branch fixes identified and recorded in the Issues tab.
52+
* **Wiki** is used for summarising update aims for future versions of the notebooks, and to record speculative improvements that cannot be action in the current milestone.
53+
54+
2255

2356
Other more general points to note:
2457

25-
* **Avoid long descriptive names.** Long branch names can be very helpful when you are looking at a list of branches. But it can get in the way when looking at decorated one-line logs as the branch names can eat up most of the single line and abbreviate the visible part of the log.
58+
* **Avoid long descriptive names.** Long branch names can be very helpful when you are looking at a list of branches but it can get in the way when looking at decorated one-line logs as the branch names can eat up most of the single line and abbreviate the visible part of the log.
2659
* **Do not use bare numbers.** Do not use use bare numbers (or hex numbers) as part of your branch naming scheme.
2760

28-
**If in doubt, please contact Saeed Sadri (saeed.sadri@metoffice.gov.uk) or Hamish Steptoe (hamish.steptoe@metoffice.gov.uk) if you
29-
have questions**
61+
## CONTRIBUTING.ipynb
62+
The `CONTRIBUTING.ipyn` file contains the worksheet style guide. Please consult this for information on formatting the new and ammended worksheets in a consistent style.
63+
64+
**If in doubt, please contact the PRECIS team (precis@metoffice.gov.uk) if you
65+
have questions.**
66+
67+
<h5 align="center">
68+
<img src="notebooks/img/MO_MASTER_black_mono_for_light_backg_RBG.png" width="200" alt="Met Office"> <br>
69+
&copy; British Crown Copyright 2018 - 2019, Met Office
70+
</h5>

0 commit comments

Comments
 (0)