Human Centered Data Science (Fall 2019)/Assignments

This page is a work in progress.

Assignments are comprised of weekly in-class activities, weekly reading reflections, written assignments, and programming/data analysis assignments. Weekly in-class reading groups will discuss the assigned readings from the course and students are expected to have read the material in advance. In class activities each week are posted to Canvas and may require time outside of class to complete.

Unless otherwise noted, all assignments are due before 5pm on the following week's class.

Unless otherwise noted, all assignments are individual assignments.

Assignment timeline

Assignments due every week

In-class activities - 2 points (weekly): In-class activity output posted to Canvas (group or individual) within 24 hours of class session.
Reading reflections - 2 points (weekly): Reading reflections posted to Canvas (individual) before following class session.

Scheduled assignments

A1 - 5 points (due 10/3): Data curation (programming/analysis)
A2 - 10 points (due 10/17): Bias in data (programming/analysis)
A3 - 10 points (due 10/31): Crowdwork Ethnography (written)
A4 - 5 points (due 11/7): Final project proposal (written)
A5 - 5 points (due 11/14): Final project plan (written)
A6 - 10 points (due 12/5): Final project presentation (oral, slides)
A7 - 15 points (due 12/10): Final project report (programming/analysis, written)

more information...

Weekly in-class activities

In each class session, one in-class activity will have a graded deliverable that is due the next day. The sum of these deliverables constitutes your participation grade for the course. The deliverable is intended to be something that you complete (and ideally, turn in, in class), but in rare cases may involve some work after class. It could be as simple as a picture of a design sketch you made, or notes from a group brainstorm. When you and/or your group complete the assigned activity, follow the instructions below to submit the activity and get full credit.

Love it or hate it, teamwork is an integral part of data science practice (and work in general). During some class sessions, you will be asked to participate in one or more group activities. These activities may involve reading discussions, group brainstorming activities, collaborative coding or data analysis, working together on designs, or offering peer support.

Instructions (individual activity)

Do the in-class activity
Submit the deliverable via Canvas, in the format specified by the instructor within 24 hours of class

Instructions (group activity)

Do the in-class activity
Before the end of class, choose one group member to submit the deliverable for the whole group
The designated group member will submit the deliverable via Canvas, in the format specified by the instructor within 24 hours of class

Note: Make sure to list the full names of all group members in the Canvas post!

Late deliverables will never be accepted, and in the case of group activities, everyone in the group will lose points. So make sure you choose someone reliable to turn the assignment in!

Weekly reading reflections

This course will introduce you to cutting edge research and opinion from major thinkers in the domain of human centered data science. By reading and writing about this material, you will have an opportunity to explore the complex intersections of technology, methodology, ethics, and social thought that characterize this budding field of research and practice.

As a participant in the course, you are responsible for intellectually engaging with all assigned readings and developing an understanding of the ideas discussed in them.

The weekly reading reflections assignment is designed to encourage you to reflect on these works and make connections during our class discussions. To this end, you will be responsible for posting reflections on the previous week's assigned reading before the next class session.

There will generally be multiple readings assigned each week. You are responsible for reading all of them. However, you only need to write a reflection on one reading per week. Unless your instructor specifies otherwise, you can choose which reading you would like to reflect on.

These reflections are meant to be succinct but meaningful. Follow the instructions below, demonstrate that you engaged with the material, and turn the reflection in on time, and you will receive full credit. Late reading reflections will never be accepted.

Instructions

Read all assigned readings.
Select a reading to reflect on.
In at least 2-3 full sentences, answer the question "How does this reading inform your understanding of human centered data science?"
Using full sentences, list at least 1 question that this reading raised in your mind, and say why the reading caused you to ask this question.
Post your reflection to Canvas before the next class session.

