Intermediate Data Science

Writing in Data Science

Author

Joanna Bieri
DATA201

Intermediate Data Science

Important Information

Today’s Reading

No new chapter from the book today! Instead, please read these two short articles before class:

Career Discussion (in class Thursday 9/24)

Build a Career in Data Science, 1.3 Choosing your Path. We will start class talking about it, so bring your notes.

No New Homework

There is no new homework for Day 7. Use the extra time to catch up, and to make your HW 6 write-up really good. Everything in these notes should go straight into that write-up.

Why Writing Matters

Today we take a break from new pandas commands and talk about writing.

This might feel like a strange topic for a data science class, but I think it is one of the most important things you will learn this semester. AI tools can already write a lot of code. They can load a data set, make a plot, and fit a model in seconds. What they cannot do is stand in front of your boss and explain what you did and why you should trust it.

Every time you hand in a data analysis, someone should be able to read it and answer three questions:

  1. What did you do? What data, what method, what model?
  2. How did you do it? What steps, in what order?
  3. Why did you make those choices? Why this plot, why drop those rows, why this model?

If you can clearly explain the what, how, and why, you are the person an employer wants to hire. Your code finds the answer, and your writing is how everyone else learns what the answer is and whether to trust it.

Today we will look at five things that make data science writing good:

  1. Explaining your choices
  2. Describing your data (and the ethics around it)
  3. Reproducibility
  4. Citing your sources
  5. Using your own voice

Explain Your Choices

Every analysis is full of small decisions. You decide which rows to drop, how to fill missing values, which columns to keep, what kind of plot to make, where to put a cutoff. Each of these changes your results, so each one needs a sentence that says what you did and why.

Here is a made-up example. Which one is better?

Version A: I dropped the NaNs and then made a plot of charges by age.

Version B: 12 rows had no value for charges. That is less than 1% of the data, so I dropped them, and it should not change the averages much. I plotted charges against age because I wanted to see if older people are charged more.

Version B tells the reader how many rows, why it was okay to drop them, and why this plot. Version A makes the reader guess, and a reader who has to guess starts to wonder what else you did not tell them.

Choices you should always explain:

  • Dropping rows or columns
  • Filling in missing values (and what you filled them with)
  • Changing data types or recoding categories
  • Cutoffs and bins (eg. who counts as a “young adult”?)
  • Which plot you chose and what you want the reader to see in it
  • Which model or method you used, and why that one

NOTE - You do not need to write an essay for every line of code. One or two plain sentences is usually enough. The goal is that nobody has to guess.

Describe Your Data

Before anyone can trust your results, they need to know where your data came from. A good description answers these questions:

  1. Where did it come from? Give the source and a link.
  2. Who collected it, when, and why? Data collected for one purpose can be a bad fit for another.
  3. What is one row? One person? One day? One transaction?
  4. What is missing? Missing values, but also: who or what is NOT in this data at all?
  5. Are you allowed to use it? Check the license or terms, and think about privacy if the data is about people.

These questions come from a longer list in a paper called Datasheets for Datasets (Gebru et al.), which argues that every data set should come with this kind of description. It is worth a look if you want the full list.

Here is a made-up example:

Version A: I used a data set about insurance.

Version B: This data comes from Kaggle ([link]). Each row is one person with a health insurance plan in the US, with their age, sex, BMI, number of children, smoking status, region, and yearly medical charges. There are 1338 rows and no missing values. This is a sample of 1338 people, so I am careful not to say my results apply to everyone in the US.

Notice that Version B is honest about what it does not know. That is a good thing!

A real example - where did the data come from?

In 2020, in the middle of the COVID pandemic, the medical journal The Lancet published a big study that said a drug called hydroxychloroquine was linked to a higher risk of death. The data came from a private company called Surgisphere. Other scientists quickly noticed that the numbers looked strange. When independent reviewers asked to see the full data set, the company would not give it to them, and three of the four authors said they could no longer vouch for the data. The paper was retracted about two weeks after it came out. (Retraction Watch, The Lancet retraction notice)

