Skip to content

Commit 6dc12e3

Browse files
authored
Citation examples / docs (#105)
* update references and templates * add citation info to CONTRIBUTING.md * a bit more citation info for CONTRIBUTING.md * update computational_template.ipynb * update viz_template.ipynb
1 parent bc331e0 commit 6dc12e3

File tree

4 files changed

+120
-72
lines changed

4 files changed

+120
-72
lines changed

CONTRIBUTING.md

+16
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,22 @@ than waiting for a full **NCL Entry** to be completed.
190190

191191
[Example of a NCL Receipt](https://ncar.github.io/geocat-applications/ncl/receipts/days_in_month.html)
192192

193+
### Adding Citations
194+
To add citations to your page, first add your reference information to the
195+
`geocat-applications/references.bib` file. Many journals and databases
196+
allow you to export citation information in the required
197+
[BibTex](https://www.ctan.org/pkg/bibtex) format to save you a bit of
198+
work. You can copy and paste this text into the `references.bib` file.
199+
200+
From there you can add citations to your specific page using the
201+
directives shown in the [computational template](https://github.com/NCAR/geocat-applications/blob/main/templates/computational_template.ipynb).
202+
203+
For references to software documentation and other web content, we generally
204+
prefer links instead of or in addition to formal citations. If you're not
205+
sure which approach to take, consider where you would like to guide the reader
206+
and whether or not there is a scholarly object and/or DOI available for you
207+
to cite.
208+
193209
### Generate the Documentation Locally
194210
From the `geocat-applications/` directory, run:
195211
```

references.bib

+32-49
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,39 @@
1-
---
2-
---
3-
4-
@inproceedings{holdgraf_evidence_2014,
5-
address = {Brisbane, Australia, Australia},
6-
title = {Evidence for {Predictive} {Coding} in {Human} {Auditory} {Cortex}},
7-
booktitle = {International {Conference} on {Cognitive} {Neuroscience}},
8-
publisher = {Frontiers in Neuroscience},
9-
author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Knight, Robert T.},
10-
year = {2014}
11-
}
12-
13-
@article{holdgraf_rapid_2016,
14-
title = {Rapid tuning shifts in human auditory cortex enhance speech intelligibility},
15-
volume = {7},
16-
issn = {2041-1723},
17-
url = {http://www.nature.com/doifinder/10.1038/ncomms13654},
18-
doi = {10.1038/ncomms13654},
19-
number = {May},
20-
journal = {Nature Communications},
21-
author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Rieger, Jochem W. and Crone, Nathan and Lin, Jack J. and Knight, Robert T. and Theunissen, Frédéric E.},
22-
year = {2016},
23-
pages = {13654},
24-
file = {Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:C\:\\Users\\chold\\Zotero\\storage\\MDQP3JWE\\Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:application/pdf}
1+
@article{barba2019teaching,
2+
title={Teaching and learning with Jupyter},
3+
author={Barba, Lorena A and Barker, Lecia J and Blank, Douglas S and Brown, Jed and Downey, Allen B and George, Timothy and Heagy, Lindsey J and Mandli, Kyle T and Moore, Jason K and Lippert, David and others},
4+
journal={Recuperado: https://jupyter4edu. github. io/jupyter-edu-book},
5+
pages={1--77},
6+
year={2019}
257
}
268

27-
@inproceedings{holdgraf_portable_2017,
28-
title = {Portable learning environments for hands-on computational instruction using container-and cloud-based technology to teach data science},
29-
volume = {Part F1287},
30-
isbn = {978-1-4503-5272-7},
31-
doi = {10.1145/3093338.3093370},
32-
abstract = {© 2017 ACM. There is an increasing interest in learning outside of the traditional classroom setting. This is especially true for topics covering computational tools and data science, as both are challenging to incorporate in the standard curriculum. These atypical learning environments offer new opportunities for teaching, particularly when it comes to combining conceptual knowledge with hands-on experience/expertise with methods and skills. Advances in cloud computing and containerized environments provide an attractive opportunity to improve the efficiency and ease with which students can learn. This manuscript details recent advances towards using commonly-Available cloud computing services and advanced cyberinfrastructure support for improving the learning experience in bootcamp-style events. We cover the benets (and challenges) of using a server hosted remotely instead of relying on student laptops, discuss the technology that was used in order to make this possible, and give suggestions for how others could implement and improve upon this model for pedagogy and reproducibility.},
33-
booktitle = {{ACM} {International} {Conference} {Proceeding} {Series}},
34-
author = {Holdgraf, Christopher Ramsay and Culich, A. and Rokem, A. and Deniz, F. and Alegro, M. and Ushizima, D.},
35-
year = {2017},
36-
keywords = {Teaching, Bootcamps, Cloud computing, Data science, Docker, Pedagogy}
9+
@article{granger2021jupyter,
10+
title={Jupyter: Thinking and storytelling with code and data},
11+
author={Granger, Brian E and P{\'e}rez, Fernando},
12+
journal={Computing in Science \& Engineering},
13+
volume={23},
14+
number={2},
15+
pages={7--14},
16+
year={2021},
17+
publisher={IEEE}
3718
}
3819

39-
@article{holdgraf_encoding_2017,
40-
title = {Encoding and decoding models in cognitive electrophysiology},
41-
volume = {11},
42-
issn = {16625137},
43-
doi = {10.3389/fnsys.2017.00061},
44-
abstract = {© 2017 Holdgraf, Rieger, Micheli, Martin, Knight and Theunissen. Cognitive neuroscience has seen rapid growth in the size and complexity of data recorded from the human brain as well as in the computational tools available to analyze this data. This data explosion has resulted in an increased use of multivariate, model-based methods for asking neuroscience questions, allowing scientists to investigate multiple hypotheses with a single dataset, to use complex, time-varying stimuli, and to study the human brain under more naturalistic conditions. These tools come in the form of “Encoding” models, in which stimulus features are used to model brain activity, and “Decoding” models, in which neural features are used to generated a stimulus output. Here we review the current state of encoding and decoding models in cognitive electrophysiology and provide a practical guide toward conducting experiments and analyses in this emerging field. Our examples focus on using linear models in the study of human language and audition. We show how to calculate auditory receptive fields from natural sounds as well as how to decode neural recordings to predict speech. The paper aims to be a useful tutorial to these approaches, and a practical introduction to using machine learning and applied statistics to build models of neural activity. The data analytic approaches we discuss may also be applied to other sensory modalities, motor systems, and cognitive systems, and we cover some examples in these areas. In addition, a collection of Jupyter notebooks is publicly available as a complement to the material covered in this paper, providing code examples and tutorials for predictive modeling in python. The aimis to provide a practical understanding of predictivemodeling of human brain data and to propose best-practices in conducting these analyses.},
45-
journal = {Frontiers in Systems Neuroscience},
46-
author = {Holdgraf, Christopher Ramsay and Rieger, J.W. and Micheli, C. and Martin, S. and Knight, R.T. and Theunissen, F.E.},
47-
year = {2017},
48-
keywords = {Decoding models, Encoding models, Electrocorticography (ECoG), Electrophysiology/evoked potentials, Machine learning applied to neuroscience, Natural stimuli, Predictive modeling, Tutorials}
20+
@article{perez2011python
21+
title={Python: an ecosystem for scientific computing},
22+
author={Perez, Fernando and Granger, Brian E and Hunter, John D},
23+
journal={Computing in Science \\& Engineering},
24+
volume={13},
25+
number={2},
26+
pages={13--21},
27+
year={2011},
28+
publisher={AIP Publishing},
4929
}
5030

51-
@book{ruby,
52-
title = {The Ruby Programming Language},
53-
author = {Flanagan, David and Matsumoto, Yukihiro},
54-
year = {2008},
55-
publisher = {O'Reilly Media}
31+
@Inproceedings{ project_jupyter-proc-scipy-2018,
32+
author = { {P}roject {J}upyter and {M}atthias {B}ussonnier and {J}essica {F}orde and {J}eremy {F}reeman and {B}rian {G}ranger and {T}im {H}ead and {C}hris {H}oldgraf and {K}yle {K}elley and {G}ladys {N}alvarte and {A}ndrew {O}sheroff and {M} {P}acer and {Y}uvi {P}anda and {F}ernando {P}erez and {B}enjamin {R}agan-{K}elley and {C}arol {W}illing },
33+
title = { {B}inder 2.0 - {R}eproducible, interactive, sharable environments for science at scale },
34+
booktitle = { {P}roceedings of the 17th {P}ython in {S}cience {C}onference },
35+
pages = { 113 - 120 },
36+
year = { 2018 },
37+
editor = { {F}atih {A}kici and {D}avid {L}ippa and {D}illon {N}iederhut and {M} {P}acer },
38+
doi = { 10.25080/Majora-4af1f417-011 }
5639
}

templates/computational_template.ipynb

+47-5
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@
1919
]
2020
},
2121
{
22-
"metadata": {},
2322
"cell_type": "markdown",
23+
"metadata": {},
2424
"source": [
2525
"## Grab and Go\n",
2626
"\n",
@@ -32,9 +32,11 @@
3232
]
3333
},
3434
{
35-
"metadata": {},
3635
"cell_type": "markdown",
37-
"source": "---"
36+
"metadata": {},
37+
"source": [
38+
"---"
39+
]
3840
},
3941
{
4042
"cell_type": "markdown",
@@ -46,15 +48,55 @@
4648
"- explaining the concepts behind the functionality\n",
4749
"- introducing other examples in the python ecosystem that cover similar topics\n",
4850
"\n",
51+
"Here's an example citation {footcite}`project_jupyter-proc-scipy-2018`.\n",
52+
"\n",
53+
"And another one with a textual citation, {footcite:t}`project_jupyter-proc-scipy-2018`.\n",
54+
"\n",
55+
"And a few more for good measure {footcite}`perez2011python,barba2019teaching,granger2021jupyter`.\n",
56+
"\n",
4957
"*Note that these examples can be their own ##-level headers and that your final notebook is not expected to have a section with the ## Content Sections present in this cell*"
5058
]
59+
},
60+
{
61+
"cell_type": "markdown",
62+
"metadata": {},
63+
"source": [
64+
"## Additional Resources\n",
65+
"To learn more about this topic in Python, we suggest:\n",
66+
"* Resource 1\n",
67+
"* Resource 2\n",
68+
"* Resource 3 "
69+
]
70+
},
71+
{
72+
"cell_type": "markdown",
73+
"metadata": {},
74+
"source": [
75+
"## References\n",
76+
"```{footbibliography}\n",
77+
"```"
78+
]
5179
}
5280
],
5381
"metadata": {
82+
"kernelspec": {
83+
"display_name": "Python 3 (ipykernel)",
84+
"language": "python",
85+
"name": "python3"
86+
},
5487
"language_info": {
55-
"name": "python"
88+
"codemirror_mode": {
89+
"name": "ipython",
90+
"version": 3
91+
},
92+
"file_extension": ".py",
93+
"mimetype": "text/x-python",
94+
"name": "python",
95+
"nbconvert_exporter": "python",
96+
"pygments_lexer": "ipython3",
97+
"version": "3.12.3"
5698
}
5799
},
58100
"nbformat": 4,
59-
"nbformat_minor": 2
101+
"nbformat_minor": 4
60102
}

