# How to deal with reviews of Jupyter notebooks?

There is currently a question in the 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?

• "This leads me to ask if there is a way for us to meaningfully review Jupyter notebooks?" Can they be turned into text? If not, standard caveats for non-text code applies. – Mast May 8 '20 at 10:15
• @Mast: Mostly, yes. The only exception are images produced by the code when run or directly embedded. There is also the possibility of interactive graphics, but that is IMO opinion no different than normal code creating interactive graphics. – Graipher May 8 '20 at 10:16
• Are those images required to review the code? They could be uploaded as images for the context of the question, but technically they are more like the intermediate values of variables during execution, correct? – Mast May 8 '20 at 10:18
• @Mast: Yes, they are just the (intermediate) output of the code. The code itself would still make sense without generally. It is just normal Python (or R, or Julia, or ...) code. – Graipher May 8 '20 at 10:19
• We can fix this. I'll write an answer in an hour or so, when I got time, if nobody beats me to it :-) – Mast May 8 '20 at 10:21
• from what I recall of jupyter notebooks everything that is code is plain python. The only thing meaningfully different between them and normal python code is stuff that's not code and therefore "out of scope" for this site anyways? But I'm not sure that's accurate, so I hesitate to write an answer based on that – Vogel612 May 8 '20 at 10:31
• OP now included the whole notebook. – S.S. Anne May 9 '20 at 15:50

## 2 Answers

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.

• "Multi-line comments with neat blocks would be preferable, in my opinion." I would personally hate all the C&P I'd have to do. But if you download as a .md you can get that. You just have to upload the images yourself. – Peilonrayz May 8 '20 at 11:53
• Very helpful, thanks! – Neel May 9 '20 at 11:31

# 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.

• Interesting, a downvote even though Mast and myself agree. I guess someone doesn't like getting tools to format the code for you... – Peilonrayz May 8 '20 at 17:29
• Great! I'll try this. – Neel May 9 '20 at 11:31