If you cannot say where your data came from, nobody can check your work.

Ethics - who is in your data?

In 2018 Reuters reported that Amazon had stopped using a model it built to rank job applicants. The model was trained on ten years of résumés that had been sent to the company, and most of those résumés came from men. The model learned that pattern. It gave lower scores to résumés that included the word “women’s,” as in “women’s chess club captain.” Amazon tried to fix it, but could not be sure the model was fair, so they dropped it. (MIT Technology Review)

Nobody at Amazon wrote code that said “prefer men.” The bias was in the data. This is why question 4 above matters so much: always ask who is missing from your data and what that might do to your results.

Reproducibility

Your analysis is reproducible if someone else can take your notebook and your data, run it, and get the same results. In this class that someone is usually your teammate, who pulls your notebook from the team repo and runs it on their own computer.

A real example - five countries left out

In 2010 two well known Harvard economists, Carmen Reinhart and Kenneth Rogoff, published a paper saying that when a country’s debt goes above 90% of its GDP, its economy tends to shrink. Politicians around the world quoted it in arguments about cutting government spending.

In 2013 a graduate student at UMass Amherst, Thomas Herndon, tried to reproduce the result for a class assignment and could not do it. He asked the authors for their spreadsheet. It turned out an Excel formula that averaged the growth numbers stopped at row 44 instead of row 49, so five countries were left out. After fixing that and a few other problems, the average growth for high debt countries was about +2.2% instead of -0.1%. (The Conversation)

A student doing homework caught a mistake in a paper that politicians were quoting, and he only caught it because he tried to run the analysis again!

Another one - Excel changes your data

If you type the gene name SEPT2 into Excel, it turns it into the date September 2. In 2016 a group of researchers scanned published genetics papers and found that about one in five papers that included Excel gene lists had gene names that Excel had turned into dates or numbers. (Ziemann et al., Genome Biology)

We just saw how hard pandas works to turn strings into dates when we ask it to. Excel does it without asking. When your work is in code, every change to the data is written down where someone can see it.

Your reproducibility checklist

  • Restart the kernel and run all. If it does not run from top to bottom without errors, it is not done.
  • Use relative paths. pd.read_csv('data/tips.csv') works on your teammate’s computer. pd.read_csv('/Users/yourname/Desktop/tips.csv') does not.
  • Make sure the data is available. Either the data file is in the repo, or your code downloads it (like we do with kagglehub).
  • Remove junk code. Old experiments and broken cells confuse the reader.
  • Let your code write the numbers. If you type a number into your text by hand, it will be wrong the next time the data changes. See the example below.

This should look familiar, it is the same list as the checklist at the bottom of every homework!

Let your code write your numbers

Here is a small trick that makes your writing more reproducible. Instead of typing numbers into your markdown by hand, you can have Python print a sentence with the numbers filled in.

import pandas as pd

df = pd.read_csv('data/tips.csv')
df.head()
total_bill tip smoker day time size
0 16.99 1.01 No Sun Dinner 2
1 10.34 1.66 No Sun Dinner 3
2 21.01 3.50 No Sun Dinner 3
3 23.68 3.31 No Sun Dinner 2
4 24.59 3.61 No Sun Dinner 4

Say I want to tell the reader how big this data set is and how much is missing. I could look at the output and type it in by hand, or I could use an f-string (a string with an f in front) to put the values right into a sentence:

n_rows, n_cols = df.shape
n_missing = df.isna().sum().sum()

print(f'The data has {n_rows} rows and {n_cols} columns.')
print(f'There are {n_missing} missing values.')
The data has 244 rows and 6 columns.
There are 0 missing values.
# You can also round numbers inside the f-string with :.2f (two decimal places)
ave_tip = df['tip'].mean()
ave_pct = (df['tip'] / df['total_bill']).mean() * 100