templates/viz_template.ipynb

+25-18
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,15 @@
1515
"cell_type": "code",
1616
"execution_count": null,
1717
"metadata": {},
18+
"outputs": [],
1819
"source": [
1920
"import xarray as xr\n",
2021
"import cartopy.crs as ccrs\n",
2122
"import cartopy.feature as cfeature\n",
2223
"import matplotlib.pyplot as plt\n",
2324
"\n",
2425
"import geocat.datafiles as gdf"
25-
],
26-
"outputs": []
26+
]
2727
},
2828
{
2929
"cell_type": "markdown",
@@ -36,11 +36,11 @@
3636
"cell_type": "code",
3737
"execution_count": null,
3838
"metadata": {},
39+
"outputs": [],
3940
"source": [
4041
"# Use Xarray and GeoCAT datafiles to pull up a sample relevant dataset\n",
4142
"ds = xr.open_dataset(gdf.get(\"\"), decode_times=False)"
42-
],
43-
"outputs": []
43+
]
4444
},
4545
{
4646
"cell_type": "markdown",
@@ -62,13 +62,13 @@
6262
"cell_type": "code",
6363
"execution_count": null,
6464
"metadata": {},
65+
"outputs": [],
6566
"source": [
6667
"# Generate figure (set its size (width, height) in inches)\n",
6768
"fig, ax = plt.subplots(figsize=(8, 6))\n",
6869
"\n",
6970
"# Plot the data in one line if possible."
70-
],
71-
"outputs": []
71+
]
7272
},
7373
{
7474
"cell_type": "markdown",
@@ -86,13 +86,13 @@
8686
"cell_type": "code",
8787
"execution_count": null,
8888
"metadata": {},
89+
"outputs": [],
8990
"source": [
9091
"# Generate figure (set its size (width, height) in inches)\n",
9192
"fig, ax = plt.subplots(figsize=(8, 6))\n",
9293
"\n",
9394
"# Plot the data with relevant kwargs specified."
94-
],
95-
"outputs": []
95+
]
9696
},
9797
{
9898
"cell_type": "markdown",
@@ -111,6 +111,7 @@
111111
"cell_type": "code",
112112
"execution_count": null,
113113
"metadata": {},
114+
"outputs": [],
114115
"source": [
115116
"# Generate figure (set its size (width, height) in inches) and axes using Cartopy projection\n",
116117
"fig = plt.figure(figsize=(8, 6))\n",
@@ -124,8 +125,7 @@
124125
"# Plot the data on the map\n",
125126
"\n",
126127
"plt.title(\"\");"
127-
],
128-
"outputs": []
128+
]
129129
},
130130
{
131131
"cell_type": "markdown",
@@ -140,6 +140,7 @@
140140
"cell_type": "code",
141141
"execution_count": null,
142142
"metadata": {},
143+
"outputs": [],
143144
"source": [
144145
"# Generate figure (set its size (width, height) in inches) and axes using Cartopy projection\n",
145146
"fig = plt.figure(figsize=(8, 6))\n",
@@ -153,8 +154,7 @@
153154
"# Plot the data on the map\n",
154155
"\n",
155156
"plt.title(\"\");"
156-
],
157-
"outputs": []
157+
]
158158
},
159159
{
160160
"cell_type": "markdown",
@@ -185,8 +185,8 @@
185185
"cell_type": "code",
186186
"execution_count": null,
187187
"metadata": {},
188-
"source": [],
189-
"outputs": []
188+
"outputs": [],
189+
"source": []
190190
},
191191
{
192192
"cell_type": "markdown",
@@ -201,20 +201,27 @@
201201
"cell_type": "code",
202202
"execution_count": null,
203203
"metadata": {},
204-
"source": [],
205-
"outputs": []
204+
"outputs": [],
205+
"source": []
206206
},
207207
{
208208
"cell_type": "markdown",
209209
"metadata": {},
210210
"source": [
211-
"## References\n",
211+
"## Additional Resources\n",
212212
"\n",
213213
"Want to go deeper in your understanding of the topic or the available keyword arguments, check out these resources:\n",
214214
"\n",
215215
" - [Link to Documentation]()\n",
216216
" - [Another link]()"
217217
]
218+
},
219+
{
220+
"cell_type": "code",
221+
"execution_count": null,
222+
"metadata": {},
223+
"outputs": [],
224+
"source": []
218225
}
219226
],
220227
"metadata": {
@@ -233,7 +240,7 @@
233240
"name": "python",
234241
"nbconvert_exporter": "python",
235242
"pygments_lexer": "ipython3",
236-
"version": "3.11.8"
243+
"version": "3.12.3"
237244
}
238245
},
239246
"nbformat": 4,

0 commit comments

Comments
 (0)