Package: nnanno
nnannoSample, annotate and apply computer vision models to the Newspaper Navigator datasettl;drnnannois a modest collection of tools to help work with the delightfulNewspaper Navigatordata.nnannoNewspaper Navigatoris a project which extracted visual content (pictures, maps etc.) from the Library of CongressChronicling Americadigitised newspaper collection.Newspaper Navigator has released data in a number of formats includingjsonfiles which contain a range of metadata about the newspaper from which the image was taken from.nnannowas thrown together to help work with this collection as part of the preparation of some example datasets used in a series of Programming Historian tutorials (currently under review). Since this code was developed using the wonderfulnbdevlibrary it is possible to install it for your own use.What nnanno tries to help withnnanno doesn't to provide an end-to-end to end software for using machine learning with the Newspaper Navigator data. Instead it is a minimal collection of code thatmayhelp you if you want to work with the Newspaper Navigator data.There are three particular areas where nnanno tries to help a little:sampling subsets from the full Newspaper Navigator dataannotating this sample with additional labels usinglabel studioinference (experimental 😬) running inference i.e making new predictions with a machine learning model on the newspaper navigator dataset using IIIF.DisclaimerThis code was written mainly to help develop some example datasets for a series of Programming Historian tutorials. It has some tests but there are likely bugs and issues with the code. The code in this repository was all written in notebooks, some people  hate notebooks. Those people will probably hate this too 🤷‍♂️If you want to work with the full Newspaper Navigator data you will likely be better of accessing it via the provided S3 bucket seenews-navigator.labs.loc.gov/for more information.nbdev notesThis code was written usingnbdev. This is a tool that helps use Jupyter notebooks for developing Python libraries. Inside the documentation you will see code cells followed by output. This is generated from a Jupyter notebook and shows the actual output of the code rather than something that has been copied and pasted for example:importdatetimeprint(datetime.date.today())2021-02-02Is evaluated as Python code. This also means all of the documentation and examples can be opened in notebooks and the code inspected, changed and run.InstallYou can installnnannoviaPyPI:pip install nnannoThis will install all of the code for sampling from Newspaper Navigator data.Optional extra packagesIf you want to use all of the parts ofnnannoyou'll need to install some extra packages.label studioIf you also want to uselabel-studiofor annotating you will need to install this too. There are various ways in which you may want to install label-studio. See the label studiodocumentationfor various options for setting this up.fastaiIf you want to use the experimental inference functionality you will need to install fastai. See thefastai docsfor options for doing this.DocumentationThedocumentationcan be viewed as rendered pages with the option of opening as notebooks in Google Colab.Illustrations in advertising: an 'end-to-end' example of using nnannoYou can find an 'end-to-end' example inexamples folder of the documentation.This example goes through the process of sampling, annotating, training a model and predicting this against the newspaper navigator data.FunctionalityThe three main areas ofnnannoare shown below. The examples in the documentation and in the "end-to-end" example shows this functionality in more detail.Creating samplesnnannocan be used to create samples from the Newspaper Navigator data:fromnnanno.sampleimport*sampler=nnSampler()df=sampler.create_sample(1,'photos',start_year=1850,end_year=1855,step=1)This returns a dataframe containing samples from the Newspaper Navigator data (loaded via JSON) into a Pandas DataFrame.df.columnsIndex(['filepath', 'pub_date', 'page_seq_num', 'edition_seq_num', 'batch',
       'lccn', 'box', 'score', 'ocr', 'place_of_publication',
       'geographic_coverage', 'name', 'publisher', 'url', 'page_url'],
      dtype='object')AnnotationThe annotation part of nnanno is mainly a little bit of documentation and a few functions to help setup annotation of a sample from Newspaper Navigator using IIIF urls and thelabel studioannotation tool. Since we can annotate via IIIF this offers a way of annotating without having to download large amounts of data locally.fromnnanno.annotateimportcreate_label_studio_jsonInferenceThe inference section of nnannoattemptsto show one possible way to use IIIF to run inference against samples of Newspaper Navigator using a trainedfastaimodel. This will allow you to make predictions against larger parts of the Newspaper Navigator data.fromnnanno.inferenceimport*fromfastai.vision.allimport*dls=ImageDataLoaders.from_csv('../ph/ads/','ads_upsampled.csv',folder='images',fn_col='file',label_col='label',item_tfms=Resize(64,ResizeMethod.Squish),num_workers=0)learn=cnn_learner(dls,resnet18,metrics=F1Score())learn.fit(1)epochtrain_lossvalid_lossf1_scoretime00.9247420.9638720.64557000:12With a trained fastai model we can predict on a sample from Newspaper Navigatorpredictor=nnPredict(learn,try_gpu=False)predictor.predict_sample('ads','testinference',0.01,end_year=1850)This returns ajsonfile for each year from the sample containing the original newspaper navigator data plus the predictions from your modeldf=pd.read_json('testinference/1850.json')We can access the 'decoded' predictionsdf['pred_decoded'].value_counts()text-only        50
illustrations    38
Name: pred_decoded, dtype: int64or work with the probabilities directlydf.iloc[:5,-2]0    0.152435
1    0.027183
2    0.096673
3    0.395800
4    0.957422
Name: illustrations_prob, dtype: float64AcknowledgmentThis work was support byLiving with Machines. This project, funded by the UK Research and Innovation (UKRI) Strategic Priority Fund, is a multidisciplinary collaboration delivered by the Arts and Humanities Research Council (AHRC), with The Alan Turing Institute, the British Library and the Universities of Cambridge, East Anglia, Exeter, and Queen Mary University of London.