How to deal with reviews of Jupyter notebooks?

Question

There is currently a question in the python tag which asks as the main question for a review of an (externally linked) Jupyter notebook. In order to not be off-topic the OP also included the most relevant function in the question (not sure if this is enough, but let's leave that aside for now).

This leads me to ask if there is a way for us to meaningfully review Jupyter notebooks?

Some thoughts:

• Jupyter notebooks add additional code formatting concerns/opportunities (there are separate cells and you can embed code output, images and markdown). As such there are additional things to be careful of if you want to create a maintainable Jupyter notebook, although the normal Python best-practices are still valid.
• Being an external link there is the obvious problem of link rot. Could this be avoided by somehow including the whole notebook in the post? If yes, how would you best keep its structure intact?

I could see just saying the OP should convert the notebook into a Python file (such an export is possible in the interface) and post that, but then all the advice specific to Jupyter notebooks (like use headings, add markdown descriptions of what you are doing, etc) becomes obsolete.

What are your opinions?

Answer 1

I see 2 questions:

1. Is Jupyter reviewable?
2. Is linkrot a dealbreaker?

1) Yes. 2) Yes.

Jupyter is basically annotated Python. A global script cut in pieces.

The link can stay as additional context, but anything not embedded in the question itself is not reviewable. With a Jupyter notebook, this means essential parts of the code are missing in the question as it currently is.

How can we review Jupyter?

The following excerpt

could be included into the question as:

#Loading data

#The senators.pickle file is scraped using the script in the root of the repository.

with open('senators.pickle', 'rb') as f:
    senators_tx = pickle.load(f)


#Data cleaning
#Filling in missing tickers

#In this section, we fill in as many of the missing ticker symbols as we can.

def tokenize(asset_name):
    """ Convert an asset name into useful tokens. """
    token_string = asset_name\
        .replace('(', '')\
        .replace(')', '')\
        .replace('-', ' ')\
        .replace('.', '')
    return token_string.split(' ')

def token_is_ticker(token, token_blacklist):
    return len(token) <= 4 and token.upper() not in token_blacklist

# These generic words do not help us determine the ticker
blacklist = {

Or without comments. Or with multi-line comments. Or by pasting the entire thing in multiple code-blocks with the text formatted in some way between them, but I imagine that conversion would be time intensive and not worth the hassle.

Multi-line comments with neat blocks would be preferable, in my opinion. I imagine somebody could write a nice script (either in Python or as userscript) to take Jupyter notebooks and turn them into a formatted question, but it's perfectly doable by hand.

Naturally, as discussed in the FAQ, this should be done by the OP of the question.

Answer 2

Getting it reviewed

There are three ways an OP can get the code in the question. These are:

Manually copy the code

As shown in the linked question, manually copying some of the notebook over to a Code Review question is acceptable and can produce an ok question.

Save the history as a plain old Python file

A Jupyter notebook is just an IPython shell. The OP can extract the code as if it were a Python script with the %save command.

%save file_name ~0/

Whilst this is missing the pretty images, these can be generated in a properly configured environment. And so are not needed in the body of the question.
Since this is saving the history of the shell the Jupyter and REPL specific information is lost. This loss means comments like "you should make a main function that calls all of this" is valid but is ultimately useless to the OP.

Download the notebook to a Python file

Jupyter gives the option to File > Download as > Python (.py). This gives a vastly different output to the output that %save does. This is because it includes all the markdown or other cells as Python comments.

This has the benefit of saving it as a plain old Python file - so anyone with Python installed can run it. However it has additional context to it, solving the issues that %save has. Allowing for greater feedback on the Jupyter or IPython specific things.

Conclusion

The OP must include the code in the question as valid Python. This is not an unreasonable expectation of an OP. As there are three simple ways to extract the information from the notebook.

However for truly bizarre reasons* we don't review Markdown. So the OP may want to delete all Markdown cells before downloading.

_{*: We review LaTeX and Regex which both have many different standards.}