print(f'The average tip is ${ave_tip:.2f}, which is about {ave_pct:.1f}% of the bill.')
The average tip is $3.00, which is about 16.1% of the bill.

If the data changes, the sentence changes with it. You still need to write the markdown around it that says what these numbers mean!

Cite Your Sources

If an idea, a piece of code, or a data set came from somewhere else, say where. Citing lets your reader go check your sources, and it gives credit to the people who did the work.

What to cite:

  • Data - the source and a link (see Describe Your Data above).

  • Books and articles - if you used an idea or method from our textbook or an article, name it.

  • Code you found online - put the link in a comment right above the code, eg.

      # Code for the rolling average adapted from:
  # https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.rolling.html

  • AI - here is what our syllabus says:

“A quick debugging question or syntax lookup needs no citation. If you copy and paste code an AI wrote for you, say so: name the tool and what it helped with in a short note on the assignment. If AI helps you understand a concept, rewrite the explanation in your own words rather than pasting it in. If you draw on a large chunk of AI-generated material, disclose that too.”

Here is a made-up example of a short AI note at the bottom of a homework:

AI use: I used ChatGPT to help me write the code for the grouped bar chart in Part 3, and to fix an error with pd.cut. The explanations and interpretation are my own.

One or two honest sentences is enough.

Use Your Own Voice

Our syllabus says: “The written discussion, interpretation, and reflection you submit must always be your own thinking, in your own words, on every assignment.”

When you explain a plot in your own words you find out whether you actually understand it. If you cannot explain it, that is a sign to go back and look again. And your reader can tell the difference between someone who looked at the data and someone who pasted in a paragraph.

Here is a made-up example about a plot of charges by age:

Version A: The visualization reveals a robust positive correlation between age and medical charges, highlighting the critical importance of age as a key driver of healthcare costs.

Version B: Charges go up with age, but the points split into three separate bands. I think the top band might be smokers, so I am going to color the points by smoker next to check.

Version A sounds polished but it does not say anything you could not guess before looking at the plot. Version B says what the writer actually saw, including something surprising, and what they are going to do about it.

Some tips:

  • Say what you see. Describe the actual plot: where the points are, what goes up or down, what is weird.
  • It is okay to be unsure. “I am not sure why there is a dip in 2015” is a great sentence. It is honest, and it is a question someone can follow up on.
  • Use plain words. You do not need to sound like a research paper. Write like you are explaining it to a friend in another major.
  • Paraphrase. If you learned something from the book, an article, or an AI, close the tab and write it the way you would say it.

Putting It Together - the Shape of a Write-Up

Your homework write-up notebooks do not need to be long, but they should have a clear shape. Here is one that works:

  1. Question - What are you trying to find out?
  2. Data - Where did it come from, what is one row, what is missing? (Describe Your Data)
  3. Methods - What did you do to the data and why? (Explain Your Choices)
  4. Results - Your plots and numbers, each with a few sentences about what you see. (Your Own Voice)
  5. Conclusion - What did you learn? What would you look at next? What are you still unsure about?
  6. Sources - Data, articles, code, and any AI use. (Cite Your Sources)

Use markdown headings for each part so a reader can jump around. And before you open your Pull Request: restart the kernel and run all! (Reproducibility)

You Try

Open the write-up notebook you are working on for HW 6.

  1. Pick one section that you already wrote, or one plot that you have not written about yet.
  2. Rewrite it using today’s ideas. Ask yourself: did I explain my choices? Would someone who has never seen this data understand it? Is this in my own words?
  3. Trade with a teammate. Read their paragraph and tell them one thing that is clear and one place where you had to guess.
  4. Add a Data section and a Sources section to your write-up if you do not have them yet.

When you are happy with it, commit it to your branch like normal. This is part of your HW 6, so there is nothing extra to turn in!

Sources

AI use: I used Claude (Anthropic) to help draft these notes and slides, find the real-world examples, and write the made-up example paragraphs. I chose the topics, and I reviewed and edited everything.