|
8 | 8 | } |
9 | 9 | }, |
10 | 10 | "source": [ |
11 | | - "# Miscellaneous CLIMADA conventions" |
12 | | - ] |
13 | | - }, |
14 | | - { |
15 | | - "cell_type": "markdown", |
16 | | - "metadata": { |
17 | | - "slideshow": { |
18 | | - "slide_type": "slide" |
19 | | - }, |
20 | | - "tags": [], |
21 | | - "toc": true |
22 | | - }, |
23 | | - "source": [ |
24 | | - "## Contents\n", |
25 | | - "\n", |
26 | | - "- [Dependencies (python packages)](#Dependencies-(python-packages))\n", |
27 | | - "- [Class inheritance](#Class-inheritance)\n", |
28 | | - "- [Does it belong into CLIMADA?](#Does-it-belong-into-CLIMADA?)\n", |
29 | | - "- [Paper repository](#Paper-repository)\n", |
30 | | - "- [Utility function](#Utility-function)\n", |
31 | | - "- [Impact function renaming - if to impf](#Impact-function-renaming---if-to-impf)\n", |
32 | | - "- [Data dependencies](#Data-dependencies)\n", |
33 | | - "- [Side Note on Parameters](#Side-Note-on-Parameters)" |
| 11 | + "# CLIMADA coding conventions" |
34 | 12 | ] |
35 | 13 | }, |
36 | 14 | { |
|
59 | 37 | "Thus, when you are coding, follow these priorities:\n", |
60 | 38 | "\n", |
61 | 39 | "1. [Python standard library](https://docs.python.org/3/library/index.html)\n", |
62 | | - "2. Funktions and methods already implemented in CLIMADA (do NOT introduce circulary imports though)\n", |
| 40 | + "2. Functions and methods already implemented in CLIMADA (do NOT introduce circulary imports though)\n", |
63 | 41 | "3. [Packages already included in CLIMADA](https://github.com/CLIMADA-project/climada_python/network/dependencies)\n", |
64 | 42 | "4. Before adding a new dependency: \n", |
65 | 43 | " - Contact a [repository admin](https://github.com/CLIMADA-project/climada_python/wiki/Developer-Board) to get permission\n", |
66 | 44 | " - Open an [issue](https://github.com/CLIMADA-project/climada_python/issues)\n", |
67 | 45 | " \n", |
68 | | - "Hence, first try to solve your problem with the standard library and function/methods already implemented in CLIMADA (see in particular the [util functions](#id)) then use the packages included in CLIMADA, and if this is not enough, propose the addition of a new package. Do not hesitate to propose new packages if this is needed for your work!" |
| 46 | + "Hence, first try to solve your problem with the standard library and function/methods already implemented in CLIMADA (see in particular the [utility functions](#Utility-functions)) then use the packages included in CLIMADA, and if this is not enough, propose the addition of a new package. Do not hesitate to propose new packages if this is needed for your work!" |
69 | 47 | ] |
70 | 48 | }, |
71 | 49 | { |
|
81 | 59 | "source": [ |
82 | 60 | "In Python, a [class can inherit from other classes](https://docs.python.org/3/tutorial/classes.html), which is a very useful mechanism in certain circumstances. However, it is wise to think about inheritance before implementing it. Very important, is that CLIMADA classes do not inherit from external library classes. For example, Exposure directly inherited from Geopandas. This caused problems in CLIMADA when the package Geopandas was updated.\n", |
83 | 61 | "\n", |
84 | | - "**CLIMADA classes shall NOT inherit classes from external modules**" |
85 | | - ] |
86 | | - }, |
87 | | - { |
88 | | - "cell_type": "markdown", |
89 | | - "metadata": { |
90 | | - "slideshow": { |
91 | | - "slide_type": "slide" |
92 | | - } |
93 | | - }, |
94 | | - "source": [ |
95 | | - "## Does it belong into CLIMADA? " |
96 | | - ] |
97 | | - }, |
98 | | - { |
99 | | - "cell_type": "markdown", |
100 | | - "metadata": { |
101 | | - "slideshow": { |
102 | | - "slide_type": "slide" |
103 | | - } |
104 | | - }, |
105 | | - "source": [ |
106 | | - "When developing for CLIMADA, it is important to distinguish between core content and particular applications. Core content is meant to be included into the [climada_python](https://github.com/CLIMADA-project/climada_python) repository and will be subject to a code review. Any new addition should first be discussed with one of the [repository admins](https://github.com/CLIMADA-project/climada_python/wiki/Developer-Board). The purpose of this discussion is to see\n", |
107 | | - "\n", |
108 | | - "- How does the planed module fit into CLIMADA?\n", |
109 | | - "- What is an optimal architecture for the new module?\n", |
110 | | - "- What parts might already exist in other parts of the code?\n", |
111 | | - "\n", |
112 | | - "Applications made with CLIMADA, such as an [ECA study](https://eca-network.org/) can be stored in the [paper repository](https://github.com/CLIMADA-project/climada_papers) once they have been published. For other types of work, consider making a separate repository that imports CLIMADA as an external package." |
| 62 | + "**CLIMADA classes shall NOT inherit classes from external modules.**" |
113 | 63 | ] |
114 | 64 | }, |
115 | 65 | { |
|
131 | 81 | } |
132 | 82 | }, |
133 | 83 | "source": [ |
134 | | - "Applications made with CLIMADA which are published in the form of a paper or a report are very much encouraged to be submited to the [climada/paper](https://github.com/CLIMADA-project/climada_papers) repository. You can either:\n", |
| 84 | + "Applications made with CLIMADA which are published in the form of a paper or a report are very much encouraged to be submitted to the [climada/paper](https://github.com/CLIMADA-project/climada_papers) repository. You can either:\n", |
135 | 85 | "\n", |
136 | 86 | "- Prepare a well-commented jupyter notebook with the code necessary to reproduce your results and upload it to the [climada/paper](https://github.com/CLIMADA-project/climada_papers) repository. Note however that the repository cannot be used for storing data files.\n", |
137 | 87 | "- Upload the code necessary to reproduce your results to a separate repository of your own. Then, add a link to your repository and to your publication to the readme file on the [climada/paper](https://github.com/CLIMADA-project/climada_papers) repository.\n", |
138 | 88 | "\n", |
139 | 89 | "**Notes about DOI**\n", |
140 | 90 | "\n", |
141 | | - "Some journals requires you to provide a DOI to the code and data used for your publication. In this case, we encourage to create a separate repository for your code and create a DOI using [Zenodo](https://zenodo.org/) or any specific service from your institution (e.g. [ETH Zürich](https://documentation.library.ethz.ch/display/DOID/DOI+Registration+Manual)).\n", |
| 91 | + "Some journals require you to provide a DOI to the code and data used for your publication. In this case, we encourage you to create a separate repository for your code and create a DOI using [Zenodo](https://zenodo.org/) or any specific service from your institution (e.g. [ETH Zürich](https://documentation.library.ethz.ch/display/DOID/DOI+Registration+Manual)).\n", |
142 | 92 | "\n", |
143 | 93 | "The CLIMADA releases are also identified with a DOI." |
144 | 94 | ] |
|
151 | 101 | } |
152 | 102 | }, |
153 | 103 | "source": [ |
154 | | - "## Utility function" |
| 104 | + "## Utility functions" |
155 | 105 | ] |
156 | 106 | }, |
157 | 107 | { |
|
175 | 125 | "It is very important to not reinvent the wheel and to avoid unnecessary redundancies in the code. This makes maintenance and debugging very tedious.\n" |
176 | 126 | ] |
177 | 127 | }, |
178 | | - { |
179 | | - "cell_type": "markdown", |
180 | | - "metadata": { |
181 | | - "slideshow": { |
182 | | - "slide_type": "slide" |
183 | | - } |
184 | | - }, |
185 | | - "source": [ |
186 | | - "## Impact function renaming - if to impf " |
187 | | - ] |
188 | | - }, |
189 | | - { |
190 | | - "cell_type": "markdown", |
191 | | - "metadata": { |
192 | | - "slideshow": { |
193 | | - "slide_type": "slide" |
194 | | - } |
195 | | - }, |
196 | | - "source": [ |
197 | | - "In the original CLIMADA code, the impact function is often referred to as `if` or `if_`. This is easy to confuse with the conditional operator *if*. Hence, in future a transition from\n", |
198 | | - "\n", |
199 | | - "`if` ---------> `impf`\n", |
200 | | - "\n", |
201 | | - "will be performed. Once the change is active, known developers will be notified and this message updated." |
202 | | - ] |
203 | | - }, |
204 | 128 | { |
205 | 129 | "cell_type": "markdown", |
206 | 130 | "metadata": {}, |
|
221 | 145 | "\n", |
222 | 146 | "As indicated in the software and tutorials, other data might need to be downloaded manually by the user. The following table shows these last data sources, their version used, its current availability and where they are used within CLIMADA:\n", |
223 | 147 | "\n", |
224 | | - "| Availability | Name | Version | Link | CLIMADA class | CLIMADA version | CLIMADA tutorial reference |\n", |
225 | | - "|--------------|-------------------------------------------------|---------|------|---------------|-----------------|-------------------------------|\n", |
226 | | - "| OK | Fire Information for Resource Management System | |[FIRMS](https://firms.modaps.eosdis.nasa.gov/download/) | BushFire | >V1.2.5 | climada_hazard_BushFire.ipynb |\n", |
227 | | - "| OK | Gridded Population of the World (GPW) | v4.11 |[GPW4.11](https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-count-rev11) | LitPop | > v1.2.3 | climada_entity_LitPop.ipynb |\n", |
228 | | - "| FAILED | Gridded Population of the World (GPW) | v4.10 |[GPW1.10](https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-count-rev10) | LitPop | >= v1.2.0 | climada_entity_LitPop.ipynb |\n", |
229 | | - "| | | | | | | |" |
| 148 | + "| Name | Version | Link | CLIMADA class | CLIMADA version | CLIMADA tutorial reference |\n", |
| 149 | + "|-------------------------------------------------|---------|------|---------------|-----------------|-------------------------------|\n", |
| 150 | + "| Fire Information for Resource Management System | |[FIRMS](https://firms.modaps.eosdis.nasa.gov/download/) | BushFire | > v1.2.5 | climada_hazard_BushFire.ipynb |\n", |
| 151 | + "| Gridded Population of the World (GPW) | v4.11 |[GPW4.11](https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-count-rev11) | LitPop | > v1.2.3 | climada_entity_LitPop.ipynb |\n" |
230 | 152 | ] |
231 | 153 | }, |
232 | 154 | { |
233 | 155 | "cell_type": "markdown", |
234 | 156 | "metadata": {}, |
235 | 157 | "source": [ |
236 | | - "## Side Note on Parameters" |
| 158 | + "## Side note on parameters" |
237 | 159 | ] |
238 | 160 | }, |
239 | 161 | { |
|
249 | 171 | }, |
250 | 172 | { |
251 | 173 | "cell_type": "code", |
252 | | - "execution_count": 4, |
| 174 | + "execution_count": 2, |
253 | 175 | "metadata": {}, |
254 | 176 | "outputs": [ |
255 | 177 | { |
|
276 | 198 | }, |
277 | 199 | { |
278 | 200 | "cell_type": "code", |
279 | | - "execution_count": null, |
| 201 | + "execution_count": 3, |
280 | 202 | "metadata": {}, |
281 | | - "outputs": [], |
| 203 | + "outputs": [ |
| 204 | + { |
| 205 | + "name": "stdout", |
| 206 | + "output_type": "stream", |
| 207 | + "text": [ |
| 208 | + "1 2 6\n" |
| 209 | + ] |
| 210 | + } |
| 211 | + ], |
282 | 212 | "source": [ |
283 | 213 | "# usually just fine\n", |
284 | 214 | "def g(x, y, z):\n", |
|
295 | 225 | "### Decrease the number of parameters.\n", |
296 | 226 | "\n", |
297 | 227 | "Though CLIMADA's pylint configuration .pylintrc allows 7 arguments for any method or function before it complains, it is advisable to aim for less.\n", |
298 | | - "It is quite likely that a function with so many parameters has an inherent design flaw.\\\n", |
| 228 | + "It is quite likely that a function with so many parameters has an inherent design flaw.\n", |
299 | 229 | "\n", |
300 | | - "There are very well designed command line tools with innumerable optional arguments, e.g., rsync - but these are command line tools. There are also methods like pandas.DataFrame.plot() with countless optional arguments and it makes perfectly sense.\n", |
| 230 | + "There are very well designed command line tools with inumerable optional arguments, e.g., rsync - but these are command line tools. There are also methods like `pandas.DataFrame.plot()` with countless optional arguments and it makes perfectly sense.\n", |
301 | 231 | "\n", |
302 | 232 | "But within the climada package it probably doesn't.\n", |
303 | 233 | "divide et impera!\n", |
|
332 | 262 | "def f(a, b, c, d, e, f, g, h):\n", |
333 | 263 | " print(f'f does many things with a lot of arguments: {a, b, c, d, e, f, g, h}')\n", |
334 | 264 | " return sum([a, b, c, d, e, f, g, h])\n", |
335 | | - " \n", |
| 265 | + "\n", |
336 | 266 | "f(1, 2, 3, 4, 5, 6, 7, 8)" |
337 | 267 | ] |
338 | 268 | }, |
|
382 | 312 | "metadata": {}, |
383 | 313 | "source": [ |
384 | 314 | "This of course pleads the case on a strictly formal level. No real complexities have been reduced during the making of this example.\\\n", |
385 | | - "Nevertheless there is the benefit of reduced test case requirements. And in real life real complexity _will_ be reduced." |
| 315 | + "Nevertheless there is the benefit of reduced test case requirements. And in real life, real complexity _will_ be reduced." |
386 | 316 | ] |
387 | 317 | } |
388 | 318 | ], |
|
404 | 334 | "name": "python", |
405 | 335 | "nbconvert_exporter": "python", |
406 | 336 | "pygments_lexer": "ipython3", |
407 | | - "version": "3.8.12" |
| 337 | + "version": "3.9.16" |
408 | 338 | }, |
409 | 339 | "latex_envs": { |
410 | 340 | "LaTeX_envs_menu_present": true, |
|
0 commit comments