Minor consistency improvements

docs/thesis/chapters/1_introduction.tex

@@ -10,9 +10,9 @@ This thesis sets out to investigate the reasons behind the apparent asymmetry be
 
 Therefore, we design a software framework called \href{https://github.com/schmelczer/great-ai}{\textit{GreatAI}} and present it in this thesis. The principal motivation behind the construction of \textit{GreatAI} is to facilitate the responsible and robust deployment of algorithms and models by designing a more accessible API in an attempt to overcome the practical drawbacks of other similar frameworks. Its name stands for its main aim: to assist easily creating \underline{G}eneral \underline{R}obust \underline{E}nd-to-end \underline{A}utomated, and \underline{T}rustworthy AI deployments.
 
-The utility of \textit{GreatAI} is examined and refined using the principles of design science methodology \cite{wieringa2014design} through iteratively designing its API and implementation in two case studies concerning the natural language processing (NLP) pipeline of a commercial product in collaboration with \href{https://scoutinscience.com/}{ScoutinScience B.V.} The goal of the aforementioned software suite is to evaluate technology transfer opportunities in scientific publications. Subsequently, interviews are conducted with practitioners to validate the broader applicability and generalisability of the design.
+The utility of \textit{GreatAI} is examined and refined using the principles of design science methodology \cite{wieringa2014design} through iteratively designing its API and implementation in two case studies concerning the natural language processing (NLP) pipeline of a commercial product in collaboration with \href{https://scoutinscience.com/}{ScoutinScience B.V.} The goal of the aforementioned software suite is to evaluate technology-transfer opportunities in scientific publications. Subsequently, interviews are conducted with practitioners to validate the broader applicability and generalisability of the design.
 
-The choice of case study subject is no coincidence; while working on the ScoutinScience platform for the last two years, my colleagues and I have increasingly noticed the same recurring challenges in deploying and operating AI/ML pipelines. This has motivated me to pursue a general solution. Considering that the company's predominant field is NLP, the case studies, and hence, the prototype of \textit{GreatAI} will also focus primarily on deploying NLP models. Nonetheless, the motivation for creating a general solution for all AI/ML contexts remains and will be taken into account every step of the way.
+The choice of case study subject is no coincidence; while working on the ScoutinScience Platform for the last two years, my colleagues and I have increasingly noticed the same recurring challenges in deploying and operating AI/ML pipelines. This has motivated me to pursue a general solution. Considering that the company's predominant field is NLP, the case studies, and hence, the prototype of \textit{GreatAI} will also focus primarily on deploying NLP models. Nonetheless, the motivation for creating a general solution for all AI/ML contexts remains and will be taken into account every step of the way.
 
 \section{Research questions}
 

docs/thesis/chapters/2_background.tex

@@ -65,7 +65,7 @@ No DevOps dependencies\textsuperscript{4}&            &            &
 
 Luckily, the open-source scene of AI/ML/DS tools, libraries, frameworks, and platforms is thriving. Additionally, there is a considerable number of closed-source --- usually platforms-as-a-service (PaaS) --- solutions next to them. Let us look at some prominent examples. Table \ref{table:platform-comparison} shows a high-level comparison of frameworks along the dimensions in which practitioners reportedly face difficulties in the \textit{Deployment} stage of the CRISP-DM model \cite{wirth2000crisp}.
 
-IBM's AutoAI \cite{wang2020autoai} promises to provide automation for the entire machine learning lifecycle, including deployment. It is a closed-sourced, paid service which --- from their documentation --- seems to focus primarily on non-technical users by providing them with a UI for authoring models. The restrictions caused by the encapsulation of the entire process can be severe: the challenges of integration were emphasised above \cite{sculley2015hidden}. Additionally, an engineer working on Microsoft's comparable solution, the Azure ML Studio, highlighted that once users gain enough understanding of ML, such visual tools can get in their way, and they may need to seek out other solutions \cite{amershi2019software}. Unfortunately, the main value proposition of Azure ML Studio is also to provide a UI for laypeople, and it has also been set to be retired by 2024. Its successor is Azure Machine Learning which shares many similarities with AWS's SageMaker suite \cite{joshi2020amazon}.
+IBM's AutoAI \cite{wang2020autoai} promises to provide automation for the entire machine learning lifecycle, including deployment. It is a closed-sourced, paid service which --- from their documentation --- seems to focus primarily on non-technical users by providing them with a graphical user interface (GUI) for authoring models. The restrictions caused by the encapsulation of the entire process can be severe: the challenges of integration were emphasised above \cite{sculley2015hidden}. Additionally, an engineer working on Microsoft's comparable solution, the Azure ML Studio, highlighted that once users gain enough understanding of ML, such visual tools can get in their way, and they may need to seek out other solutions \cite{amershi2019software}. Unfortunately, the main value proposition of Azure ML Studio is also to provide a GUI for laypeople, and it has also been set to be retired by 2024. Its successor is Azure Machine Learning which shares many similarities with AWS's SageMaker suite \cite{joshi2020amazon}.
 
 SageMaker offers the most comprehensive suite of tools and services; most importantly, it has a set of features called \textit{AWS SageMaker MLOps}. This provides easy and/or default implementations for multiple industry best practices described in \cite{serban2020adoption,serban2021practices,john2020ai}. Among others, it promotes using CI/CD, model monitoring, tracing, model versioning, storing both data and models on shared infrastructure, numerous collaboration tools, etc. Nonetheless, SageMaker does not enjoy universal adoption, as indicated by the survey data. The cause of this may be the lack of a self-hosting option and its relatively high prices: many companies prefer on-premise hosting for privacy, and financial reasons \cite{bosch2021engineering}. Additionally, vendor lock-in and possibly --- in the case where it is not already used for the project --- the initial effort required for setting up AWS integration could be likely deterrents.
 

docs/thesis/chapters/4_design.tex

@@ -98,7 +98,7 @@ Although API design has been the central subject so far, it is worth remembering
 
 The general theme in the implementation is that each explicit best practice should have its distinct, loosely-coupled functions or classes. When collaboration opportunities arise, such as persisting the model versions (\nth{1} component) into prediction traces (\nth{2} component), there are three primary conduits for realising them. These are the \texttt{context} object responsible for the global configuration per process, the \texttt{FunctionMetadataStore} specifying the expected behaviour of each prediction function, and finally the \texttt{TracingContext} that is created anew for each prediction input (session).
 
-After refining the framework with feedback gathered from case studies and users, we will end up with the core architecture presented in Figure \ref{fig:architecture}. The implementation is mixed-paradigm, combining the expressiveness of functional and the design patterns of object-oriented programming (OOP) in order to maintain an overall low complexity. Reflection is also utilised, especially for run-time type-checking and generating the API definitions and Dashboard components. Regardless, the architecture is still presented with a syntax similar to the class diagrams of UML2 \cite{Rumbaugh2004} because it provides the freedom to express even the non-OOP design aspects.
+After refining the framework with feedback gathered from case studies and users, we will end up with the core architecture presented in Figure \ref{fig:architecture}. The implementation is mixed-paradigm, combining the expressiveness of functional and the design patterns of object-oriented programming (OOP) in order to maintain an overall low complexity. Reflection is also utilised, especially for run-time type-checking and generating the API definitions and dashboard components. Regardless, the architecture is still presented with a syntax similar to the class diagrams of UML2 \cite{Rumbaugh2004} because it provides the freedom to express even the non-OOP design aspects.
 
 For the sake of brevity, Figure \ref{fig:architecture} does not show all fields, and some related entities have been combined, e.g. the \textit{GroundTruthAPI} box represents the \texttt{add\_ground\_truth}, \texttt{query\_ground\_truth}, and \texttt{delete\_ground\_truth} functions. The client project can also access most of the presented entities, but these optional dependency arrows are not shown in the diagram. The \texttt{utilities} submodule is also left unexpanded; almost all of its functions are orthogonal with the exception of \texttt{parallel\_map}. The latter follows a textbook producer-consumer model facilitated by queues and event signals \cite{wang2020producer}.
 

docs/thesis/chapters/5_cases/main.tex

@@ -1,12 +1,12 @@
 \chapter{The ScoutinScience Platform} \label{chapter:case}
 
-The core product of ScoutinScience B.V.\footnote{\href{https://scoutinscience.com/}{scoutinscience.com}} is its Platform\footnote{\href{https://dashboard.scoutinscience.com/}{dashboard.scoutinscience.com}}. The clients are technology-transfer offices of Dutch and German universities, government organisations (e.g. Wetsus), and corporations (e.g. Heraeus Group and Ruma Rubber B.V.) who wish to extend the scope of their R\&D activities. ScoutinScience connects to multiple data sources of academic publications and integrates them into a single database. Each new publication is evaluated with a suite of AI components that ultimately determine its technology-transfer potential. Other markers are also extracted that help the users get a quick overview of the authors, topics, and contributions of a given piece of research.
+The core product of ScoutinScience B.V.\footnote{\href{https://scoutinscience.com/}{scoutinscience.com}} is its Platform\footnote{\href{https://dashboard.scoutinscience.com/}{dashboard.scoutinscience.com}}. The clients are Technology Transfer Offices of Dutch and German universities, government organisations (e.g. Wetsus), and corporations (e.g. Heraeus Group and Ruma Rubber B.V.) who wish to extend the scope of their R\&D activities. ScoutinScience connects to multiple data sources of academic publications and integrates them into a single database. Each new publication is evaluated with a suite of AI components that ultimately determine its technology-transfer potential. Other markers are also extracted that help the users get a quick overview of the authors, topics, and contributions of a given piece of research.
 
 Each client organisation gets to see a different filtered view of this database ranked by the predicted probability of technology-transfer opportunities being present. The main motivation is to make these business developers' and other professionals' work more efficient by showing them which papers have the highest chance of being considered interesting by them. 
 
 To achieve this, we have a service-based architecture \cite{kleppmann2017designing} on the backend-side --- apart from the data integration, communication, and business logic --- it is made up of services wrapping simpler (phrase-matching, Naïve Bayes) and more sophisticated (conditional random fields, transformer) models. As we will soon see, these can also depend on each other; for instance, based on the predicted scientific domain, a different model can be chosen for scoring certain aspects of papers.
 
-I was among the first engineers on the team, which has grown considerably in the past two years. While architecting, designing, and integrating more and better models into our software solution, I experienced the same difficulties as were described in Chapter \ref{chapter:background}. The gap between prototypes and production-ready services is larger than it seems, and it is also larger than it should be. This has motivated me to investigate the state-of-the-art, and I have found that it is insufficient in many cases. Since the ScoutinScience platform is a typical example of applying AI in the industry, it will serve as the real-life case, problem context, and testbed for attempting to design a solution that can hopefully advance the state-of-the-art.
+I was among the first engineers on the team, which has grown considerably in the past two years. While architecting, designing, and integrating more and better models into our software solution, I experienced the same difficulties as were described in Chapter \ref{chapter:background}. The gap between prototypes and production-ready services is larger than it seems, and it is also larger than it should be. This has motivated me to investigate the state-of-the-art, and I have found that it is insufficient in many cases. Since the ScoutinScience Platform is a typical example of applying AI in the industry, it will serve as the real-life case, problem context, and testbed for attempting to design a solution that can hopefully advance the state-of-the-art.
 
 This chapter describes the process of designing \textit{GreatAI} and how it fits into real-life use cases. First, a simple experiment is presented which investigates a Naïve Bayes classifier's \cite{maron1961automatic} accuracy at predicting the fields of papers. This leads to the implementation of a software service that is deployed to production. Subsequently, as the feature set of the library grows and matures, a more complex component is developed concerning text-summarisation with SciBERT \cite{beltagy2019scibert}. After implementing each case, the insights gained are fed back into the library's design.
 

docs/thesis/chapters/5_cases/naive-bayes.tex

@@ -48,7 +48,7 @@ MAG needs no further preprocessing if we aim to match SciBERT's setup \cite{belt
 
 \subsection{Methods}
 
-Our aims are twofold: (1) to evaluate a sentence classification model on MAG and compare it with the prior art; and (2) to retrain and apply this model for classifying publication metadata (including abstracts). This would allow the ScoutinScience platform to select an appropriate processing pipeline which has been trained on a matching vocabulary (and domain) for each publication. 
+Our aims are twofold: (1) to evaluate a sentence classification model on MAG and compare it with the prior art; and (2) to retrain and apply this model for classifying publication metadata (including abstracts). This would allow the ScoutinScience Platform to select an appropriate processing pipeline which has been trained on a matching vocabulary (and domain) for each publication. 
 
 It seems reasonable that only considering the distribution (frequencies) of individual terms may be sufficient. For testing this hypothesis, a unigram language model --- Multinomial Naïve Bayes (MNB) --- is constructed, and its accuracy is compared with SciBERT's. The former definitely aligns with the advice to \textit{Use The Most Efficient Models}. Using the MNB implementation of scikit-learn \cite{pedregosa2011scikit}, it only took 71 lines of code to create, hyperparameter optimise, and test a text classifier.\footnote{The code is available at \href{https://great-ai.scoutinscience.com/tutorial/}{great-ai.scoutinscience.com/tutorial}.} This further proves how simple it is to use standard packages. The code can be considered for satisfying the \textit{Automate Hyper-Parameter Optimisation} best practice since it also implements an automated hyperparameter sweep. 
 

docs/thesis/chapters/5_cases/scibert.tex

@@ -27,7 +27,7 @@ In order to compile a new dataset, experts are asked to judge sentences that pas
     \centering
     \includegraphics[width=0.75\linewidth]{figures/annotator.png}
     \captionsetup{width=.9\linewidth}
-    \caption{The annotator UI showing a single sentence and the two labels that can be assigned based on its relevance to technology-transfer.}
+    \caption{The annotator GUI showing a single sentence and the two labels that can be assigned based on its relevance to technology-transfer.}
     \label{fig:annotator}
 \end{figure}
 
@@ -99,10 +99,10 @@ Figure \ref{fig:histograms} shows the ratio of summary candidate sentences as pr
 
 \subsection{Deployment}
 
-To implement the summarisation, at most, the top 7 selected sentences are chosen as ranked by their log probabilities. They are subsequently reordered according to their position in the text. As a quasi-explanation, the tokens' attention scores are visualised and overlaid on the highlighted sentences. The \textit{i}-th token's visualised attention comes from summing up the attention weights of each of the last layer's heads between the \texttt{[CLS]} and the \textit{i}-th token. To improve the end-user experience, a high-pass filter and a stop-word list are applied to the scores to avoid highlighting the syntax-related tokens (punctuation, determiners). The service --- after being integrated into the dashboard --- can be seen in Figure \ref{fig:dashboard-highlights}.
+To implement the summarisation, at most, the top 7 selected sentences are chosen as ranked by their log probabilities. They are subsequently reordered according to their position in the text. As a quasi-explanation, the tokens' attention scores are visualised and overlaid on the highlighted sentences. The \textit{i}-th token's visualised attention comes from summing up the attention weights of each of the last layer's heads between the \texttt{[CLS]} and the \textit{i}-th token. To improve the end-user experience, a high-pass filter and a stop-word list are applied to the scores to avoid highlighting the syntax-related tokens (punctuation, determiners). The service --- after being integrated into the Dashboard --- can be seen in Figure \ref{fig:dashboard-highlights}.
 
 \begin{displayquote}
-\textbf{Design inspiration} In order to get insights into their inner workings, Hugging Face models can be given \texttt{output\_attentions=True} in their constructor, which results in a new property becoming accessible on the results for querying the attentions. The only issue with it is that it is a 5-dimensional matrix which makes exploring and understanding it non-obvious. In short, it has very low \textit{Discoveribility}. For example, the attention weights for the UI are calculated with this expression:
+\textbf{Design inspiration} In order to get insights into their inner workings, Hugging Face models can be given \texttt{output\_attentions=True} in their constructor, which results in a new property becoming accessible on the results for querying the attentions. The only issue with it is that it is a 5-dimensional matrix which makes exploring and understanding it non-obvious. In short, it has very low \textit{Discoveribility}. For example, the attention weights for the GUI are calculated with this expression:
 \begin{minted}[
 baselinestretch=1,
 ]{python}

docs/thesis/chapters/6_results.tex

@@ -148,7 +148,7 @@ The effortless parallel feature extraction and large file handling support were
 
 When reflecting on the framework from a bird's eye view, the generality and extensibility of the API were emphasised. As explained by a senior engineer, this is mainly because once you commit to using it, it is important not to find yourself at a dead end for a specific use case forcing you to look for a different library. However, two participants also noted that for complete generality, \texttt{MATLAB} support would be necessary. Regarding non-functional features, private hosting (especially in banking and government), open-source auditability, and good scalability (by means of an external database) were the top subjects of praise.
 
-\paragraph{API} Regarding the surface through which clients interact with the library, the feedback is also positive but more nuanced. Many participants liked that the functions' behaviour is easy to guess from their names. The decorator syntax caused minor confusion but consulting the documentation solved the issues in all three cases. The CLI app \texttt{great-ai} was appreciated for having a close to trivial signature; the participant noted that she strives to use as few CLI commands as feasible. Surprisingly, even the practitioners with more data science background appreciated the Docker support. Nonetheless, one expert had a feature request for a configuration UI because his colleagues are used to handling MATLAB App Designer applications.
+\paragraph{API} Regarding the surface through which clients interact with the library, the feedback is also positive but more nuanced. Many participants liked that the functions' behaviour is easy to guess from their names. The decorator syntax caused minor confusion but consulting the documentation solved the issues in all three cases. The CLI app \texttt{great-ai} was appreciated for having a close to trivial signature; the participant noted that she strives to use as few CLI commands as feasible. Surprisingly, even the practitioners with more data science background appreciated the Docker support. Nonetheless, one expert had a feature request for a configuration GUI because his colleagues are used to handling MATLAB App Designer applications.
 
 The recurring theme of the discussions focused on the question of ``\textit{How simple is too simple?}''. The argument is that an API cannot be simpler than the domain in which it exists. More precisely, it can only be simpler at the cost of losing transparency. Let us take the example of saving models using \texttt{save\_model()}. If a project is set up correctly, it either has an initial \texttt{configure()} call to the storage provider backend, or it has an appropriately named credentials file in the project's root, for instance, \texttt{s3.ini} or \texttt{mongo.ini}. Once set up, it is trivial to use as long as we do not divert from the happy path. However, if an issue arises, such as an upgrade or migration of MongoDB, debugging the application is non-trivial for its lack of transparency.