JOSE Review: Notes on notebooks

[TomDonoghue]

This issue / suggestion is related to the JOSE review.

Here I'm collecting a few thoughts on the notebooks.

Notes on formatting:

• in this kind of resource, I think it's nice to demonstrate well formatted code, and there are a couple PEP8 violations that could be fixed up. What I noticed was mostly about spacing. I think a sweep for code formatting would help.
  • convention: indent lines should have a consistent spacing, and trailing lines should meet the opening element on the previous line
  • example, in code cell starting # Create a variable 'mobility_category' inpattern_discovery_unsupervised_learning`, the spacing is all inconsistent.
  • convention: no spaces around the = in assignment in function calls
  • a lot of the plot calls in pattern_discovery_unsupervised_learning don't follow this.
• limiting printing of long elements. For example, in pattern_discovery_unsupervised_learning, the notebook at times prints out the full arrays, which makes for long segments of scrolling through numbers. I think it would be preferable to print out an example row or so, rather than full arrays.
  • somewhat similarly, !pip freeze in open_reproducible_workflows and sns.catplot? in data_exploration_visualization have long print outs, where it's clear it's ideal to have the full output printed.

Notes on content:

• You sometimes use magics (% and %%), and also shell commands (ex !pip install X) in some notebooks. To the unfamiliar user, it might not be clear what these elements are, and that they are something different from Python commands. I didn't notice these things described anywhere (though I might have missed it). If it's not already somewhere, perhaps adding some quick notes somewhere (perhaps in python_data_science_cloud) would help clarify these things (that Jupyter notebooks aren't always directly running Python code, and that this special syntax exists for running other things).

[valdanchev]

Many thanks for the very helpful feedback @TomDonoghue. Will go through your comments and will write back when I manage to address them.

[valdanchev]

In relation to the notes on formatting, the code now conforms to PEP 8 by running automated code formatters Black and flake8 on Jupyter through nbQA.

• Added a section Readability of your Python code

The printing of long elements was reduced by:

• enabling scrolling for outputs such that outputs are not listed in long segments but are put into scrollable frames;
• printing the full output in a .txt file (e.g., requirements.txt).

To address the notes on content, added the following sections in the notebook 'Python for Data Analysis on the Cloud':

• Running Terminal commands in Jupyter/Colab notebook
• Installing packages with pip
• Jupyter magic commands The three sections describe and give examples of relevant command-line tools and syntax different from Python.

[TomDonoghue]

The updates all look good to me!