You are encouraged, but not required, to make connections between different readings (from the current week, from previous weeks, or other relevant material you've read/listened to/watched) in your reflections.

Scheduled assignments

This section provides basic descriptions of all scheduled course assignments (everything you are graded on except for weekly in-class activities and reading reflections). The instructor will make specific rubrics and requirements for each of these assignments available on Canvas the day the homework is assigned.

A1: Data curation

The goal of this assignment is to construct, analyze, and publish a dataset of monthly traffic on English Wikipedia from January 1 2008 through August 30 2019. All analysis should be performed in a single Jupyter notebook and all data, documentation, and code should be published in a single GitHub repository.

The purpose of the assignment is to demonstrate that you can follow best practices for open scientific research in designing and implementing your project, and make your project fully reproducible by others: from data collection to data analysis.

For this assignment, you combine data about Wikipedia page traffic from two different Wikimedia REST API endpoints into a single dataset, perform some simple data processing steps on the data, and then analyze that data.

Step 0: Read about reproducibility

Review Chapter 2 "Assessing Reproducibility" and Chapter 3 "The Basic Reproducible Workflow Template" from The Practice of Reproducible Research University of California Press, 2018.

Step 1: Data acquisition

In order to measure Wikipedia traffic from 2008-2019, you will need to collect data from two different API endpoints, the Legacy Pagecounts API and the Pageviews API.

The Legacy Pagecounts API (documentation, endpoint) provides access to desktop and mobile traffic data from December 2007 through July 2016.
The Pageviews API (documentation, endpoint) provides access to desktop, mobile web, and mobile app traffic data from July 2015 through last month.

For each API, you will need to collect data for all months where data is available and then save the raw results into 5 separate JSON source data files (one file per API query type) before continuing to step 2.

To get you started, you can refer to this example Notebook that contains sample code for API calls (view the notebook, download the notebook). This sample code is licensed CC0 so feel free to re-use any of the code in that notebook without attribution.

Your JSON-formatted source data file must contain the complete and un-edited output of your API queries. The naming convention for the source data files is:

apiname_accesstype_firstmonth-lastmonth.json

For example, your filename for monthly page views on desktop should be:

pagecounts_desktop-site_200712-201908.json

Important notes:

As much as possible, we're interested in organic (user) traffic, as opposed to traffic by web crawlers or spiders. The Pageview API (but not the Pagecount API) allows you to filter by agent=user. You should do that.
There was about 1 year of overlapping traffic data between the two APIs. You need to gather, and later graph, data from both APIs for this period of time.

Step 2: Data processing

You will need to perform a series of processing steps on these data files in order to prepare them for analysis. These steps must be followed exactly in order to prepare the data for analysis. At the end of this step, you will have a single CSV-formatted data file that can be used in your analysis (step 3) with no significant additional processing.

For data collected from the Pageviews API, combine the monthly values for mobile-app and mobile-web to create a total mobile traffic count for each month.
For all data, separate the value of timestamp into four-digit year (YYYY) and two-digit month (MM) and discard values for day and hour (DDHH).

Combine all data into a single CSV file with the following headers:

Column	Value
year	YYYY
month	MM
pagecount_all_views	num_views
pagecount_desktop_views	num_views
pagecount_mobile_views	num_views
pageview_all_views	num_views
pageview_desktop_views	num_views
pageview_mobile_views	num_views

For all months with 0 pageviews for a given access method (e.g. desktop-site, mobile-app), that value for that (column, month) should be listed as 0. So for example all values of pagecount_mobile_views for months before October 2014 should be 0, because mobile traffic data is not available before that month.

The final data file should be named:

en-wikipedia_traffic_200712-201809.csv

Step 3: Analysis

For this assignment, the "analysis" will be fairly straightforward: you will visualize the dataset you have created as a time series graph.

Your visualization will track three traffic metrics: mobile traffic, desktop traffic, and all traffic (mobile + desktop).

In order to complete the analysis correctly and receive full credit, your graph will need to be the right scale to view the data; all units, axes, and values should be clearly labeled; and the graph should possess a legend and a title. You must also generate a .png or .jpeg formatted image of your final graph.

If possible please graph the data in Python or R, in your notebook, rather than using an external application.

Step 4: Documentation

Follow best practices for documenting your project, as outlined in the lecture slides and in Chapter 2 "Assessing Reproducibility" and Chapter 3 "The Basic Reproducible Workflow Template" from The Practice of Reproducible Research.

Your documentation will be done in your Jupyter Notebook, a README file, and a LICENSE file.

At minimum, your Jupyter Notebook should:

Provide a short, clear description of every step in the acquisition, processing, and analysis of your data in full Markdown sentences (not just inline comments or docstrings)

At minimum, you README file should

Describe the goal of the project.
List the license of the source data and a link to the Wikimedia Foundation REST API terms of use: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions
Link to all relevant API documentation
Describe the values of all fields in your final data file.
List any known issues or special considerations with the data that would be useful for another researcher to know. For example, you should describe that data from the Pageview API excludes spiders/crawlers, while data from the Pagecounts API does not.

Submission instructions

Create the data-512-a1 repository on GitHub w/ your code and data.
Complete and add your README and LICENSE file.
Submit the link to your GitHub repo to: https://canvas.uw.edu/courses/1319253/assignments/4937082

Required deliverables

A directory in your GitHub repository called data-512-a1 that contains the following files:

5 source data files in JSON format that follow the specified naming convention.
1 final data file in CSV format that follows the specified naming convention.
1 Jupyter notebook named hcds-a1-data-curation that contains all code as well as information necessary to understand each programming step.
1 README file in .txt or .md format that contains information to reproduce the analysis, including data descriptions, attributions and provenance information, and descriptions of all relevant resources and documentation (inside and outside the repo) and hyperlinks to those resources.
1 LICENSE file that contains an MIT LICENSE for your code.
1 .png or .jpeg image of your visualization.

Helpful tips

Read all instructions carefully before you begin
Read all API documentation carefully before you begin
Experiment with queries in the sandbox of the technical documentation for each API to familiarize yourself with the schema and the data
Ask questions on Slack if you're unsure about anything
When documenting/describing your project, think: "If I found this GitHub repo, and wanted to fully reproduce the analysis, what information would I want? What information would I need?"

A2: Bias in data

The goal of this assignment is to explore the concept of bias through data on Wikipedia articles - specifically, articles on political figures from a variety of countries. For this assignment, you will combine a dataset of Wikipedia articles with a dataset of country populations, and use a machine learning service called ORES to estimate the quality of each article.

You are expected to perform an analysis of how the coverage of politicians on Wikipedia and the quality of articles about politicians varies between countries. Your analysis will consist of a series of tables that show:

the countries with the greatest and least coverage of politicians on Wikipedia compared to their population.
the countries with the highest and lowest proportion of high quality articles about politicians.

You are also expected to write a short reflection on the project, that describes how this assignment helps you understand the causes and consequences of bias on Wikipedia.

A repository with a README framework and examples of querying the ORES datastore in R and Python can be found here

Getting the article and population data

The first step is getting the data, which lives in several different places. The Wikipedia politicians by country dataset can be found on Figshare. Read through the documentation for this repository, then download and unzip it to extract the data file, which is called page_data.csv.

The population data is available in CSV format in the Files section of Canvas under "A2: bias in data". This dataset is drawn from the world population datasheet published by the Population Reference Bureau.

Cleaning the data

Both page_data.csv and WPDS_2018_data.csv contain some rows that you will need to filter out and/or ignore when you combine the datasets in the next step. In the case of page_data.csv, the dataset contains some page names that start with the string "Template:". These pages are not Wikipedia articles, and should not be included in your analysis.

Similarly, WPDS_2018_data contains some rows that provide cumulative regional population counts, rather than country-level counts. These rows are distinguished by having ALL CAPS values in the 'geography' field (e.g. AFRICA, OCEANIA). These rows won't match the country values in page_data, but you will want to retain them (either in the original file, or a separate file) so that you can report coverage and quality by region in the analysis section.

Getting article quality predictions

Now you need to get the predicted quality scores for each article in the Wikipedia dataset. For this step, we're using a Wikimedia API endpoint for a machine learning system called ORES ("Objective Revision Evaluation Service"). ORES estimates the quality of an article (at a particular point in time), and assigns a series of probabilities that the article is in one of 6 quality categories. The options are, from best to worst:

FA - Featured article
GA - Good article
B - B-class article
C - C-class article
Start - Start-class article
Stub - Stub-class article

For context, these quality classes are a sub-set of quality assessment categories developed by Wikipedia editors. If you're curious, you can read more about what these assessment classes mean on English Wikipedia. We will talk about what these categories mean, and how the ORES model predicts which category an article goes into, next week in class. For this assignment, you only need to know that these categories exist, and that ORES will assign one of these 6 categories to any rev_id you send it.

In order to get article predictions for each article in the Wikipedia dataset, you will first need to read page_data.csv into Python (or R), and then read through the dataset line by line, using the value of the rev_id column in the API query. If you're working in Python, the CSV module will help with this.

You have two options for getting data from the ORES:

Option 1: Install and run the ORES client (preferred, Python only)

You can pip install ores in your local notebook environment (https://github.com/wikimedia/ores installation instructions). This will allow you to get scores for list of multiple rev_id values in a single batch--you can even send all ~50k articles in the page_data.csv in a single batch! Here's some demo code:

from ores import api
#please provide this useragent string (second arg below) to help the ORES team track requests
ores_session = api.Session("https://ores.wikimedia.org", "Class project <jmorgan@wikimedia.org>")
#where 1234, 5678, 91011 below are rev_ids...
results = ores_session.score("enwiki", ["articlequality"], [1234, 5678, 91011])
for score in results:
    print(score)
#where the value for 'prediction' in each response below corresponds to the predicted article quality class
{'articlequality': {'score': {'prediction': 'B', 'probability': {'GA': 0.005565225912988614, 'Stub': 0.285072978841463, 'C': 0.1237249061020009, 'B': 0.2910788689339172, 'Start': 0.2859984921969326, 'FA': 0.008559528012697881}}}}
{'articlequality': {'score': {'prediction': 'Start', 'probability': {'GA': 0.005264197821210708, 'Stub': 0.40368617053424666, 'C': 0.021887833774629408, 'B': 0.029933164235917967, 'Start': 0.5352849001253548, 'FA': 0.0039437335086407645}}}}
{'articlequality': {'score': {'prediction': 'Stub', 'probability': {'GA': 0.0033975128938096197, 'Stub': 0.8980284163392759, 'C': 0.01216786960110309, 'B': 0.01579141569356552, 'Start': 0.06809640787450176, 'FA': 0.0025183775977442226}}}}

Option 2: Use the REST API endpoint (Python or R)

The ORES REST API is configured fairly similarly to the pageviews API we used for Assignment 1. Documentation can be found here. It expects a revision ID, which is the third column in the Wikipedia dataset, and a model, which is "wp10". The sample iPython notebooks for this assignment provide examples of a correctly-structured API query that you can use to understand how to gather your data, and also to examine the query output.

Whether you query the API or use the client, you will notice that ORES returns a prediction value that contains the name of one category, as well as probability values for each of the 6 quality categories. For this assignment, you only need to capture and use the value for prediction. We'll talk more about what the other values mean in upcoming weeks.

Combining the datasets

Some processing of the data will be necessary! In particular, you'll need to - after retrieving and including the ORES data for each article - merge the wikipedia data and population data together. Both have fields containing country names for just that purpose. After merging the data, you'll invariably run into entries which cannot be merged. Either the population dataset does not have an entry for the equivalent Wikipedia country, or vice versa.

Please remove any rows that do not have matching data, and output them to a CSV file called wp_wpds_countries-no_match.csv

Consolidate the remaining data into a single CSV file called wp_wpds_politicians_by_country.csv

The schema for that file should look something like this:

Column
country
article_name
revision_id
article_quality
population

Note: revision_id here is the same thing as rev_id, which you used to get scores from ORES.

Analysis

Your analysis will consist of calculating the proportion (as a percentage) of articles-per-population and high-quality articles for each country AND for each geographic region. By "high quality" articles, in this case we mean the number of articles about politicians in a given country that ORES predicted would be in either the "FA" (featured article) or "GA" (good article) classes.

Examples:

if a country has a population of 10,000 people, and you found 10 articles about politicians from that country, then the percentage of articles-per-population would be .1%.
if a country has 10 articles about politicians, and 2 of them are FA or GA class articles, then the percentage of high-quality articles would be 20%.

Tables

The tables should be pretty straightforward. Produce four tables that show:

10 highest-ranked countries in terms of number of politician articles as a proportion of country population
10 lowest-ranked countries in terms of number of politician articles as a proportion of country population
10 highest-ranked countries in terms of number of GA and FA-quality articles as a proportion of all articles about politicians from that country
10 lowest-ranked countries in terms of number of GA and FA-quality articles as a proportion of all articles about politicians from that country

Embed them in the Jupyter notebook.

Writeup

Write a few paragraphs, either in the README or at the end of the notebook, reflecting on what you have learned, what you found, what (if anything) surprised you about your findings, and/or what theories you have about why any biases might exist (if you find they exist). You can also include any questions this assignment raised for you about bias, Wikipedia, or machine learning. Particular questions you might want to answer:

What biases did you expect to find in the data, and why?
What are the results?
What theories do you have about why the results are what they are?
Can you think of a realistic data science research situation where using these data (to train a model, or perform a hypothesis-driven analysis) might create biased or misleading results, due to the inherent gaps and limitations of the data?

Submission instructions

Complete your Notebook and datasets in Jupyter Hub.
Create the data-512-a2 repository on GitHub w/ your code and data.
Complete and add your README and LICENSE file.
Submit the link to your GitHub repo to: FIXME

Required deliverables

A directory in your GitHub repository called data-512-a2 that contains the following files:

1 final data file in CSV format that follows the formatting conventions.
1 Jupyter notebook named hcds-a2-bias that contains all code as well as information necessary to understand each programming step, as well as your writeup (if you have not included it in the README) and the tables.
1 README file in .txt or .md format that contains information to reproduce the analysis, including data descriptions, attributions and provenance information, and descriptions of all relevant resources and documentation (inside and outside the repo) and hyperlinks to those resources, and your writeup (if you have not included it in the notebook). A prototype framework is included in the sample repository
1 LICENSE file that contains an MIT LICENSE for your code.

Helpful tips

Read all instructions carefully before you begin
Read all API documentation carefully before you begin
Experiment with queries in the sandbox of the technical documentation for the API to familiarize yourself with the schema and the data
Explore the data a bit before starting to be sure you understand how it is structured and what it contains
Ask questions on Slack if you're unsure about anything. If you need more help, come to office hours or schedule a time to meet with Yihan or Jonathan.
When documenting/describing your project, think: "If I found this GitHub repo, and wanted to fully reproduce the analysis, what information would I want? What information would I need?"

A3: Crowdwork ethnography

For this assignment, you will go undercover as a member of the Amazon Mechanical Turk community. You will preview or perform Mechanical Turk tasks (called "HITs"), lurk in Turk worker discussion forums, and write an ethnographic account of your experience as a crowdworker, and how this experience changes your understanding of the phenomenon of crowdwork.

The full assignment description is available as a Google doc and as a PDF.

A4: Final project proposal

to come

A5: Final project plan

to come

For this assignment, you will write up a study plan for your final class project. The plan will cover a variety of details about your final project, including what data you will use, what you will do with the data (e.g. statistical analysis, train a model), what results you expect or intend, and most importantly, why your project is interesting or important (and to whom, besides yourself).

A6: Final project presentation

For this assignment, you will give an in-class presentation of your final project. The goal of this assignment is to demonstrate that you are able to effectively communicate your research questions, methods, conclusions, and implications to your target audience.

A7: Final project report

For this assignment, you will publish the complete code, data, and analysis of your final research project. The goal is to demonstrate that you can incorporate all of the human-centered design considerations you learned in this course and create research artifacts that are understandable, impactful, and reproducible.