The full text of newspaper articles in Trove is extracted from page images using Optical Character Recognition (OCR). The accuracy of the OCR process is influenced by a range of factors including the font and the quality of the images. Many errors slip through. Volunteers have done a remarkable job in correcting these errors, but it's a huge task. This notebook explores the scale of OCR correction in Trove.
There are two ways of getting data about OCR corrections using the Trove API. To get aggregate data you can include has:corrections in your query to limit the results to articles that have at least one OCR correction.
To get information about the number of corrections made to the articles in your results, you can add the reclevel=full parameter to include the number of corrections and details of the most recent correction to the article record. For example, note the correctionCount and lastCorrection values in the record below:
{
"article": {
"id": "41697877",
"url": "/newspaper/41697877",
"heading": "WRAGGE AND WEATHER CYCLES.",
"category": "Article",
"title": {
"id": "101",
"value": "Western Mail (Perth, WA : 1885 - 1954)"
},
"date": "1922-11-23",
"page": 4,
"pageSequence": 4,
"troveUrl": "https://trove.nla.gov.au/ndp/del/article/41697877",
"illustrated": "N",
"wordCount": 1054,
"correctionCount": 1,
"listCount": 0,
"tagCount": 0,
"commentCount": 0,
"lastCorrection": {
"by": "*anon*",
"lastupdated": "2016-09-12T07:08:57Z"
},
"identifier": "https://nla.gov.au/nla.news-article41697877",
"trovePageUrl": "https://trove.nla.gov.au/ndp/del/page/3522839",
"pdf": "https://trove.nla.gov.au/ndp/imageservice/nla.news-page3522839/print"
}
}
import requests
import os
import ipywidgets as widgets
from operator import itemgetter # used for sorting
import pandas as pd # makes manipulating the data easier
import altair as alt
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry
from tqdm.auto import tqdm
from IPython.display import display, HTML, FileLink, clear_output
import math
from collections import OrderedDict
import time
# Make sure data directory exists
os.makedirs('data', exist_ok=True)
# Create a session that will automatically retry on server errors
s = requests.Session()
retries = Retry(total=5, backoff_factor=1, status_forcelist=[ 502, 503, 504 ])
s.mount('http://', HTTPAdapter(max_retries=retries))
s.mount('https://', HTTPAdapter(max_retries=retries))
api_key = 'YOUR API KEY'
print('Your API key is: {}'.format(api_key))
# Basic parameters for Trove API
params = {
'facet': 'year', # Get the data aggregated by year.
'zone': 'newspaper',
'key': api_key,
'encoding': 'json',
'n': 0 # We don't need any records, just the facets!
}
def get_results(params):
'''
Get JSON response data from the Trove API.
Parameters:
params
Returns:
JSON formatted response data from Trove API
'''
response = s.get('https://api.trove.nla.gov.au/v2/result', params=params, timeout=30)
response.raise_for_status()
# print(response.url) # This shows us the url that's sent to the API
data = response.json()
return data
Let's find out what proportion of newspaper articles have at least one OCR correction.
First we'll get to the total number of newspaper articles in Trove.
# Set the q parameter to a single space to get everything
params['q'] = ' '
# Get the data from the API
data = get_results(params)
# Extract the total number of results
total = int(data['response']['zone'][0]['records']['total'])
print('{:,}'.format(total))
Now we'll set the q parameter to has:corrections to limit the results to newspaper articles that have at least one correction.
# Set the q parameter to 'has:corrections' to limit results to articles with corrections
params['q'] = 'has:corrections'
# Get the data from the API
data = get_results(params)
# Extract the total number of results
corrected = int(data['response']['zone'][0]['records']['total'])
print('{:,}'.format(corrected))
Calculate the proportion of articles with corrections.
print('{:.2%} of articles have at least one correction'.format(corrected/total))
You might be thinking that these figures don't seem to match the number of corrections by individuals displayed on the digitised newspapers home page. Remember that these figures show the number of articles that include corrections, while the individual scores show the number of lines corrected by each volunteer.
def get_facets(data):
'''
Loop through facets in Trove API response, saving terms and counts.
Parameters:
data - JSON formatted response data from Trove API
Returns:
A list of dictionaries containing: 'term', 'total_results'
'''
facets = []
try:
# The facets are buried a fair way down in the results
# Note that if you ask for more than one facet, you'll have use the facet['name'] param to find the one you want
# In this case there's only one facet, so we can just grab the list of terms (which are in fact the results by year)
for term in data['response']['zone'][0]['facets']['facet']['term']:
# Get the year and the number of results, and convert them to integers, before adding to our results
facets.append({'term': term['search'], 'total_results': int(term['count'])})
# Sort facets by year
facets.sort(key=itemgetter('term'))
except TypeError:
pass
return facets
def get_facet_data(params, start_decade=180, end_decade=201):
'''
Loop throught the decades from 'start_decade' to 'end_decade',
getting the number of search results for each year from the year facet.
Combine all the results into a single list.
Parameters:
params - parameters to send to the API
start_decade
end_decade
Returns:
A list of dictionaries containing 'year', 'total_results' for the complete
period between the start and end decades.
'''
# Create a list to hold the facets data
facet_data = []
# Loop through the decades
for decade in tqdm(range(start_decade, end_decade + 1)):
#print(params)
# Avoid confusion by copying the params before we change anything.
search_params = params.copy()
# Add decade value to params
search_params['l-decade'] = decade
# Get the data from the API
data = get_results(search_params)
# Get the facets from the data and add to facets_data
facet_data += get_facets(data)
# Reomve the progress bar (you can also set leave=False in tqdm, but that still leaves white space in Jupyter Lab)
clear_output()
return facet_data
facet_data = get_facet_data(params)
# Convert our data to a dataframe called df
df = pd.DataFrame(facet_data)
df.head()
So which year has the most corrections?
df.loc[df['total_results'].idxmax()]
The fact that there's more corrections in newspaper articles from 1915, might make you think that people have been more motivated to correct articles relating to WWI. But if you look at the total number of articles per year, you'll see that there's been more articles digitised from 1915! The raw number of corrections is probably not very useful, so let's look instead at the proportion of articles each year that have at least one correction.
To do that we'll re-harvest the facet data, but this time with a blank, or empty search, to get the total number of articles available from each year.
# Reset the 'q' parameter
# Use a an empty search (a single space) to get ALL THE ARTICLES
params['q'] = ' '
# Get facet data for all articles
all_facet_data = get_facet_data(params)
# Convert the results to a dataframe
df_total = pd.DataFrame(all_facet_data)
No we'll merge the number of articles by year with corrections with the total number of articles. Then we'll calculate the proportion with corrections.
def merge_df_with_total(df, df_total, how='left'):
'''
Merge dataframes containing search results with the total number of articles by year.
This is a left join on the year column. The total number of articles will be added as a column to
the existing results.
Once merged, do some reorganisation and calculate the proportion of search results.
Parameters:
df - the search results in a dataframe
df_total - total number of articles per year in a dataframe
Returns:
A dataframe with the following columns - 'year', 'total_results', 'total_articles', 'proportion'
(plus any other columns that are in the search results dataframe).
'''
# Merge the two dataframes on year
# Note that we're joining the two dataframes on the year column
df_merged = pd.merge(df, df_total, how=how, on='term')
# Rename the columns for convenience
df_merged.rename({'total_results_y': 'total_articles'}, inplace=True, axis='columns')
df_merged.rename({'total_results_x': 'total_results'}, inplace=True, axis='columns')
# Set blank values to zero to avoid problems
df_merged['total_results'] = df_merged['total_results'].fillna(0).astype(int)
# Calculate proportion by dividing the search results by the total articles
df_merged['proportion'] = df_merged['total_results'] / df_merged['total_articles']
return df_merged
# Merge the search results with the total articles
df_merged = merge_df_with_total(df, df_total)
df_merged.head()
Let's visualise the results, showing both the number of articles with corrections each year, and the proportion of articles each year with corrections.
# Number of articles with corrections
chart1 = alt.Chart(df_merged).mark_line(point=True).encode(
x=alt.X('term:Q', axis=alt.Axis(format='c', title='Year')),
y=alt.Y('total_results:Q', axis=alt.Axis(format=',d', title='Number of articles with corrections')),
tooltip=[alt.Tooltip('term:Q', title='Year'), alt.Tooltip('total_results:Q', title='Articles', format=',')]
).properties(width=700, height=250)
# Proportion of articles with corrections
chart2 = alt.Chart(df_merged).mark_line(point=True, color='red').encode(
x=alt.X('term:Q', axis=alt.Axis(format='c', title='Year')),
# This time we're showing the proportion (formatted as a percentage) on the Y axis
y=alt.Y('proportion:Q', axis=alt.Axis(format='%', title='Proportion of articles with corrections')),
tooltip=[alt.Tooltip('term:Q', title='Year'), alt.Tooltip('proportion:Q', title='Proportion', format='%')],
# Make the charts different colors
color=alt.value('orange')
).properties(width=700, height=250)
# This is a shorthand way of stacking the charts on top of each other
chart1 & chart2
This is really interesting – it seems there's been a deliberate effort to get the earliest newspapers corrected.
Let's see how the number of corrections varies across categories. This time we'll use the category facet instead of year.
params['q'] = 'has:corrections'
params['facet'] = 'category'
data = get_results(params)
facets = []
for term in data['response']['zone'][0]['facets']['facet']['term']:
# Get the state and the number of results, and convert it to integers, before adding to our results
facets.append({'term': term['search'], 'total_results': int(term['count'])})
df_categories = pd.DataFrame(facets)
df_categories.head()
Once again, the raw numbers are probably not all that useful, so let's get the total number of articles in each category and calculate the proportion that have at least one correction.
# Blank query
params['q'] = ' '
data = get_results(params)
facets = []
for term in data['response']['zone'][0]['facets']['facet']['term']:
# Get the state and the number of results, and convert it to integers, before adding to our results
facets.append({'term': term['search'], 'total_results': int(term['count'])})
df_total_categories = pd.DataFrame(facets)
We'll merge the two corrections by category data with the total articles per category and calculate the proportion.
df_categories_merged = merge_df_with_total(df_categories, df_total_categories)
df_categories_merged
A lot of the categories have been added recently and don't contain a lot of articles. Some of these have a very high proportion of articles with corrections – 'Obituaries' for example. This suggests users are systematically categorising and correcting certain types of article.
Let's focus on the main categories by filtering out those with less than 30,000 articles.
df_categories_filtered = df_categories_merged.loc[df_categories_merged['total_articles'] > 30000]
df_categories_filtered
And now we can visualise the results.
cat_chart1 = alt.Chart(df_categories_filtered).mark_bar().encode(
x=alt.X('term:N', title='Category'),
y=alt.Y('total_results:Q', title='Articles with corrections')
)
cat_chart2 = alt.Chart(df_categories_filtered).mark_bar().encode(
x=alt.X('term:N', title='Category'),
y=alt.Y('proportion:Q', axis=alt.Axis(format='%', title='Proportion of articles with corrections')),
color=alt.value('orange')
)
cat_chart1 | cat_chart2
As we can see, the rate of corrections is much higher in the 'Family Notices' category than any other. This probably reflects the work of family historians and others searching for, and correcting, articles containing particular names.
How do rates of correction vary across newspapers? We can use the title facet to find out.
params['q'] = 'has:corrections'
params['facet'] = 'title'
data = get_results(params)
facets = []
for term in data['response']['zone'][0]['facets']['facet']['term']:
# Get the state and the number of results, and convert it to integers, before adding to our results
facets.append({'term': term['search'], 'total_results': int(term['count'])})
df_newspapers = pd.DataFrame(facets)
df_newspapers.head()
Once again we'll calculate the proportion of articles corrected for each newspaper by getting the total number of articles for each newspaper on Trove.
params['q'] = ' '
data = get_results(params)
facets = []
for term in data['response']['zone'][0]['facets']['facet']['term']:
# Get the state and the number of results, and convert it to integers, before adding to our results
facets.append({'term': term['search'], 'total_results': int(term['count'])})
df_newspapers_total = pd.DataFrame(facets)
df_newspapers_merged = merge_df_with_total(df_newspapers, df_newspapers_total, how='right')
df_newspapers_merged.sort_values(by='proportion', ascending=False, inplace=True)
df_newspapers_merged.rename(columns={'term': 'id'}, inplace=True)
df_newspapers_merged.head()
The title facet only gives us the id number for each newspaper, not its title. Let's get all the titles and then merge them with the facet data.
# Get all the newspaper titles
title_params = {
'key': api_key,
'encoding': 'json',
}
title_data = s.get('https://api.trove.nla.gov.au/v2/newspaper/titles', params=params).json()
titles = []
for newspaper in title_data['response']['records']['newspaper']:
titles.append({'title': newspaper['title'], 'id': int(newspaper['id'])})
df_titles = pd.DataFrame(titles)
df_titles.head()
df_titles.shape
One problem with this list is that it also includes the titles of the Government Gazettes (this seems to be a bug in the API). Let's get the gazette titles and then subtract them from the complete list.
# Get gazette titles
gazette_data = s.get('https://api.trove.nla.gov.au/v2/gazette/titles', params=params).json()
gazettes = []
for gaz in gazette_data['response']['records']['newspaper']:
gazettes.append({'title': gaz['title'], 'id': int(gaz['id'])})
df_gazettes = pd.DataFrame(gazettes)
df_gazettes.shape
Subtract the gazettes from the list of titles.
df_titles_not_gazettes = df_titles[~df_titles['id'].isin(df_gazettes['id'])]
Now we can merge the newspaper titles with the facet data using the id to link the two datasets.
df_newspapers_with_titles = pd.merge(df_titles_not_gazettes, df_newspapers_merged, how='left', on='id').fillna(0).sort_values(by='proportion', ascending=False)
# Convert the totals back to integers
df_newspapers_with_titles[['total_results', 'total_articles']] = df_newspapers_with_titles[['total_results', 'total_articles']].astype(int)
Now we can display the newspapers with the highest rates of correction. Remember, that a proportion of 1.00 means that every available article has at least one correction.
df_newspapers_with_titles[:25]
At the other end, we can see the newspapers with the smallest rates of correction. Note that some newspapers have no corrections at all.
df_newspapers_with_titles.sort_values(by='proportion')[:25]
We'll save the full list of newspapers as a CSV file.
df_newspapers_with_titles_csv = df_newspapers_with_titles.copy()
df_newspapers_with_titles_csv.rename({'total_results': 'articles_with_corrections'}, axis=1, inplace=True)
df_newspapers_with_titles_csv['percentage_with_corrections'] = df_newspapers_with_titles_csv['proportion'] * 100
df_newspapers_with_titles_csv.sort_values(by=['percentage_with_corrections'], inplace=True)
df_newspapers_with_titles_csv[['id', 'title', 'articles_with_corrections', 'total_articles', 'percentage_with_corrections']].to_csv('titles_corrected.csv', index=False)
df_newspapers_with_titles_csv['title_url'] = df_newspapers_with_titles_csv['id'].apply(lambda x: f'http://nla.gov.au/nla.news-title{x}')
df_newspapers_with_titles_csv.to_csv('titles_corrected.csv', index=False)
display(FileLink('titles_corrected.csv'))
Let's see if we can combine some guesses about OCR error rates with the correction data to find the newspapers most in need of help.
To make a guesstimate of error rates, we'll use the occurance of 'tbe' – ie a common OCR error for 'the'. I don't know how valid this is, but it's a place to start!
# Search for 'tbe' to get an indication of errors by newspaper
params['q'] = 'text:"tbe"~0'
params['facet'] = 'title'
data = get_results(params)
facets = []
for term in data['response']['zone'][0]['facets']['facet']['term']:
# Get the state and the number of results, and convert it to integers, before adding to our results
facets.append({'term': term['search'], 'total_results': int(term['count'])})
df_errors = pd.DataFrame(facets)
Merge the error data with the total articles per newspaper to calculate the proportion.
df_errors_merged = merge_df_with_total(df_errors, df_newspapers_total, how='right')
df_errors_merged.sort_values(by='proportion', ascending=False, inplace=True)
df_errors_merged.rename(columns={'term': 'id'}, inplace=True)
df_errors_merged.head()
Add the title names.
df_errors_with_titles = pd.merge(df_titles_not_gazettes, df_errors_merged, how='left', on='id').fillna(0).sort_values(by='proportion', ascending=False)
So this is a list of the newspapers with the highest rate of OCR error (by our rather dodgy measure).
df_errors_with_titles[:25]
And those with the lowest rate of errors. Note the number of non-English newspapers in this list – of course our measure of accuracy fails completely in newspapers that don't use the word 'the'!
df_errors_with_titles[-25:]
Now let's merge the error data with the correction data.
corrections_errors_merged_df = pd.merge(df_newspapers_with_titles, df_errors_with_titles, how='left', on='id')
corrections_errors_merged_df.head()
corrections_errors_merged_df['proportion_uncorrected'] = corrections_errors_merged_df['proportion_x'].apply(lambda x: 1 - x)
corrections_errors_merged_df.rename(columns={'title_x': 'title', 'proportion_x': 'proportion_corrected', 'proportion_y': 'proportion_with_errors'}, inplace=True)
corrections_errors_merged_df.sort_values(by=['proportion_with_errors', 'proportion_uncorrected'], ascending=False, inplace=True)
So, for what it's worth, here's a list of the neediest newspapers – those with high error rates and low correction rates! As I've said, this is a pretty dodgy method, but interesting nonetheless.
corrections_errors_merged_df[['title', 'proportion_with_errors', 'proportion_uncorrected']][:25]
Created by Tim Sherratt for the GLAM Workbench.