PLOVER_MANUAL.tex

\documentclass[11pt]{report}
\usepackage[left=1in,top=1in,right=1in,bottom=1in]{geometry} % see geometry.pdf on how to lay out the page. There's lots.
\geometry{letterpaper} % or letter or a5paper or ... etc
\pagestyle{headings}
\usepackage{geometry}
\usepackage{graphicx}
\usepackage[usenames]{color}
\definecolor{purple}{rgb}{.5, 0, .5}
\usepackage{longtable}
\usepackage{multirow}
\usepackage{multicol}
\usepackage{booktabs}
\usepackage[table]{xcolor}
\usepackage{verbatim} % for comment blocks
\usepackage{natbib}
\usepackage{datetime} % To set the document dates automagically
\usepackage[hidelinks]{hyperref} % for real url support in the pdf
\usepackage[normalem]{ulem} % for \sout{} strikethrough

% Define a new column type with fixed width (like p{{}), but which doesn't justify text
\usepackage{array}
\newcolumntype{L}[1]{>{\raggedright\arraybackslash}p{#1}}

\newcommand{\plcat}[1]{\textsf{#1}}
\newcommand{\plcon}[1]{\textbf{#1}}
\newcommand{\plmod}[1]{\texttt{#1}}
\newcommand{\ti}[1]{\textit{#1}}
\newcommand{\txt}[1]{\texttt{#1}}
\newcommand{\fn}[1]{\footnote{#1}}
\newdateformat{monthyeardate}{%
 \THEDAY~\monthname[\THEMONTH] \THEYEAR}

\newcommand{\andy}[1]{\textcolor{red}{#1}}
	
\begin{document}

\pagenumbering{gobble}

\vspace{-10pt}	

      \begin{center}
            {\Huge \bfseries PLOVER\ }\\[2ex]
            {\LARGE Political Language Ontology for Verifiable Event Records\\ [2ex]Event, Actor and Data Interchange Specification}\\[10ex]
            {\LARGE Open Event Data Alliance} \\[2ex]
            {\Large \url{http://openeventdata.org/} }\\[2ex]
            {\LARGE DRAFT Version: 2.0\\ [2EX]\monthyeardate\today}
        \end{center}


\begin{figure}[h!]
\centering
\includegraphics[width=0.40\textwidth]{media/plover_icon}
\end{figure}

\vspace{20pt}	


\begin{figure}[h!]
\centering
\includegraphics[width=0.6\textwidth]{media/cc_license}
\end{figure}





%\pagenumbering{roman}
%\tableofcontents
%\setcounter{tocdepth}{3}
%\listoftables

\chapter*{Acknowledgments}

\noindent Contributors to the development of PLOVER include, in alphabetical order, Benjamin Bagozzi, Andreas Beger, John Beieler, Liz Boschee, Patrick Brandt, Andrew Halterman, Jill Irvine, Jennifer Holmes, Javier Osorio, Tom Parris, Grace Scarborough, and Philip Schrodt.\\

\noindent The Open Event Data Alliance is an educational and open research corporation chartered in the Commonwealth of Virginia, United States.\\

\noindent The PLOVER logo is based on a drawing found at\\ {\footnotesize \url{http://www.rspb.org.uk/discoverandenjoynature/discoverandlearn/birdguide/name/r/ringedplover/}}\\

\noindent Funding for PLOVER was initially provided in part by the U.S. National Science Foundation award SBE-1539302, ``RIDIR: Modernizing Political Event Data for Big Data Social Science Research''. Any opinions, findings, conclusions or recommendations in this document are those of [at least one of] the authors and do not necessarily reflect the views of the National Science Foundation, or any company or government agency employing or funding the authors or otherwise contributing to the document.\\

\noindent Additional work was sponsored by the Political Instability Task Force (PITF). The PITF is funded by the Central Intelligence Agency. The views expressed in this codebook are the authors' alone and do not
represent the views of the US Government.\\

\noindent Readers interested in the POLECAT data that were generated using the PLOVER ontology should see \citet{ScarboroughEtAl2023} and \citet{HaltermanEtAl2023}.\\

\noindent This document is hosted at the following GitHub repository: \txt{\footnotesize https://github.com/openeventdata/PLOVER}\\


\noindent This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.\\

\noindent  Copyright \copyright ~2021 by the Open Event Data Alliance \\

\noindent Latest update: \today~(UTC)


\chapter{Introduction}
\pagenumbering{arabic}

The concept of political event data originated in the academic quantitative international relations community in the mid-1960s. While a number of projects produced some event data, often for specialized applications, eventually two coding frameworks dominated the production of general-purpose event data sets: Charles McClelland's WEIS \citep{McClelland67,McClelland76}  and the Conflict and Peace Data Bank (COPDAB) developed by Edward Azar \citep{AzarSloan75, Azar80, Azar82}. Both were created during the Cold War and assumed a ``Westphalian-Clausewitzian'' political world in which sovereign states reacted to each other primarily through official diplomacy
and military threats. Consequently these coding systems proved less than optimal for dealing with post-Cold-War issues such as ethnic conflict, low-intensity violence, internal conflict and repression, and multilateral intervention.

During the early 2000s, the CAMEO framework---Conflict and Mediation Event Observations---was developed \citep{SGY09} to support an NSF-funded project at the University of Kansas on the study of inter-state conflict mediation, not as a general-purpose event ontology. Nonetheless, it was gradually adopted as a ``next generation'' coding scheme, notably for the DARPA-funded Integrated Conflict Early Warning System (ICEWS) project \citep{OBrien10} because it corrected some of the long-recognized ambiguities in WEIS and COPDAB, and was explicitly designed both for automated coding and for the detailed coding of sub-state actors. It was continued in the widely-used public ICEWS data (\txt{https://dataverse.harvard.edu/dataverse/icews}) coded using the BBN SERIF/ACCENT coder, with BBN doing considerable additional work on various details of the system.

As event data came into wider use in the 2010s, several problems with CAMEO became apparent, largely dealing with the complexity of the system, the absence of a standard format beyond the original  date-source-target-event fields (for example, representing geographical location), and continuing interest on coding substate activities not present in the earlier systems.

To address these concerns, an informal group of academic, government and private sector producers and users of event data met and circulated drafts during the fall of 2016 to develop a new, simplified and more flexible event data specification to replace CAMEO, which became PLOVER and the basis of this document: Section \ref{ssec:ctp} summarizes the major changes. Additional extensive
work was done in 2021 as PLOVER was adopted by the Political Instability Task Force to replace
CAMEO in its new coder for iDATA (the next generation ICEWS).

Because the PLOVER event categories are generally a simplification of CAMEO our expectation is that it will be relatively easy to splice existing CAMEO data sets to PLOVER equivalents by simply collapsing the two- and three-digit categories. The scaled ``PLOVER scores'' are also designed for splicing with time series generated from the CAMEO ``Goldstein scores.'' The standardization of the JSON field names---as well as adoption of JSON as the data interchange format---will allow the development of general-purpose utilities that can work with all formats, in contrast with the current proliferation of incompatible and error-prone CSV and tab-delimited formats.

Compared to the Kansas and BBN CAMEO manuals---though curiously, consistent with the public documentation for WEIS and COPAB in the ICPSR archive---at this point we have provided only general guidance on the content of the various categories, modes, and contexts. With the current state of automated natural language processing, any 2020s automated coding system will almost certainly be implemented using machine learning systems trained on a labeled set of news texts and those training cases effectively are the detailed examples. This differs from the older systems which classified events using dictionaries which were abstracted, by human developers, from the texts. We eventually hope to provide a set of training cases, possibly synthetic, that will be free of intellectual property constraints; at present a small set of cases extracted from the Kansas CAMEO manual is available on the PLOVER GitHub site \txt{https://github.com/openeventdata/PLOVER} but it is not sufficient for training a system, at least with 2021 technologies.


\section{Why ``PLOVER''?}

Plovers (\textit{Charadriidae}) are a globally-distributed family of short-billed gregarious wading birds who spend their lives frantically poking through endless stretches of sand and muck trying to find something of interest. It is difficult to imagine a better analogy to the process of coding event data.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Event, Mode, and Context}

\section{Overview}\label{ssec:ecm}

A major difference between PLOVER and the earlier widely-used event coding systems is moving the information in the hierarchical 3- and 4-digit categories of CAMEO into three components: \txt{event-mode-context} generally corresponding to ``\texttt{what-how-why}.'' We anticipate at least five advantages to this approach:

\begin{enumerate}

\item The three \texttt{what-how-why} components are now distinct, whereas various CAMEO subcategories inconsistently used the $how$ and $why$ to distinguish between subcategories.

\item Because a \txt{context} can be applied to any event category and, where relevant, any \txt{mode}, PLOVER has far more combinations of codes for describing events than the fixed hierarchy of CAMEO.

\item We are probably increasing the ability of general machine-learning classifiers---as distinct from the older customized dictionary-based parser/coders---to assign \txt{mode} and \txt{context} compared to their ability to assign subcategories.

\item In initial experiments, it appears this  approach is \textit{much} easier for humans to code than the hierarchical structure of CAMEO because a human coder can hold most of the relevant categories in working memory. More generally,  \txt{event-mode-context}  coding uses words, not numerical codes, so coders will probably be using the parts of the brain (Broca's area) which are specialized for processing words. No known specialized cognitive facility exists for handling some 250 2-to-4-digit codes.

\item Because the words used to differentiate \txt{mode} and \txt{context} are generally very basic, translations of the coding protocols into languages other than English is likely to be easier than translating the subcategory descriptions found in CAMEO.
\end{enumerate}

While both \txt{mode} and \txt{context} will usually take a single value, in some instances multiple values will be appropriate and this is allowed. Both fields are optional, and if no existing values seem appropriate, the field should be left null, though perhaps with some details provided in the JSON \texttt{comment} field, particularly when the record is generated using human coding.



\section{Context codes that can be used with any category}

The \txt{context} field re-introduces, albeit in a greatly extended form, a concept found in the original COPDAB data (but absent from WEIS and hence CAMEO) which allows, for example, a distinction in the event record between a meeting dealing with military issues and a meeting dealing with economic issues. Human analysts naturally incorporate this information in their reading of an article. Based on some initial experiments, we believe that with contemporary text classification algorithms this should be relatively easy to implement.

Additional details and clarifications for some of the more ambiguous or complicated general contexts listed in \autoref{tab:general-contexts} can be found in \autoref{chapter:contexts}.

%%%%%%%%%%%% START CONTEXTS TABLE %%%%%%

\begin{longtable}{|p{.21\textwidth}|L{.73\textwidth}|}
\caption{General contexts\\ (Each context has additional details in \autoref{chapter:contexts})}
\label{tab:general-contexts} \\
\hline
Name & Content \\
\hline
\endhead

\hline \multicolumn{2}{|l|}{{Continued on next page}} \\ \hline
\endfoot

\hline
\endlastfoot
\hyperref[context:military]{military} & military, including military assistance; only covers official state military bodies, \textit{excluding} paramilitary or militia organizations, law enforcement, or non-state armed actors \\
\hyperref[context:intelligence]{intelligence} & gathering of information by state intelligence organizations, including more general discussions of those agencies \\
\hyperref[context:executive]{executive} & executive agencies and bureaucracies, executives and their families, as well as personal and political issues involving non-elected heads of state \\
\hyperref[context:legislative]{legislative} & legislative debate, parliamentary coalition formation \\
\hyperref[context:election]{election} & elections and campaigns \\
\hyperref[context:political-institutions]{political\_institutions} & changes to---as well as non-routine interactions between and within---formal political bodies, including political parties \\
\hyperref[context:pro-democracy]{pro\_democracy} & processes and initiatives associated with democratization \\
\hyperref[context:pro-autocracy]{pro\_autocracy} & processes and initiatives associated with autocratization \\
\hyperref[context:economic]{economic} & economic news, trade, finance, economic development, inflation/GDP/recessions, or monetary policy. \emph{Exclude} news solely about individual companies \\
\hyperref[context:legal]{legal} & courts and judiciary; national and international law\\
reparations & reparations, i.e., monetary or non-monetary compensation for past harm inflicted \\
\hyperref[context:hr]{human\_rights} & unspecified human rights in a general sense, often but not always literally including the term ``human rights'' \\
\hyperref[context:rightsfree]{rights\_freedoms} & political rights and freedoms, civil liberties, press/media freedom, restrictions on civil rights, gatherings, etc.\\
\hyperref[context:repression]{repression} & forceful repression of groups, individuals, or societies by security forces \\
\hyperref[context:human-sec]{human\_security} & access to water, food, housing, energy, land/property tenure (e.g. seizure of crops), etc. \\
gender & mentions of gender, women's issues, gender equality, etc., including abortion and issues of reproductive rights\\
\hyperref[context:lgbt]{lgbt} & LGBTQ issues such as related laws, discrimination, and protests\\
\hyperref[context:religethno]{religion\_ethnicity} & religious, ethnic, caste, or linguistic issues, including discrimination, violence, cooperation, or more broadly important mentions \\
\hyperref[context:inequality]{inequality} & the unequal distribution of resources and opportunities  \\
\hyperref[context:diplomatic]{diplomatic} & diplomacy, which can be both international and domestic \\
\hyperref[context:territory]{territory} & international and domestic territorial disputes, protests and rebellions over territory, and forced displacements\\
peacekeeping & peacekeeping, typically multilateral operations \\
\hyperref[context:health]{health} & public health, disease outbreaks and epidemics, disease in general \\
\hyperref[context:asylum]{asylum} & discussions of seeking or granting asylum \\
\hyperref[context:migration]{migration}  & migration, refugees, and displaced people \\
\hyperref[context:disasters]{disasters} & disasters including both ``natural" and accidents/spills etc. \\
\hyperref[context:natural-resource]{natural\_resource} & natural resource extraction, trade, dependence, and pollution \\
\hyperref[context:environment]{environment} & pollution and related environmental problems; environmental policy, environmental cooperation, and environmental protest \\
\hyperref[context:tech]{technology} & technological development, new technology, high-tech industry\\
\hyperref[context:terrorism]{terrorism} & events related to terrorist groups; anti-terrorism actions and policies \\
\hyperref[context:cbrn]{cbrn} & chemical, biological, radiation, and nuclear weapons or attacks  \\
\hyperref[context:cyber]{cyber} & cyber attacks and crime; events with this context are not necessarily cyber events (e.g. hacking) themselves\\
\hyperref[context:misinfo]{misinformation} & misinformation, influence operations, fake news; events with this context are not necessarily misinformation themselves\\
\hyperref[context:crime]{crime} & Any discussion of crimes or criminals, \textit{excluding} events that have one of the more specific crime contexts like trafficking \\
\hyperref[context:corruption]{corruption} &  misuse/abuse of public office, including corruption, bribery, cronyism, nepotism, abuse of public office  \\
\hyperref[context:drugs]{illegal\_drugs} & criminal possession, distribution, sale, or manufacturing of illegal drugs \\
\hyperref[context:trafficking]{trafficking} & trafficking or smuggling of humans, drugs, animals, or other goods; both domestic and international \\
\end{longtable}

%%%%%%%%%%%% END CONTEXTS TABLE %%%%%%

How these contexts are used in practice will depend on how a coder implements them. If they are applied using document-level classifiers, researchers/analysts could misinterpret the meaning of contexts. For example, an \plcat{ASSAULT} event with an ``elections'' context does not necessarily imply electoral violence. It could be an article about, for instance, violence in Afghanistan in the context of an article on US election politics. Thus, the interpretation of ``context'' may depend on how it's implemented in practice. Certain types of events, particularly general protests and meetings, will also have multiple contexts: this is a feature, not a bug.

Based on our past experience developing event-oriented data sets, we are almost certain to find some additional contexts as we start coding data, so this list is likely to change somewhat.  In many cases, it may be possible to extract the information needed for specialized applications by simply modifying the \txt{context} coding---which should be relatively easy---rather than modifying the event category coding, which is more difficult but was the only option in the older hierarchical systems.

\newpage

\section{Auxiliary modes}\label{ssec:special}

\textbf{Note: these Auxiliary modes have not yet been fully implemented in any PLOVER-based coding projects to date.}

PLOVER also includes four \emph{auxiliary modes}, which provide information about whether a reported event is \plcon{historical}, \plcon{future}, \plcon{hypothetical}, or has a \plcon{negation}. PLOVER assumes that the coding engine will be able to resolve these and put that information in the \txt{context}. Negated events can be excluded from the final event dataset. Examples:
   \begin{itemize}
   \item \plcon{historical}: ``During the decolonization struggle, Angolan forces..."
   \item \plcon{future}: ``Members of the G-7 will meet in Ottawa next month..."
   \item \plcon{hypothetical}: ``If Russian forces were to cross the border, that would represent a major..."
   \item \plcon{negation}: ``Thus far, fighting has not re-emerged in the tense region."	
   \end{itemize}

Theoretically, some event types can be represented as other event types plus an auxiliary mode: \plcat{AGREE} could be  \plcat{SUPPORT} + \plcon{future} or \plcat{THREATEN} could be \plcat{ASSAULT} + \plcon{hypothetical}. In situations like these, the coder should always return the single event category, not a category+auxiliary.

We anticipate that in general---and consistent with earlier event coding schemes---it will be possible to code \txt{mode} from the same sentence used to code the event, or possibly that sentence and one before it. \txt{context}, in contrast, will usually be coded at the paragraph- or document-level: this differs from earlier automated coding, though probably is similar to human-coded data such as COPDAB and BCOW \citep{Leng87} where \txt{context}-like fields were coded.


\section{Changes in treatment of political entities}\label{ssec:change}

\subsection{``actor'' and ``recipient'' replace ``source'' and ``target''}

In order to reduce overlap with how the policy community uses the terms  ``source'' and ``target'', we are using the word \txt{actor} to refer to the entity or entities who initiated the event, and \txt{recipient} to refer to the
 the entity or entities to whom the event is directed, if this is clear. \txt{recipient} is optional for many events. We are using the term ``entity'' to refer to the class of potential actors and recipients.

\subsection{Compound and Reciprocal Actors}\label{sec:recip}

Following the dyadic approach which originated in WEIS and COPDAB,  most CAMEO-based coders dealt with compound entities---``The United States and France accused Russia\ldots''---by generating multiple events: this example would generate two events of the form
\begin{verbatim}
	USA  RUS  112
	FRA  RUS  112
\end{verbatim}
This approach, however, gets very problematic in the not-uncommon situation where an alliance is involved and is expanded to all of its constituent members: a single reference to the G20 expands to at least twenty events, and a \textit{meeting} of the G20, generating reciprocal events, expands to 380 events, which is one of the reasons ``consult'' events are so frequent in CAMEO-coded data.

In PLOVER, compound entities generate a single actor or recipient, but with multiple members: the actor and recipient are a list of entities rather than a single entities. Depending on the application, a user might expand this in a post-processing phase to multiple events with single entity codes following the earlier conventions, but the initial coding of the event uses the list.

PLOVER also uses actor lists to deal with reciprocal events. In CAMEO, a meeting ``President Obama met with Japanese Prime Minister Abe at the White House'' generated two events
\begin{verbatim}
	JAP  USA  042
	USA  JAP  043
\end{verbatim}
where 042 and 043 are the CAMEO codes for ``visit'' and ``host'' respectively.\footnote{This example optimistically assumes the coding system was clever enough to recognize the significance of the phrase ``at the White House.''} While the PLOVER \plcat{CONSULT} mode provides for a host/visit distinction, this is not required. In such instances, all of the entities are considered as the actor and no recipient is included.

%In \plcat{ASSAULT} events, reciprocal violence---as distinct from one-sided violence---is handled in a similar fashion, with both entities as \texttt{actor}: this applies in any event where both sides are using force, even if one side ``started it'', an assessment often as not contested anyway. One-sided violence, such as assassinations or police firing on demonstrators, will have the perpetrator as the \texttt{actor} and the victims as \texttt{recipient}. The \plmod{sideAB} mode in  \plcat{ASSAULT} is used in conjunction with the \texttt{recipient} field when there are two clear ``sides'' in the conflict.



%\clearpage

\section{Numeric conflict/cooperation scores}

%Researchers and analysts often want to represent events along a conflict/cooperation scale. In CAMEO, these were called ``Goldstein scores'' since they were an extension of the WEIS scores in \cite{Goldstein92} which mapped the CAMEO codes to a $-$10 to $+$10 scale (though in fact the most cooperative action had score of only $+$8.5). The ``PLOVER scores'' given in Table \ref{tab:ploverscores} provide comparable scaled conflict/cooperation scores for PLOVER. They were created by taking a weighted average of the CAMEO/Goldstein scores for each PLOVER category, with the weights being the empirical frequency of the CAMEO event type in an 18 month sample (October-2017 to March-2019). Two additional changes were made based on our knowledge of the categories: COERCE and MOBILIZE were flipped, so COERCE was increased in magnitude from -5.3 to -7.2 and MOBILIZE moved from -7.2 to -5.3.

Researchers and analysts often want to represent events along a conflict/cooperation scale. In CAMEO, these were called ``Goldstein scores'' since they were an extension of the WEIS scores in \cite{Goldstein92} which mapped the CAMEO codes to a $-$10 to $+$10 scale. The ``PLOVER scores'' given in Table \ref{tab:ploverscores} provide comparable scaled conflict/cooperation scores for PLOVER. An initial mapping was created by taking a weighted average of the CAMEO-based Goldstein scores for each PLOVER category, with the weights being the empirical frequency of the CAMEO event type in an 18 month sample of data (October-2017 to March-2019).

Using this initial mapping and the original CAMEO-based Goldstein scores as  starting points, a subject matter expert then qualitatively developed a set of PLOVER scores for each of PLOVER's event types and modes. A second subject matter expert simultaneously developed an alternative set of proposed PLOVER scores through a combination of (i) pairwise comparisons of PLOVER event type-mode combinations and (ii) a Bradley-Terry model to estimate locations of each PLOVER event type-mode on a cooperative--conflictual scale. The two separately developed sets of PLOVER scores were then reviewed by a team of five subject matter experts (including the two mentioned above) to reconcile discrepancies. Ultimately, the final PLOVER scores presented below reflect a re-scaled average of the two sets of expert-derived PLOVER scores, with a small number of qualitative score adjustments that were implemented by the larger team of experts upon discussion. By and large, these final PLOVER scores reflect the original ``Goldstein scores'' in ranging from $-$10 to $+$10, with more positive values reflecting more cooperative actions and more negative values reflecting more conflictual actions.


%\begin{table}[htp]
%\begin{center}
%\caption{PLOVER conflict--cooperation scores}
%\begin{tabular}{lc}
%\hline
%\textbf{PLOVER category} & \textbf{PLOVER scores} \\
%\hline
%ASSAULT  & -9.3\\
%COERCE & -7.2\\
%PROTEST & -6.6\\
%MOBILIZE & -5.3\\
%SANCTION & -5.2\\
%THREATEN & -5.1\\
%REQUEST & -5.0\\
%REJECT & -4.2\\
%ACCUSE &  -2.0\\
%CONSULT &  +2.1\\
%AGREE & +4.2\\
%SUPPORT & +4.6\\
%CONCEDE & +5.0\\
%COOPERATE & +6.8\\
%AID & +7.4\\
%RETREAT & +7.6 \\
%\hline
%\end{tabular}
%\end{center}
%\label{tab:ploverscores}
%\end{table}


\begin{table}[htp]
\begin{center}
\caption{PLOVER conflict--cooperation scores}
\hspace*{-1.2cm}
\begin{tabular}{|lc|lc|lc|}
\hline
\textbf{CATEGORY: Mode} & \textbf{Score} & \textbf{CATEGORY: Mode} & \textbf{Score} & \textbf{CATEGORY: Mode} & \textbf{Score} \\
\hline
\cellcolor{gray!25}AGREE	&	\cellcolor{gray!25}2.5	&	\cellcolor{gray!25}REJECT	&	\cellcolor{gray!25}-2	&	\cellcolor{gray!25}COERCE	&	\cellcolor{gray!25}-7 \\
\cellcolor{gray!25}CONSULT	&	\cellcolor{gray!25}2.5	&	REJECT: Assist	&	-1.5	&	COERCE: Seize	&	-7 \\
CONSULT: Visit	&	4	&	REJECT: Change	&	-2	&	COERCE: Restrict	&	-7 \\
CONSULT: Third-party	&	1	&	REJECT: Yield	&	-2	&	COERCE: Censor	&	-6.5 \\
CONSULT: Multilateral	&	4	&	REJECT: Meet	&	-2	&	COERCE: Curfew	&	-6.5 \\
CONSULT: Phone	&	1.5	&	\cellcolor{gray!25}THREATEN	&	\cellcolor{gray!25}-3.5	&	COERCE: Martial-law	&	-7.5 \\
\cellcolor{gray!25}SUPPORT	&	\cellcolor{gray!25}5	&	THREATEN: Restrict	&	-3	&	COERCE: Arrest	&	-7 \\
\cellcolor{gray!25}CONCEDE	&	\cellcolor{gray!25}4.5	&	THREATEN: Arrest	&	-3.5	&	COERCE: Deport	&	-7 \\
\cellcolor{gray!25}COOPERATE	&	\cellcolor{gray!25}9.5	&	THREATEN: Relations	&	-3.5	&	COERCE: Withhold	&	-7 \\
\cellcolor{gray!25}AID	&	\cellcolor{gray!25}10	&	THREATEN: Expel	&	-3.5	&	COERCE: Misinformation	&	-6.5 \\
\cellcolor{gray!25}RETREAT	&	\cellcolor{gray!25}6.5	&	THREATEN: Territory	&	-4	&	COERCE: Cyber	&	-7 \\
RETREAT: Withdraw	&	8	&	THREATEN: Violence	&	-3.5	&	\cellcolor{gray!25}ASSAULT	&	\cellcolor{gray!25}-9 \\
RETREAT: Release	&	6.5	&	\cellcolor{gray!25}PROTEST	&	\cellcolor{gray!25}-5	&	ASSAULT: Abduct	&	-8.5 \\
RETREAT: Disarm	&	10	&	PROTEST: Demo	&	-5	&	ASSAULT: Beat	&	-7.5 \\
RETREAT: Ceasefire	&	7.5	&	PROTEST: Riot	&	-7	&	ASSAULT: Torture	&	-8.5 \\
RETREAT: Access	&	6.5	&	PROTEST: Strike	&	-5	&	ASSAULT: Sexual	&	-8.5 \\
RETREAT: Resign	&	4.5	&	PROTEST: Hunger	&	-4.5	&	ASSAULT: Targeted	&	-9.5 \\
\cellcolor{gray!25}REQUEST	& \cellcolor{gray!25}0 &PROTEST: Boycott	&	-4.5	&	ASSAULT: Destroy	&	-8.5 \\	
REQUEST: Assist	&	0.5	&	PROTEST: Obstruct	&	-4.5		&	ASSAULT: Primitive	&	-8 \\
REQUEST: Change	&	-1	&	\cellcolor{gray!25}SANCTION	&	\cellcolor{gray!25}-6		&	ASSAULT: Firearms	&	-9 \\
REQUEST: Yield	&	-1	&	SANCTION: Convict	&	-6	&	ASSAULT: Explosives	&	-9 \\
REQUEST: Meet	&	0	&		SANCTION: Expel	&	-5.5	&	ASSAULT: Suicide-attack	&	-9.5 \\
\cellcolor{gray!25}ACCUSE	& \cellcolor{gray!25}3&	SANCTION: Withdraw	&	-6		&	ASSAULT: Aerial	&	-9.5 \\
ACCUSE: Disapprove	&	-2	&	SANCTION: Discontinue	&	-6	&	ASSAULT: Drone	&	-9.5 \\
ACCUSE: Investigate	&	-3.5	&	\cellcolor{gray!25}MOBILIZE	&	\cellcolor{gray!25}-5.5	&	ASSAULT: Heavy-weapons	&	-9.5 \\
ACCUSE: Allege	&	-3.5	&	MOBILIZE: Troops	&	-6.5	&	ASSAULT: Crowd-control	&	-7.5 \\
	&		&	MOBILIZE: Weapons	&	-6.5	&	ASSAULT: Unconventional	&	-10 \\
	&		&	MOBILIZE: Police	&	-5.5	&	&\\
	&		&	MOBILIZE: Militia	&	-6	& &\\
\hline
\end{tabular}
\end{center}
\label{tab:ploverscores}
\end{table}

\chapter{Event Categories}

\section{AGREE}


Agree to, offer, promise, or otherwise indicate willingness or commitment to cooperate, including promises to sign or ratify agreements.  Cooperative actions of types \plcat{CONSULT}, \plcat{SUPPORT}, \plcat{COOPERATE}, and \plcat{AID} reported in future tense are also taken to imply intentions and should be coded as \plcat{AGREE}.


\subsection{Potential ambiguities}

\begin{itemize}
\item As noted in Section \ref{ssec:special}, there's the potential for some events to fit both the definition of \plcat{AGREE} and \plcat{SUPPORT} + \plcon{future}. For example, ``Russia and the United States \emph{will sign an agreement} limiting certain kinds of weapons...". When situations like this occur, the coder should always return the single event category that fits, rather than a category+auxiliary mode.
\item Future cooperative actions of type \plcat{RETREAT} + \plcon{future} and \plcat{CONCEDE} + \plcon{future} should be left as they are, i.e. they do not reduce to \plcat{AGREE}.
% AB 2021-09-22: not sure whether to include this
%\item There is some ambiguity in what should be coded as \plcon{future} versus realized or imminently realized cooperation. If the event concerns a specific action and it is clear that it will be realized, retain the original event category; otherwise code as \plcat{AGREE}. For example, ``France has said that it will provide \$ 5 million in military equipment to Ukraine'' should be coded as \plcat{AGREE}, while the more generic ``France has said that it will provide military aid to Ukraine'' should be coded as \plcat{AGREE}.
\end{itemize}

\subsection{Requires recipient: No}

\subsection{Supplementary fields: None}

\subsection{Quad category: VERBAL COOPERATION}

\newpage

\section{CONSULT}

All consultations and meetings: this includes visiting and hosting visits, as well as meeting at a neutral location, and consultation by phone or other media. Because this type of political event is both frequent and easily (and safely\ldots) covered in the international press, it is the largest category in most event data sets.  Additional useful keywords for identifying \plcat{CONSULT}: ``Holding talks'' and ``discussions'', ``negotiations, bargaining, or discussions''. See the discussion in Section \ref{sec:recip} on the treatment of actors in \plcat{CONSULT} events.

\subsection{Potential ambiguities}

\begin{itemize}

\item References to future meetings, summits, state visits, etc. and invitations for state visits should be coded as \plcat{AGREE}.

\item Consultations with ambassadors already in a country---typically this is done to complain about an action---should be coded for the content of the action. Since this is typically done to complain about actors, this would usually be \plcat{ACCUSE} or \plcat{REJECT} with modes such as \txt{ACCUSE-disapprove} or \txt{ACCUSE-allege}

\end{itemize}

\subsection{Requires recipient: No}

In \plcat{CONSULT} events where there is no clear distinction between whether an entity is hosting or visiting, all participants are coded in the \txt{actor} field. In events where one side is hosting and one is visiting, the visitor will always be coded as the \txt{actor} and the host will be the \txt{recipient}.

\subsection{Supplementary fields: modes}

\begin{table}[htp]
\caption{CONSULT modes}
\begin{center}
\begin{tabular}{|l|p{13cm}|}
\hline
Name & Content \\
\hline
visit & \txt{actor} is visiting, \txt{recipient} is hosting.\\
third-party & Meeting is hosted by a third party\\
multilateral & Meeting occurs in a multilateral context, typically an alliance or IGO\\
phone & Consultation occurs via phone or some other remote medium\\
\hline
\end{tabular}
\end{center}
\label{tab:consultmode}
Adapted from CAMEO.
\end{table}%

\subsection{Quad category: VERBAL COOPERATION}


\newpage

\section{SUPPORT}

Initiate, resume, improve, or expand diplomatic, non-material cooperation; express support for, commend, approve policy, action, or actor, or ratify, sign, or finalize an agreement or treaty. Use this code only for political, diplomatic, and non-material support, including recognition of newly independent states, new governments that might have come to power through unconventional means, and initiation of diplomatic ties with an entity for the first time.

\plcat{SUPPORT} is distinct from the CAMEO \plcat{APPEAL} category, where the actor simply \textit{requested} support from the recipient.

\subsection{Requires recipient: No}

\subsection{Potential ambiguities}

The term used for this category, \plcat{SUPPORT}, is a somewhat ambiguous. Although it may imply a material event, but this category should only be used for verbal cooperation.

\begin{itemize}
\item Formal pardons and amnesties of arrested persons should be coded as \plcat{CONCEDE}; the actual release  or exchange of prisoners should be coded as \plcat{RETREAT}.

\item Expressions of regret or remorse for an action or situation should be coded as \plcat{CONCEDE}.

\item Promises to sign or ratify agreements and treaties are coded as \plcat{AGREE}

\item Military cooperation or defense should be coded as \plcat{COOPERATE} with a \txt{military} $context.$
\end{itemize}

\subsection{Supplementary fields: None}


\subsection{Quad category: VERBAL COOPERATION}


\newpage

\section{CONCEDE}

This covers verbal concessions which have no immediate material consequences, including the promise of future concessions such easing of administrative or legal restrictions on persons and organizations, removing curfews, suspending protests, and declarations (but not implementations) of ceasefires and withdrawals from territory.

\plcat{CONCEDE}, like the verbal components CAMEO/WEIS predecessor \plcat{YIELD}, is inherently problematic since many concessions deal with promises that certain things will \ti{not} happen, or will happen in the distant future (e.g. many policy changes). So, for example, the lifting of a curfew is, effectively, a promise that people will not be arrested for violating the curfew, which itself is not an event. We're treating such concessions as verbal rather than material even though sometimes they have material consequences, e.g. people coming out in the streets after a curfew is lifted, provide they believe the entity lifting the curfew actually has done so.

\subsection{Requires recipient: No}

\subsection{Potential ambiguities}

\begin{itemize}
\item Formal pardons, acquittals, and amnesties of arrested persons should be coded as \plcat{CONCEDE}; the actual release or exchange of prisoners should be coded as \plcat{RETREAT}.
\item Expressions of regret or remorse for an action or situation should be coded as \plcat{CONCEDE}.
\item Future concessions, i.e. \plcat{CONCEDE} + \plcon{future} should be left as they are, i.e. they do not reduce to \plcat{AGREE}.
\item Announcements of future retreats should be coded as \plcat{CONCEDE}. E.g., ``announced...would withdraw troops" is \plcat{RETREAT} + \plcat{FUTURE} and should be coded as \plcat{CONCEDE}.
\end{itemize}

\subsection{Supplementary fields: None}

\subsection{Quad category: VERBAL COOPERATION}


\newpage

\section{COOPERATE}

Initiate, resume, improve, or expand \ti{mutual} material cooperation or exchange, including

\begin{itemize}
\item Initiate, resume, improve, or expand economic exchange or cooperation.

\item Military exchanges such as joint military games and maneuvers.

\item Cooperation on judicial matters, such as extraditions and war crimes.

\item Voluntary exchanges or sharing of intelligence and other significant information.

\end{itemize}

\subsection{Potential ambiguities}

\begin{itemize}
\item \plcat{COOPERATE} is distinguished from \plcat{AID} because the activity is generally understood to directly benefit both parties, whereas  \plcat{AID} is understood to primarily benefit only the recipient.
\item Promises, offers, or agreement for future cooperation should be coded as \plcat{AGREE}.
\end{itemize}

\subsection{Requires recipient: Yes}

\subsection{Supplementary fields: None}

\subsection{Quad category: MATERIAL COOPERATION}


\newpage

\section{AID}

All provisions of providing material aid whose material benefits primarily accrue to the recipient. Examples include:

\begin{itemize}

\item Monetary aid and financial guarantees, grants, gifts and credit, including reparations.

\item Military and police assistance including arms and personnel.

\item Humanitarian aid such as emergency assistance.

\item Asylum, both to persons in its territories (territorial asylum) and diplomatic asylum on the premises of an embassy.

\end{itemize}

\subsection{Requires recipient: Yes}

\subsection{Potential ambiguities}

\begin{itemize}
\item While reparations or voluntary settlements should be coded as \plcat{AID}, court-ordered payments should be coded as \plcat{SANCTION} events with the winner and court as actor and guilty party as recipient.
\item Broad promises of future \plcat{AID} should be coded as \plcat{AGREE}.
\item Debt forgiveness and loan cancellations, e.g. ``The Paris Club has agreed to forgive \$200 of Nigeria’s \$350 million in loan obligations, \dots'' should be coded as \plcat{AID}.
\item Hostage rescues, e.g. ``Pakistan’s military rescued 10 hostages from the border region with Afghanistan yesterday'' or ``Police in Barcelona freed 10 human trafficking victims during an operation yesterday'' should be coded as \plcat{AID}.
\end{itemize}

\subsection{Supplementary fields: None}

\subsection{Quad category: MATERIAL COOPERATION}

\newpage

\section{RETREAT}

\plcat{RETREAT} covers any events---not just military ``retreat'' from territory---which have an immediate (not simply promised) material consequences, such as the release of prisoners and hostages, repatriation of refugees, the return of  confiscated property, allowing the entry of observers, peacekeepers, or humanitarian workers, disarming, observing a ceasefire or otherwise ending active conflicts, and, of course, a military retreat from, or ceding, territory. \plcat{RETREAT} also covers resignations of government officials.

\subsection{Requires recipient: No}

\subsection{Potential ambiguities}

\begin{itemize}
\item Announcements of future retreats should be coded as \plcat{CONCEDE}. E.g., ``announced...would withdraw troops" is \plcat{RETREAT} + \plcat{FUTURE} and should be coded as \plcat{CONCEDE}.
\item Debt forgiveness and loan cancellations, e.g. ``The Paris Club has agreed to forgive \$200 of Nigeria’s \$350 million in loan obligations, \dots'' should be coded as \plcat{AID}.
\item Hostage rescues, e.g. ``Pakistan’s military rescued 10 hostages from the border region with Afghanistan yesterday'' or ``Police in Barcelona freed 10 human trafficking victims during an operation yesterday'' should be coded as \plcat{AID}.
\item Refugees or similar actors that are characterized fleeing a country or subnational location should be coded \plcat{SANCTION} `expel' with the causative agent as the actor rather than \plcat{SANCTION} `withdraw' or \plcat{RETREAT} `withdraw' with the actor coded as the fleeing party.
\end{itemize}

\subsection{Supplementary fields: modes}

\begin{table}[htp]
\caption{RETREAT modes}
\begin{center}
\begin{tabular}{|l|p{13cm}|}
\hline
Name & Content \\
\hline
withdraw & Retreat from territory or withdraw forces from an area\\
release & Release captives \\
%return & Return property \\
disarm & Disarm militarily or give up weapons\\
ceasefire & Implement ceasefire\\
access & Allow third party (e.g., observers, peacekeepers, humanitarian workers) access \\
resign & Official resignation \\
\hline
\end{tabular}
\end{center}
\label{tab:retreatmode}
\end{table}%

\subsection{Quad category: MATERIAL COOPERATION}



\newpage

\section{REQUEST}

All requests, demands, and orders. Requests, demands, and orders are less forceful than threats and potentially carry less serious repercussions. Coding will need to rely primarily on the language used by reporters to make this distinction. All requests are verbal acts.

\subsection{Requires recipient: No}


\subsection{Potential ambiguities}

\begin{itemize}
\item This category only applies to verbal demands: demands that take the form of demonstrations, protests, etc. are coded as \plcat{PROTEST}.
\item When one or more parties to a conflict call for ending the conflict, that is taken to be an expression of intent on the part of the \txt{actor} and is thus coded as \plcat{AGREE}.
\item Withdrawing a demand should be coded as \plcat{CONCEDE}.
\item \plcat{REQUEST} `change' includes calls for dismissal of officials (as in, a request for change in leadership).
\end{itemize}


\subsection{Supplementary fields: modes}


\begin{table}[htp]
\caption{REQUEST modes. These modes are shared with REJECT.}
\begin{center}
\begin{tabular}{|l|p{13cm}|}
\hline
Name & Content \\
\hline
assist & Any form of exchange, relations, or assistance\\
change & Any changes in policy, government, or institutions that are not concessions \\
yield & Release of prisoners, ending sanctions, easing curfews and boycotts, ceasefires\\
meet & Meetings and negotiations\\
\hline
\end{tabular}
\end{center}
\label{tab:requestmode2}
\end{table}%


\subsection{Quad category: VERBAL CONFLICT}

\newpage


\section{ACCUSE}

\begin{itemize}
	\item Express disapprovals, objections, and complaints; condemn, decry a policy or an action; criticize, defame, denigrate responsible parties.
	\item Accuse, allege, or charge, both judicially and informally
	\item Sue or bring to court
	\item All investigations, including those of historical cases. Examples include investigations of  criminal activity (theft, killing, etc.) and corruption, human rights abuses, war crime, and violations of basic freedoms, military activities such as violations of ceasefire, seizures, and invasions.
\end{itemize}


\subsection{Requires recipient: No}

\subsection{Potential ambiguities}

\begin{itemize}

\item \plcat{ACCUSE} `disapprove' is used for diplomatic protests, as well as delegations presenting a disagreement to an organization or authority, or protests carried out in social media. As noted under \plcat{CONSULT}, summoning an in-country ambassador to present such grievances is just coded  \plcat{ACCUSE}, not  \plcat{CONSULT}

\item Candidates for \plcat{ACCUSE} `allege' + context: ``misinformation" events could also be \plcat{COERCE} `misinformation,' depending on the wording of the relevant text.

\item When an accusation or allegation is also reported alongside a formal conviction, \plcat{ACCUSE} `allege' should not be coded as these are cases where the allegation was proven to be true.

\end{itemize}


\subsection{Supplementary fields: modes}

\begin{table}[htp]
\caption{\plcat{ACCUSE} modes}
\begin{center}
\begin{tabular}{|l|p{13cm}|}
\hline
Name & Content \\
\hline
disapprove & Express disapproval; condemn; complain\\
investigate & Any investigation, including commissions, grand juries, judicial or political\\
allege & Formally or informally accuse; sue, indict, or charge; bring to trial\\
\hline
\end{tabular}
\end{center}
\label{tab:accusemode}
\end{table}%

\subsection{Quad category: VERBAL CONFLICT}

\newpage


\section{REJECT}

All rejections and refusals.

\subsection{Requires recipient: No}

\subsection{Potential ambiguities}

\begin{itemize}
\item Withdrawal of military aid or other assistance is coded as \plcat{SANCTION}.
\item An instance where a country or similar entity bars a group or organization from entering its territory should be coded as \plcat{REJECT} whereas instances where a group or organization is expelled from a country or similar entity should be coded as \plcat{COERCE}.
\end{itemize}

\subsection{Supplementary fields: modes}

\begin{table}[htp]
\caption{\plcat{REJECT} modes. These modes are shared with \plcat{REQUEST}.}
\begin{center}
\begin{tabular}{|l|p{13cm}|}
\hline
Name & Content \\
\hline
assist & Any form of exchange, relations, or assistance\\
change & Any changes in policy, government, or institutions that are not concessions \\
yield & Release of prisoners, ending sanctions, easing curfews and boycotts, ceasefires\\
meet & Meetings and negotiations\\
\hline
\end{tabular}
\end{center}
\label{tab:rejectmode}
\end{table}%


\subsection{Quad category: VERBAL CONFLICT}

\newpage


\section{THREATEN}

All threats, coercive or forceful warnings with serious potential repercussions. Threats are generally verbal acts except for purely symbolic material actions such as having an unarmed group place a flag on some territory.
\subsection{Requires recipient: No}

\subsection{Potential ambiguities}

\begin{itemize}
\item Issuing an in-absentia arrest should be coded as a \plcat{THREAT} `arrest' rather than \plcat{COERCE} `arrest'.
\end{itemize}

\subsection{Supplementary fields: mode}

Note that in \plcat{THREATEN} the mode is the \ti{content} of the threat, rather than how it has been expressed.

\begin{table}[htp]
\caption{THREATEN modes}
\begin{center}
\begin{tabular}{|l|l|}
\hline
Name & Content \\
\hline
restrict & Restrict movement of people or goods---including boycotts, strikes, blockades, and  \\
& curfews---as well as the banning of political activities of particular parties or individuals \\
arrest & Arrest, detain, imprison \\
relations & Threaten to suspend relations or ongoing talks, meetings, or negotiations\\
expel & Expel diplomats, peacekeepers, NGOs \\
territory & Threaten to occupy, seize control of the whole or part of a territory \\
violence & Threaten violence \\
\hline
\end{tabular}
\end{center}
\label{tab:threatmode}
\end{table}%

\subsection{Quad category: VERBAL CONFLICT}

\newpage

\section{PROTEST}

All civilian demonstrations and other collective actions carried out as protests against the recipient: Dissent collectively, publicly show negative feelings or opinions; rally, gather to protest a policy, action, or actor(s).

\subsection{Requires recipient: No}

\subsection{Potential ambiguities}

\begin{itemize}
\item Diplomatic protests, as well as delegations presenting a disagreement to an organization or authority, or protests carried out in social media, are coded as  \plcat{ACCUSE} `disapprove.'  \plcat{PROTEST} presumes significant physical/material activity, not just an expression of opinion.
\item When coding additional events within a text describing a protest, generally the \textit{topic} of the protest---which will typically be a REQUEST---is not coded as a separate event. However, discrete events that are the motivatation for the protest---for example a visit by a foreign dignitary, earlier actions by the police or military, or an earlier arrest---should be coded.
\end{itemize}

\subsection{Supplementary fields:}

\begin{description}
	\item[mode:] Mode of protest: see Table \ref{tab:protestmode}
	\item[event\_loc:] Location[s] of event
\end{description}

%The protest contexts that were included in older versions of this manual were removed in favor of a single set of PLOVER-base context tags. See Section \ref{sec:adding_to_plover} for a discussion of how custom, event-specific context codes can be added.


\begin{table}[htp]
\caption{PROTEST modes}
\begin{center}
\begin{tabular}{|l|p{13cm}|}
\hline
Name & Content \\
\hline
demo & Organized demonstration. Distinct, continuous, and largely peaceful action directed toward
members of a distinct `other' group or government authorities  \\
riot & Violent riot. Distinct, continuous and violent action directed toward members of
a distinct `other' group or government authorities. The participants intend to cause physical injury and/or property damage \\
strike & Members of an organization or union engage in the abandonment of
workplaces, either within specific sectors/industries or across sectors/industries\\
hunger & Hunger strike\\
boycott & The boycott of an activity, person, country, or organization via the withdrawal of commercial or social relations\\
obstruct & Obstruct passage or access to a particular locale \\
vandalize & Damage or destroy property  as a \textit{symbolic} act (for example damaging of artworks) rather destruction incidental to a riot \\
\hline
\end{tabular}
\end{center}
\label{tab:protestmode}
\raggedright{Adapted from Salehyan and Hendix, \textit{Social Conflict Analysis Database} (SCAD)
Version 3.2: \url{https://www.strausscenter.org/images/codebooks/SCAD\_32\_Codebook.pdf}}\\~

\end{table}%

\subsection{Quad category: MATERIAL CONFLICT}

\newpage

\section{SANCTION}

All reductions in existing, routine, or cooperative relations. Note that this is not confined to formal ``sanctions''---\plcat{SANCTION} was just the best word we could find for WEIS and CAMEO's ``REDUCE RELATIONS''


\subsection{Requires recipient: Yes}

\subsection{Potential ambiguities}

\begin{itemize}
\item Convictions that result in imprisonment should also be coded as \plcat{COERCE} `arrest'.
\item Expulsions or deportations of individuals---typically a legal matter---are coded as \plcat{COERCE}.
\item Cancellation of meetings are \plcat{REJECT} and therefore verbal conflict.
\item While reparations or voluntary settlements should be coded as \plcat{AID}, court-ordered payments should be coded as \plcat{SANCTION} events with the winner and court as actor and guilty party as recipient.
\item Refugees or similar actors that are characterized fleeing a country or subnational location should be coded \plcat{SANCTION} `expel' with the causative agent as the actor rather than \plcat{SANCTION} `withdraw' or \plcat{RETREAT} `withdraw' with the actor coded as the fleeing party.
\end{itemize}

\subsection{Supplementary fields: mode}

\begin{table}[htp]
\caption{SANCTION modes}
\begin{center}
\begin{tabular}{|l|p{13cm}|}
\hline
Name & Content \\
\hline
convict &  Find an entity or behavior guilty, unconstitutional, or liable in a court of law or legally constituted tribunal. This includes not only formal convictions but also instances where an entity is discussed as being found guilty and sentenced or sanctioned via court-order, though court sentences that include imprisonment will also receive a \plcat{COERCE} `arrest' mode, (see ambiguities above)\\
expel & Permanently or temporarily expel an entity from a group, organization, political party, or country. Aside from the expulsion of ambassadors or similar diplomats, this mode excludes individual deportations, which are coded as a mode under \plcat{COERCE}\\
withdraw & Withdraw oneself or one's non-military resources (e.g., aid, observers, diplomats, peacekeepers) from a group, mediation activity, organization, or country. This excludes official resignations from an occupation or elected position, which are coded as a mode under \plcat{RETREAT}\\
discontinue & Curtail, decrease, break, or terminate diplomatic, commercial, or material exchanges in manners not specified above. International (political or economic) sanctions are coded as `discontinue', although they can occasionally receive additional \plcat{SANCTION} modes depending on the nature of the sanctions \\
\hline
\end{tabular}
\end{center}
\label{tab:sanctionmode}
\end{table}%

\subsection{Quad category: MATERIAL CONFLICT}

\newpage

\section{MOBILIZE}

All military or police moves that fall short of the actual use of force.

This category is different from \plcat{ASSAULT}, which refers to actual uses of force, while military posturing falls short of actual use of force and is typically a demonstration of military capabilities and readiness. \plcat{MOBILIZE} is also distinct from \plcat{THREAT} in that the latter is typically verbal, and does not involve any activity that is undertaken to demonstrate military power.

\txt{actor} entities  are not necessarily militaries affiliated with states: they can be any organized armed groups (for example militias or gangs).

The \txt{recipient} are entities against whom the \txt{actor} mobilizes its military capabilities in a threatening manner if that is clear, but a group may mobilize with no specific entity stated.

\subsection{Potential ambiguities}

\begin{itemize}
\item Joint military operations are coded as \plcat{COOPERATE} but single-country exercises should be coded as \plcat{MOBILIZE}.
\item Events that involved ``mobilizing supporters to demonstrate" should be coded as \plcat{PROTEST}.
\item If a document reports a \plcat{MOBILIZE} event in the context of an \plcat{ASSAULT}, only the \plcat{ASSAULT} should be coded. For example: ``military units in the area were activated and returned fire on the rebels" should not report a separate \plcat{MOBILIZE} event.
\item Mobilizing police or military forces for disaster relief should be coded as \plcat{AID}.
\item Mobilizing weapons, ships, or vehicles should be coded as \plcat{MOBILIZE} `weapons' rather than \plcat{MOBILIZE} `troops,' unless there's a separate mention of troops being mobilized.
\end{itemize}

\subsection{Requires recipient: No}

\subsection{Supplementary fields: modes }

\begin{table}[htp]
\caption{MOBILIZE modes}
\begin{center}
\begin{tabular}{|l|p{13cm}|}
\hline
Name & Content \\
\hline
troops & Mobilize armed personnel or units\\
weapons & Increase readiness of weapons systems (can occur with a \plcon{cyber} context) \\
police & Mobilize or increase readiness of police or security units\\
militia & Mobilize or increase readiness of any non-state entity with significant military capability\\
\hline
\end{tabular}
\end{center}
\label{tab:mobilizemode}
Adapted from CAMEO cue category 15
\end{table}


\subsection{Quad category: MATERIAL CONFLICT}

\newpage

\section{COERCE}

Repression, restrictions on rights, or coercive uses of power falling short of violence.

\subsection{Requires recipient: No}

Most cases of \plcat{COERCE} have a clear intended \txt{recipient}, but occasionally, for example in shutting off internet access, the entities intended to be affected by the action are so broad as to be unclear.

\subsection{Potential ambiguities}

\begin{itemize}
\item Candidates for \plcat{COERCE} `misinformation' could also be \plcat{ACCUSE} `allege' $+$ context: ``misinformation'' events, depending on the wording of the relevant text.
\item Combatants captured during conflict should be coded as \plcat{ASSAULT} `abduct' rather than \plcat{COERCE} `arrest.'
\item The ``cyber'' and ``misinformation'' modes both have corresponding contexts with the same name. The modes capture specific instances of ``cyber'' or ``misinformation'' actions, e.g. a report of a website denial of service attack or a social media disinformation campaign. The contexts are broader, and also capture other actions related to ``cyber'' or ``misinformation'' events, like for example the arrest of a person for hacking or cybercrime, or a threat by the recipient of a misinformation campaign to the responsible actor to cease it.
\item State of emergencies in relation to national disasters should generally not be coded as \plcat{COERCE} `restrict' absent evidence for their use as a repressive tactic.
\item Issuing an in-absentia arrest should be coded as a \plcat{THREAT} `arrest' rather than \plcat{COERCE} `arrest'.
\item An instance where a country or similar entity bars a group or organization from entering its territory should be coded as \plcat{REJECT} whereas instances where a group or organization is expelled from a country or similar entity should be coded as \plcat{COERCE}.
\end{itemize}

\subsection{Supplementary fields: }

\begin{table}[htp]
\caption{COERCE modes}
\begin{center}
\begin{tabular}{|p{.21\textwidth}|L{.73\textwidth}|}
\hline
Name & Content \\
\hline
seize & Execute search, confiscate property, raid \\
restrict & Impose restrictions on political freedoms or movement, including cordoning off areas and the banning of individuals or organizations from political life \\
censor & Censor, ban or restrict access to publications or other information  \\
curfew & Impose curfew \\
martial-law & Impose state of emergency or martial law \\
arrest & Arrest, detain  \\
deport & Expel or deport individuals \\
withhold & Withhold public goods/services, e.g. shut off power/internet/water/ utilities or withhold food/medical supplies \\
misinformation & deception/manipulation/misinformation (will also automatically add ``misinformation'' context) \\
cyber & cyber attacks and crime, including hacking, security breaches, website attacks, etc. (will also automatically add ``cyber'' context) \\
\hline
\end{tabular}
\end{center}
\label{tab:coerce}
Adapted from CAMEO cue category 17
\end{table}%


\subsection{Quad category: MATERIAL CONFLICT}

\newpage


\section{ASSAULT}

\plcat{ASSAULT} events are deliberate actions which can potentially result in substantial physical harm.

\subsection{Requires recipient: No}

In \plcat{ASSAULT} events where the violence is two-sided, all participants are coded in the \txt{actor} field except when a ``Side A/Side B'' can be distinguished per the conventions of the Correlates of War project, in which case the \plmod{sideAB} mode is added to any other relevant modes. In one-sided violence, the perpetrator is coded as the \txt{actor} and the victim as the \txt{recipient}.

% AH: I think the sideAB thing is confusing. I'm not sure how it's different from the distinction we get from two actors vs. actor and recipient.

\subsection{Potential ambiguities}
\begin{itemize}
\item General or ambiguous mentions of beatings/assaults without any mention of specific tools or methods only receive the \plcat{ASSAULT} `beat' mode.

\item Mentions of beatings/assaults that use fists, kicks, punches, and similar methods also only receive the  \plcat{ASSAULT} `beat' mode.

\item Mentions of beatings/assualts that use blunt instruments such as bats, clubs, and so on receive both \plcat{ASSAULT}  `beat' and  \plcat{ASSAULT} `primitive' modes.
\item Mentions of assaults, murders, or clashes that involve knives, machetes, fire, rocks and similar instruments only receive the  \plcat{ASSAULT} ``primitive'' mode.
\item Usage of \plcat{ASSAULT} `crowd-control' should be reserved for instances where there is an explicit mention of a crowd control weapon or tactic. Cases that discuss more ambiguous interactions such as ``police pushed back protesters'' would be coded as \plcat{RESTRICT}.
\item Combatants captured during conflict should be coded as \plcat{ASSAULT} `abduct' rather than \plcat{COERCE} `arrest.'
\item Incidental damage to houses/property should not automatically be coded as \plcat{ASSAULT} `destroy.' \plcat{ASSAULT} `destroy' should be used either as a residual mode when the method or weapon of \plcat{ASSAULT} is unknown but property or infrastructure is destroyed, or when destruction is the intention of the \plcat{ASSAULT} (e.g., the bombing energy infrastructure; demolition of housing settlements).
\end{itemize}
\subsection{Supplementary fields:}


\begin{table}[htp]
\caption{ASSAULT modes}
\begin{center}
\begin{tabular}{|p{.18\textwidth}|p{.76\textwidth}|}
\hline
Name & Content \\
\hline
abduct & Abduct, kidnap, hijack \\
beat & Physically assault by striking individuals or groups with one-off or repeated blows, typically administered manually or by blunt instrument\\
torture & Torture \\
%execute & Judicially-sanctioned execution \\
sexual & Sexual violence\\
targeted & Targeted killings, including (successful and attempted) assassinations and executions, as well as deliberate mass killings of defenseless actors \\
destroy & Intentional destruction of property \\
primitive & Primitive weapons: fire, edged weapons, rocks, farm implements \\
firearms & Rifles, pistols, light machine guns\\
explosives & Any explosive not incorporated in a heavy weapon: mines, IEDS, car bombs \\
suicide-attack & Individual and vehicular suicide attacks \\
aerial & Manned aerial vehicles, e.g. aircraft, helicopters \\
drone & Unmanned aerial vehicles (UAVs), drones \\
heavy-weapons & Artillery, rocket launchers, armored vehicles, tanks, and similar weapons \\
crowd-control & Weapons and tactics intended to be less lethal crowd control, including tear gas, water cannons, firing weapons in the air, lathi charges, etc. \\
%cleansing & Mass expulsions or deportations, ethnic cleansing  \\
%massacre & Instances of mass killing or massacres  \\
unconventional & Chemical, biological, radiation, and nuclear weapons  \\
%sideAB & Two-sided violence: \txt{actor} and \txt{recipient} are ``Side A'' and ``Side B'' \\
\hline
\end{tabular}
\end{center}
\label{tab:violmode}
\raggedright{Adapted from Political Instability Task Force Atrocities Database: \url{http://eventdata.parusanalytics.com/data.dir/atrocities.html}}.
\end{table}%

\begin{description}
	\item[mode:] Mode of violence: see Table \ref{tab:violmode}
	%\item[dead:]  number killed (integer or code)
	%\item[injured:] number injured (integer or code)
	%\item[size:] used when total casualties are reported, combining dead and wounded
	\item[event\_loc:] Location of event
\end{description}


\subsection{Quad category: MATERIAL CONFLICT}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Contexts}\label{chapter:contexts}

Additional details for the general context tags.

\section{Military}\label{context:military}

Discussions of the military or armed forces, including navy, army, marines, air force, and similar military branches. This includes not only discussions of active military operations, but also broader discussions of civil-military relations, military assistance, military culture, and military expenditures. However, this context field only pertains to state militaries. As such, discussions of government-aligned militias, domestic law enforcement, and armed non-state actors (e.g., rebel groups) should not be coded in this context category.


\section{Intelligence}\label{context:intelligence}

The covert gathering of information by state intelligence organizations, including through tactics of espionage, overhead reconnaissance, and communications interception. Accusations and suspicions of covert intelligence gathering, as well as more general discussions of state intelligence organizations, should also be coded. However, this context field excludes (1) discussions of the use of clandestine methods to spread misinformation or influence operations, which should be coded under the `misinformation' context category and (2) discussions of artificial intelligence that are unrelated to state intelligence organizations' intelligence gathering activities.

\section{Executive}\label{context:executive}

Politics and interactions involving the executive branch, the prime minister, or the non-elected executive of a country. This can include discussions of background context on (e.g.,) an executive's legal challenges, corruption concerns, family, or lifestyle. This context field should also code discussions of executive-branch rivalries or interactions, including instances where an executive or dictator chooses to appoint, demote, or remove a representative from their cabinet, inner circle, or a bureaucratic agency under their purview. Executive relations with other institutions (e.g., foreign heads of state, legislatures, judiciaries, or the military) should generally be coded as `executive', but will also often receive additional context tags. Two areas that aren't typically coded for the `executive' context are very routine mentions/interactions involving executives and discussions of past executives.

\section{Legislative}\label{context:legislative}

All regular and irregular legislative (or parliamentary) politics and interactions. This includes discussions of individual legislative representatives, legislative debates, legislative lawmaking, parliamentary coalition formation, corruption in the legislature, legislative oversight, legislative campaigns and elections. Legislative relations with other institutions (e.g., foreign heads of state, executives, judiciaries, or the military) should generally be coded as `legislative', but will also often receive additional context tags. Discussions of legislatures or parliaments within authoritarian countries should still be coded under `legislative'.

\section{Election}\label{context:election}
Discussions of elections and political campaigns. This context field includes not only details on specific elections, campaigns, and electoral candidates, but also discussions of domestic and international election monitors. Discussions of concerns over whether elections are free and fair should also be coded as `elections', in addition (depending on the context) to `rights\_freedoms' and either `pro\_democracy' or `pro\_autocracy'. Campaign fundraising, election debates, charges of electoral fraud, and discussions of voting in (or polling for) an upcoming election should also be coded as 'election'.

\section{Political Institutions}\label{context:political-institutions}

Changes in the functioning of formal political institutions and parties in a country, including non-routine interactions between different bodies of government, or with political parties. This context should capture all significant changes, regardless of the direction the changes produce, i.e., whether they move the nature of government towards more democratic or more authoritarian. Instead, the latter should be reflected with additional `pro\_democracy' or `pro\_autocracy' contexts.

The `political\_institutions' context works together with the  `pro\_democracy' and    `pro\_autocracy' contexts to capture the broader concepts of democratic backsliding, autocratization, as well as democratization.

\begin{itemize}
\item Includes substantive (legal or illegal) constitutional changes that a clearly motivated to either improve or harm political competition or checks on executive authority, e.g. voting rights strengthening or weakening.
\item Can include pseudo-democratic bodies that function under constraints, e.g. in Russia or Iran, not only very democratic countries.
\item Excludes routine interactions without broader implications for the state of democracy or functioning of major formal institutions in a country.
\item Can include events that describe extra-systemic steps by major actors (institutions), e.g. autocoups or declarations of states of emergency as a means to resolve political or institutional conflict (Tunisia 2021).
\item Includes violations of norms regarding appointments, dismissals, pardons, interactions or relationships between parts of government (Boris Johnson UK family appointments to House of Lords in 2021).
\end{itemize}

\section{Pro-democracy}\label{context:pro-democracy}

Includes processes and initiatives associated with democratization, including actions taken to promote democracy by domestic or international actors. These processes, actions, or initiatives can be gradual or abrupt, and can include, for example, 1) commitments by governments to hold free and fair elections, 2) commitments to enact, follow, or reinforce democratic institutions, or 3) the provision of verbal or material support to pro-democracy actors.

\section{Pro-autocracy}\label{context:pro-autocracy}

Includes processes and initiatives associated with authoritarian consolidation, autocratization, de-democratization, or democratic backsliding, including actions taken to undermine democracy by domestic or international actors. These processes, actions, and initiatives can be gradual or abrupt, and can include, for example, 1) efforts to dissolve or undermine democratic institutions or norms by government officials, 2) the cancellation or suspension of elections, 3) coups, or 4) refusals to step down from power when mandated to do so by existing democratic institutions.


\section{Economic}\label{context:economic}

Coverage of international and domestic economic issues, including but not limited to trade, finance, economic development, economic stability, economic crises, inflation, unemployment, GDP, and business-government relations in areas of political or economic concern (e.g., a government accusing a company of monopolistic practices, or a government expropriating a company's assets). Political interactions that focus on economic outcomes (such as diplomatic negotiations over a future trade agreement) should also be coded as `economic' (in addition to other context fields, depending on the specific context). Business news coverage should not be coded as having an `economic' context unless that business news is discussed in light of a broader economic issue or concern. This means that news reports that solely discuss company annual reports, acquisitions, and similarly mundane business activities should not automatically be coded as `economic.'


\section{Legal}\label{context:legal}

Discussions of activities and responsibilities associated with domestic or international courts and judiciaries; discussions of national and international laws; or discussions of associated professions (e.g., lawyers). Negotiations over international law should be coded under this context field. Common international legal activities that should be coded under this category would be International Criminal Court investigations, international tribunals, maritime law, the Geneva Convention, the World Trade Organization, and similar conventions on the use of chemical and biological weapons. Domestically, this context field should code discussions of (e.g.) legal proceedings against politicians, the role of the courts in society or politics, or judicial oversight. However, discussions of domestic or international crime events should not automatically be coded as `legal' unless detailed discussion of associated laws or court processes is included.

\section{Reparations}\label{context:reparations}

Monetary or non-monetary payments to compensate victims, groups, or family members for past harms inflicted---typically by a national or foreign government. Discussions where such reparations are simply promised or demanded should also be coded under this context field. Reparations may be made in the contexts of post-conflict justice, but not all post-conflict justice activities should be coded as reparations. Examples of non-monetary reparations include verbal or formal acknowledgments or apologies of past government transgressions or formal pardons of previously convicted persons that are made with explicit reference to reparations.



\section{Human Rights}\label{context:hr}

General discussions of human rights and human rights violations. This context field is intended to capture human rights contexts that may lack details concerning specific human rights violations. As such, this field will apply in most instances where the term human rights appears, and especially so when human rights is discussed in an unspecified manner. Examples of such discussions would be articles outlining 1) the global human rights regime, 2) human rights organizations and their activities (e.g., Amnesty International), 3) international meetings/treaties/negotiations over human rights, or 4) an international organization or actor's efforts to combat human rights abuse in a general sense.

\section{Rights Freedoms}\label{context:rightsfree}

Discussions of specific political rights and freedoms or their violation. This can include actual discussions of such freedoms or violations, as well as discussions of specific laws, monitoring organizations, or protests associated with these freedoms/violations. Included here should be freedom of (foreign and domestic) movement, freedom of speech, freedom of assembly, civil liberties, electoral self-determination, freedom of the press, freedom of religion, worker's rights, and women's rights. Note that this field will often receive joint codings with `human\_rights', `gender', `lbgt', `asylum', `migration', `pro\_democracy' and/or `pro\_autocracy' depending on the specific `rights\_freedoms' context.

\section{Repression}\label{context:repression}

The use of force by security forces to control individuals or groups. The latter individuals or groups will typically be unarmed and include (e.g.) individual citizens, social or ethnic groups, societies on the whole, businesses, journalists, or NGOs. The use of force against rebels should be excluded from `repression' as it denotes civil war or civil conflict rather than repression. The use of force against alleged criminals, terrorists, gangs, or associated groups should only be coded as `repression' when (i) the use of force is characterized as excessive or illegal and/or (ii) the criminal- or terrorist-identity of the recipient is disputed. Security forces (i.e., the actors initiating repression) are usually state-based (e.g., the army, police, or secret police) or state-affiliated (e.g., pro-government militias, paramilitaries, or death squads), but can occasional be comprised of non-state armed forces (if the latter forces control a particular territory or region). Specific examples of repression include disappearances, extrajudicial killings \& punishment, political imprisonments, the use of excessive force, forced displacements, and torture. As such, stories receiving a `repression' context coding will often also have a `human\_rights' and/or `rights\_freedoms' context coding.

\section{Human Security}\label{context:human-sec}

The protection of individual, group, and societal access to water, food, housing, energy, and land/property tenure. Discussions of `human\_security' along each of these dimensions should generally make a linkage to access; whereas (e.g.,) discussions of a drought without any mention of its human/social implications should generally only be coded as `disaster'. Mentions of ``food (in)security'' or ``water (in)security'' should generally be coded as `human\_security'. Likewise, the `human\_security' context field should include not only instances where a direct threat to human security arises, but also discussions of (potential) vulnerabilities to such insecurities, and domestic or international efforts to address such vulnerabilities (e.g., the United Nations Development Programme).

\section{Gender}\label{context:gender}

Discussions of gender, women's issues, gender equality, women's rights, reproductive rights, and women in politics. Discussions of gender-based discrimination (or femicide), as well as laws developed both for and against gender-based discrimination, should also be coded. Discussions of gender-oriented organizations, groups, or protests should likewise be coded as `gender.'

\section{LGBT}\label{context:lgbt}

Discussions of lesbian, gay, bisexual, transgender, queer, intersex or asexual groups, movements, or individuals. LGBTQIA discrimination and associated laws should be coded under `lgbt'. Discussions of LGBTQIA-oriented organizations, advocacy, or protests should also be coded as `lgbt.'

\section{Religion Ethnicity}\label{context:religethno}
General or specific discussions of religions, ethnicities, castes, or linguistic groups. In addition to general discussions of religion, ethnicity, caste, or language, this can include discussions of discrimination (or violence) against particular ethnic, religious, caste, or linguistic groups; or instances of discrimination (or violence) perpetrated by particular ethnic, religious, caste, or linguistic groups. In addition, this context fields should also code more cooperative interactions among ethnic, religious, caste, or linguistic groups, as well as instances where such groups play a major role in politics, advocacy, reparations, or protest.

\section{Inequality}\label{context:inequality}
Discussions of inequality in a general sense, as well as discussions of more specific forms of inequality such as economic inequality, gender inequality, racial inequality, and social inequality. The latter forms of inequality can encompass (e.g.) the uneven distribution of income or wealth in a society, policies that exclude certain groups from political participation, as well as unequal access to education, healthcare, or government services. Discussions of societal discrimination---such as gender-based, ethnic-based, religion-based, race-based, or age-based discrimination---should also be coded as `inequality.' Accordingly, many `inequality' stories will often also receive context codings for `lgbt', `gender', or `religion\_ethnicity.' Lastly, note that `inequality' can include discussions of not only (within-country) societal inequality, but also global or cross-country inequality.

\section{Diplomatic}\label{context:diplomatic}

Formal diplomatic relations, negotiations, and interactions between nation-states or between actors within particular nation-states. This includes bilateral diplomatic institutions and actors such as embassies, consulates, charge d'affaires and ambassadors, and the services that they provide. This context field also includes formal diplomatic negotiations between diplomatic representatives of nation-states and non-state actors (e.g., rebel organizations) over topics such as treaties, agreements, or alliances. Discussions of countries' ministries of foreign affairs (e.g., the State Department in the U.S.) or their ministers/secretaries should also be coded under this context field.


\section{Territory}\label{context:territory}

Discussions of territory in a political context. This can pertain to protests or rebellions over territorial autonomy, independence, or succession. This context field should also include discussions of territorial disputes (including border disputes) between nation-states as well as international treaties and/or mediation developed to address these disputes. Discussions of territorial displacement of certain groups by government and non-governmental actors should also be coded as `territory', as should discussions of territorial sovereignty. However, general mentions of land or geography should not be coded as `territory' if those mentions do not include a clear political dimension.

\section{Peacekeeping}\label{context:peacekeeping}

Activities involving the monitoring or maintaining of ongoing peace-processes, typically in the aftermath of an international or domestic armed conflict. Such activities most commonly involve international observers drawn from multilateral operations directed by (e.g.,) the United Nations, NATO, or European Union; but may at times also be drawn from individual nation-states. Peacekeeping can include the active stationing of international forces in a post-conflict area, such as is commonly the case with UN Peacekeepers (i.e., Blue Helmets), as well as multilateral non-military assistance for activities such as peace agreement implementation, post-conflict power-sharing, and confidence building measures.




\section{Health}\label{context:health}

Issues and institutions related to public health, disease outbreaks and epidemics, disease in general. This context field should include both actual instances of health crises and disease outbreaks and efforts to improve public health and disease preparedness. Discussions of healthcare systems or key domestic and international public health institutions (e.g., the WHO) should be coded as `health'. However, this context field should not be used for reports of individual accidents and accidental deaths, such as those arising from (e.g.) traffic accidents or skiing accidents.

\section{Asylum}\label{context:asylum}

The granting or pursuit of national or political asylum. Such asylum is often pursued by, and provided to, political refugees. Discussions of asylum seekers, as well as national or international national asylum treaties or institutions, should also be coded under this context field. However, general discussions of refugees should not automatically be coded as `asylum' unless some reference to asylum is made.


\section{Migration}\label{context:migration}

Discussions of international or domestic migration, as well as discussions of the direct drivers or consequences of migration. This context field accordingly includes discussions of immigration and emigration, forced displacement, internally-displaced persons, international organizations seeking to manage migration, and refugees. Discussions of migrant activities or challenges should also be coded under `migration', and would include themes such as discrimination against migrant communities, migrant remittances, and policies or laws focusing upon (e.g.) migrant pathways to citizenship or immigration.

\section{Disasters}\label{context:disasters}

Discussions of slow and rapid onset natural disasters such as droughts, hurricanes, cyclones, earthquakes, flooding, landslides, and heat waves. This context field should code news stories related not only to the disasters themselves, but also their effects on social outcomes such as migration. Accidents (e.g., chemical plant explosions) and oil or chemical spills should also be coded under this context field.



\section{Natural Resource}\label{context:natural-resource}

Discussions of natural resource extraction, management, disputes, depletion, consumption, pricing, and trade. Environmental concerns over natural resources should also be coded as `natural\_resource', in addition to as `environment'. Common types of natural resources are minerals, rare-earth metals, fossil fuels (e.g., oil, gas, and coal), agriculture, forests/lumber, diamonds, sand, and water.



\section{Environment}\label{context:environment}

Environmental problems \& solutions, environmental politics, and environmental activism. Regarding environmental problems, this context field should code environmental disasters as well as broader environmental problems or concerns such as general mentions of pollution, climate change, water stress, deforestation, or soil degradation. Environmental solutions encompass policies and technologies designed to address environmental problems, such as renewable energies or the UN Framework Convention on Climate Change. Environmental politics encompasses any (ir)regular political processes associated with environmental policymaking, lobbying, negotiation, regulation, or cooperation at the international or domestic levels. Environmental activism includes not only environmental protest and direct actions, but also broader efforts towards the conservation or preservation of particular lands or animal species, as well as discussions of specific domestic and transnational environmental advocacy organizations.



\section{Technology}\label{context:tech}
Discussions of technological development, technological innovation, new technologies, or high-tech industry. Examples of high-tech industries include those based in aerospace, semiconductors, nuclear energy, electronics, and quantum computing. Note that this context field can thereby include military technologies, cyber security technologies, and misinformation technologies, meaning that many articles with this context will likely receive multiple other context tags. National policies and international agreements designed to harmonize or foster technologies (or their future development) should also be coded as 'technology'.



\section{Terrorism}\label{context:terrorism}

Events related to terrorist groups, terrorist actions, terrorist funding, or terrorist sponsors; as well as anti-terrorism activities and policies. Terrorism is defined as any activity that aims to harm, kill, or kidnap civilians or unarmed government employees in an effort to intimidate, coerce, and/or provoke fear in societies, governments, or groups therein. This context should ideally be reserved for instances where actual terrorism is discussed, as opposed to instances where a government actor more questionably labels an opposing actor as a `terrorist' for political or strategic purposes.

\section{CBRN}\label{context:cbrn}

Discussions of chemical, biological, radiological and nuclear security defense. This context field should code all discussions related to chemical, biological, radiological, or nuclear weapons or attacks, as well as discussions of security or preparedness for such attacks. Discussions of the development of such weapons or capabilities, or suspicions of such development, should be coded. International organizations or treaties designed to oversee or prevent such weapons or attacks should also be coded under this context field. However, general discussions of (e.g.,) nuclear energy or nuclear disasters should not be coded under this context field, and should instead be coded under the `environment' and/or `disaster' context fields depending on the circumstances.

\section{Cyber}\label{context:cyber}
Discussions of cyber attacks, cyber security, cyber warfare and cyber crime. This context field should include any discussions of actual cyber crime/warfare events, as well as suspicions or allegations of those events. Discussions of laws, organizations, or initiatives designed to combat these threats (via cyber security or otherwise) should also be coded as `cyber'. Cyber terrorism should be coded as `cyber', but will also typically receive a 'terrorism' context coding. Electronic or information warfare will often receive a `cyber' context tag, as well as a 'misinformation' context tag.


\section{Misinformation}\label{context:misinfo}
Discussions of misinformation, disinformation influence operations, or fake news; as well as national and international efforts to combat these tactics. Allegations or suspicions of misinformation and related forms of information operations/warfare should be coded as `misinformation.' Note however that this context field pertains to news stories that discuss the use of (or activities related to) misinformation-type tactics, as opposed to whether or not the news story being coded is itself likely to be misinformation.



\section{Crime}\label{context:crime}

Discussions of (international or domestic) criminal activities, as well as discussions of the perpetration of specific crimes, criminal convictions, or criminals themselves. General discussions of transnational or domestic criminal organizations (e.g., the mafia) or high profile criminal fugitives should also be coded under    `crime.' International coordination and cooperation to craft, enact, or enforce laws against criminal actions should also be coded under this context field. Note that several additional context fields---such as  `trafficking,'  `corruption,' and `illegal\_drugs'---code more specific criminal actions. When these are coded, `crime' should typically not also be coded. the one exception is in the case of `cyber,' where the addition of a `crime' context allows one to distinguish between cyber-crimes and government-directed cyber actions. War crimes should generally be excluded from this context field, and coded instead under `human\_rights' or `rights\_freedoms' depending on the specific context.

\section{Corruption}\label{context:corruption}
Instances of political, legal, and business corruption. This can include allegations or suspicions of such corruption. Coded forms of corruption for this context field include (e.g.) misuse/abuse of public office for personal (private) gain, extortion, embezzlement, bribery, cronyism, nepotism, and insider trading. The passage, enforcement, or development of international or domestic anti-corruption laws should also be coded as `corruption'. However, the abuse of government power via tactics of repression or police brutality should not be coded as 'corruption', and should instead be coded as `human\_rights' `pro\_autocracy,'   `rights\_freedoms,' and/or `elections' depending on the specific context.

\section{Illegal Drugs}\label{context:drugs}
The criminal possession, distribution, sale, or manufacturing of illegal drugs. International meetings and treaties concerning efforts to combat illegal drug use, production, or transport should also be coded as `illegal\_drugs.' Discussions of criminal organizations with mention of their involvement in the drug trade or drug cartels should also be coded. Discussions or implementations of the legalization of illegal drugs by governments should also be coded as `illegal\_drugs' as should discussions of the use of drug profits for funding by rebel or terrorist organizations.

\section{Trafficking}\label{context:trafficking}
The domestic or international trafficking or smuggling of illicit goods. This includes international trafficking in (e.g.,) illegal drugs, diamonds and gemstones, gasoline, cigarettes, antiquities, lumber, humans, weapons, or wildlife; as well as the smuggling or sale of such goods across subnational political boundaries to evade specific taxes or regulations. In addition to active discussions of trafficking itself, any discussions of law enforcement efforts to disrupt trafficking should be coded as `trafficking.' Similarly, discussions of any international laws, meetings, or organizations designed to combat trafficking should be coded as  `trafficking.' Finally, discussions of negative outcomes that are directly tied to trafficking within sending and receiving states (e.g., deforestation or increases in prostitution) should likewise be coded under this context field.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Country Names and Sector Codes}

CAMEO employed a hierarchical entity coding structure based on 3-character coding elements which allowed nearly unlimited complexity and, depending on the exact coding system, could be resolved down to the identity of individual groups or individuals. As with the event codes, typically only the first two or three of these elements were used. ICEWS modified this somewhat, while preserving most of the sub-state differentiations as ``sectors''---the terminology we've adopted here over the CAMEO/IDEA ``agents'' terminology---but also provided a very substantial amount of complexity at the sub-sector level.

As with the events, PLOVER seeks to pare this down to the most commonly used countries and sectors, while retaining the possibility of more specific information. In place of the pages of entity and agent specifications found in the CAMEO manual, PLOVER has four rules:

\begin{enumerate}
\item The country name---for both an event's \texttt{actor} and \texttt{recipient}---is either a country designation for independent states, an entity designation for a very small number of non-independent territories, or a standardized identifier for international non-state actors such as intergovernmental organizations; see Table \ref{tab:nonstate} below.
\item The sector code is a 3-character code that best describes an \texttt{actor/recipient} role. The primary role is provided in an initial field for each \texttt{actor/recipient}. Any other applicable sector codes are listed in a secondary field.
\item Identifiers for individual persons or organizations are coded in the \texttt{identifier\_id} and/or \texttt{identifier\_text} fields. For many instances, this takes the form of a Wikidata ID with its corresponding text matching the canonical English-language name of the Wikidata entry. Including this information greatly helps researchers who want to (1) track a particular organization or person, (2) need to make fine-grained distinctions that are currently subsumed within a single code (USA MIL = Army + Navy + Air Force + ... and USA GOV = the president + the State Department + the attorney general of Oklahoma + the city of Cambridge + ...) and (3) assign different sector codes using the raw information provided by Wikidata/Wikipedia (e.g., a new sector category for right-wing populist parties and politicians).
\item Depending on PLOVER implementation, the remaining named fields in the \txt{actor/recipient} JSON object are used for additional information beyond what can be coded in the sector secondary modifier. In other words, one item of information---typically it is religion, ethnicity, or position---can be coded in the tertiary code, but only one: this handles virtually all of the current use-cases we know of such as religion, ethnicity, official position, etc.
\end{enumerate}

By effectively crowdsourcing details to Wikipedia/Wikidata, the latter which is generally updated very quickly, often within minutes in the case of a death of a well-known figure, we deal with a major weak point in the CAMEO dictionary approach:  the need to maintain coding teams to regularly update dictionaries, and in the absence of this, having information sometimes years out of date. Wikipedia/Wikidata also has a fairly standardized format for biographical information which contains far more detail than a CAMEO entry, but can be parsed with relatively simple programs.

An example \txt{actor} block is below:

\begin{verbatim}
	{
	 "raw_text": "Steinmeier",
	 "entity_name": "Frank-Walter Steinmeier",
	 "wikidata_id": "Q76658",
	 "wiki_description": "Minister of Foreign Affairs",
	 "country_name": "Germany",
	 "sector_code": "GOV",
	 "other_sector_codes": ""
	 }
\end{verbatim}

While the process of generating this block will depend on the specific nature of the coder, in general, the coder will (1) identify an  \txt{actor} or \txt{recipient} in the text, in this case, ``Steinmeier". (2) Using the context of the article, resolve the mention to its Wikipedia page and ID and report the Wikipedia role or description. (3) Using the information on the page, determine that Frank-Walter Steinmeier was the German Minister of Foreign Affairs and thus GOV.

\section{Country names}

The \texttt{actor/recipient} country name fields identify the country or other non-state international actor with which an \texttt{actor} or \texttt{recipient} is associated. These can be identified with a full name (the default), or optionally abbreviated 3-letter codes, e.g.\ ``Germany" or ``DEU." Presently, actors and/or recipients that a given news report only implies to be a regional or global construct (e.g., ``The West,'' ``Latin America,'' or ``The Developing World'') do not receive a country name and any corresponding event(s) involving such entities are not coded.  Altogether, the \texttt{actor/recipient} country name fields consist of three groups of entities:

\begin{enumerate}
\item Independent states according to the Correlates of War (COW) state system membership list.\footnote{We include the Holy See in this group, even though it is not in the COW list.} In these instances, reported names and short codes are based on the ISO 3166 English short names and 3-letter codes, not COW names and codes. Aside from the exceptions mentioned next, all dependencies such as the \AA land Islands or the Pitcairn Islands are (re)assigned to the country name of their controlling state.
\item A small number of non-independent territories and dependencies, by exception: Antarctica, Hong Kong\footnote{To obtain all events in China, one thus would need to select events both in ``China" and ``Hong Kong".}, and Palestine. Note that one US-recognized independent country, Kosovo, also has its own country name entry. It does not have an ISO code; we use ``KOS".
\item A small number of international non-state entities, like the UN or NGOs, listed in Table \ref{tab:nonstate}.
\end{enumerate}

The following subsections provide additional clarifications related to the way different countries and territories are handled.

\subsection{Non-state international actors}

Table \ref{tab:nonstate} presents the seven international non-state entities that are also included in the country names field. With the exception of the UN and EU, the special codes in Table \ref{tab:nonstate} are intentionally broad and generic. The application of ``international governmental organization'' excludes the ``United Nations'' and ``European Union.'' The latter two cases were separated from ``international governmental organization'' because they are (a) fairly common, and (b) the largest and arguably among the most institutionalized IGOs.

\begin{table}[htp]
\caption{International Non-state actor names}
\begin{center}
\begin{tabular}{|l|l|}
\hline
Code & Name \\
\hline
IGO   &   International Governmental Organization \\
UNO & United Nations \\
EUR & European Union \\
NGO &   Non-governmental Organization\\
ISM           &   International Social Movement\\
IMG            &   Transnational Militarized Group\\
MNC            &   Multi-national Corporation\\
\hline
\end{tabular}
\end{center}
\label{tab:nonstate}
\end{table}%

\subsection{Non-independent territories with a separate ISO code}

There are 59 dependencies and other non-independent or only partially independent entities that have an ISO 3166 code but are (1) not independent state actors in the COW state system membership list nor (2) appear on the exceptions listed under item 2 above. Examples include the Falkland Islands, Puerto Rico, and French Guiana. Those are folded into their associated controlling state, e.g., \texttt{actors/recipients} and events in the Falkland Islands are associated with the United Kingdom, etc.

Events arising in specific dependencies can still be recovered through the use of PLOVER's geolocation fields when those events contain a sufficiently precise geolocation.

\subsection{Partially recognized (disputed) entities}\label{partially-recognized-entities}

There are several disputed territories which are not recognized by the US that receive special handling, like the Transnistria region in Moldovia. They are treated as follows:

\begin{itemize}
\item Instead of a separate country name and code, they are associated with the nominally sovereign country that claims control over that territory. As such, for example, Transnistria would be treated as part of Moldovia, not a separate country.
\item However, they receive a special ``PRE: partially recognized entity'' \textit{sector} tag, in addition to whatever other sector tags they would receive. Thus an event involving the Transnistrian breakaway government would receive as country name ``Moldovia'', but the sector tags would include in ``PRE'' in addition to (in this instance) the ``GOV'' code.
\end{itemize}

Presently the list of such cases (with the country they are associated with) is: Abkhazia (Georgia), Luhansk People's Republic (Ukraine), Donetsk People's Republic (Ukraine), Nagorno-Karabakh (Azerbaijan), Northern Cyprus (Cyprus), Transnistria (Moldovia), Somaliland (Somalia), South Ossetia (Georgia), and Western Sahara (Morocco).


\clearpage
\newpage

\section{Sector Codes}

Sector codes are 3-letter codes that identify the broad societal/organizational sector that an \texttt{actor} or \texttt{recipient} is associated with. They provide a more fine-grained categorization of \texttt{actors/recipients} than just their country, and should thus be especially useful for analyzing patterns in domestic, not international, events.

\begin{center}
\begin{longtable}{|l|p{13cm}|}
\caption{Sector Codes}
\label{tab:roles}
 \\ \cline{1-2}
  \textbf{Code} & \textbf{Frequently used codes}\\
  \hline
	  COP & Police forces, officers, criminal investigative units, protective agencies \\
      GOV & Government: the executive, governing parties, coalitions partners, executive divisions \\
	  JUD & Judiciary: judges, courts \\
	  LEG & Legislature: parliaments, assemblies, lawmakers \\
	  MIL & Military: troops, soldiers, all state-military personnel/equipment\\
	  PRM & Paramilitary organizations not in opposition to government\\
	  PTY & Political parties (see Note 1) \\
	  REB & Rebels: armed opposition groups or individuals (see Note 3)\\
	  SPY & State intelligence services as well intelligence operatives or assets \\
	  UAF & Unidentified armed forces (``unknown gunmen'') \\
	  UNK & Generic unidentified actors (e.g. actor for ``two civilians were killed by a bomb'') \\
  \hline
~   & \textbf{Less frequently used codes}\\
 \hline
 	  AGR & formally or informally organized agricultural labor; peasants \\
      BUS & business: individuals companies, and enterprises, not including MNCs \\
      CRM & individual criminals and criminal gangs \\
	  CVL & civilians, protesters, activists, and other unarmed domestic entities that lack affiliation with the organized groups that appear within the sectors presented above and below  \\
	  EDU & educators, schools, students, or organizations dealing with education \\
      ELI & former government officials who currently do not hold positions in the government or armed forces, including exiled/ousted officials as well as family members of (former) government officials\\
      JRN & journalists, newspapers, radio, television, web sites (see Note 4)  \\
      LAB & formally or informally organized labor in services or manufacturing \\
	  MED & individuals and organizations dealing with health (see Note 4) \\
	  REF & refugees and internally displaced persons \\
	  OPP & political opposition: opposition parties, individuals, anti-government activists; typically assigned as a secondary code \\
      PRE & partially recognized entities, such as breakaway regions, partially recognized states, or disputed territories (see \autoref{partially-recognized-entities} and Note 2)  \\
	  REL & religious organizations and institutions \\
	  SOC & any organization or movement that is considered part of ``civil society''  not otherwise covered above\\
  \hline
\end{longtable}
\end{center}

\subsection{Sector code notes}

\begin{enumerate}
\item For PTY, the use of additional sector labels such as GOV or OPP help to distinguish political parties in government or in opposition from more general references to political parties.
\item PRE is used to identify actors associated with partially recognized territories like Transnistria. It is added to whatever other sector codes and actor would receive, e.g. a mention of the Transnistrian breakaway government would receive the ``GOV'' and ``PRE'' codes, while proper Moldovian government would only receive the ``GOV'' code. See \autoref{partially-recognized-entities}.
\item For militarized groups, we drop the INS (insurgent) and SEP (separatist) distinctions incorporated into CAMEO during the research phase of ICEWS: these can be resolved on the basis of the group identity and group objectives are frequently ambiguous in any case.
\item Two modifications of CAMEO sector codes: in CAMEO `MED' was ``media'' and `HLH' was ``medical'' but no one could remember those.
\end{enumerate}



\chapter{Data Fields}

\begin{quote}
\textbf{Note: This chapter is still under development and is not likely to be of interest to most readers. Not all items discussed within this chapter have been implemented. For those that have been implemented, please see \citet{halterman2023creating} and \citet{HaltermanEtAl2023}.}

\end{quote}
\bigskip

In addition to providing a coding ontology, PLOVER is also intended to provide a standardized data exchange format using \ti{named} data fields instead of the current system where the content of data fields is usually determined by \ti{location} in some delimited format such as \txt{.csv}. Standardizing these field names will simplify the merging and reuse of datasets, and such data are far easier for a human to read.

Despite the apparent complexity of the formats discussed here, note that the only required field we have added to ``event data classic'' is the \texttt{id} identifier, so the simplest form of an event record would look like
\begin{verbatim}
{
	"id" : "PHOXv1-20160724-0042",
	"date" : 2016-07-24,
	"actor" : [{"code":"USA"}],
	"recipient" : [{"code":"CAN"}],
	"event" : ["CONSULT"]
}
\end{verbatim}

\noindent For ease of parsing and use, we suggest formatting PLOVER in newline-delimited JSON (JSONL) format, with each event formatted as one valid JSON entry, each on a separate row.

Except in the small number of cases where a standard format is specified, the content of the field is left open, and in particular ``number'' should be interpreted as ``number or code'': for example instead of providing the number of individuals killed, a dataset might use a set of categories giving ranges. Similarly, fields such as \texttt{context} can take multiple values: typically these would be formatted using a JSON ``array'' structure---which is to say, a list---but responsibility for handling these details is left to the data provider and users.  Providers should feel free to include named fields beyond those provided here but if a data set codes or extracts information  corresponding to one of the existing fields, please use that name.

%\emph{I think we should take a firmer stance on all of this, producing a fully built out ``PLOVER-base" with all of the fields we discuss above. Other researchers can then certainly make their own variants of PLOVER (PLOVER-ICEWS, PLOVER-ACE, PLOVER-Andy's dissertation, etc) as needed, making it clear how they differ from PLOVER-base.}



\newpage

\begin{table}[htp]
\caption{PLOVER JSON }
\begin{center}
\begin{tabular}{|l|l|c|c|}
\hline
Name & Content & Note & Required? \\
\hline
id & unique identifier & 1 & Y\\
has\_event & event has been coded (True/False) & 5 & N\\
date & date in YYYY-MM-DD format &  & Y\\
time & ISO 8601-formatted time & 2 & N\\
enddate & date in YYYY-MM-DD format &  & N\\
endtime & ISO 8601-formatted time & 2 & N\\
actor & list of entity objects & & Y \\
recipient & list of entity objects & & N \\
event & list of event categories & & Y \\
event\_loc & location object for event & & N \\
event\_text & list of texts of event & & N \\
quad\_code & 1, 2, 3 or 4 & & N \\
event\_scale & floating point scale value & & N \\
mode & list of modes & 3 & N \\
context & list of contexts & 3 & N \\
link &  link identifier & 4 & N \\
text & text from which the record was coded & 6 & N \\
text\_info & textInfo object for text & & N \\
cite\_info & citeInfo object for text & & N \\
coder &  coder identification & & N \\
coded\_date & date of coding & & N \\
coded\_time & time of coding in ISO 8601-formatted time & 2 & N\\
comment &  any text & & N \\
\hline
\end{tabular}
\end{center}
\label{tab:json}
\end{table}

\noindent \textbf{Notes:}
\begin{enumerate}
\item The identifier should be unique within the data set; it is the responsibility of the user to reconcile identifiers across data sets

\item ISO 8601 allows a number of different formats for times depending on the level of detail. Formatting should be such that a string of the form \texttt{date + `T' + time} should yield an ISO-8601 datetime.
\item  \texttt{event}, \texttt{mode} and \texttt{context} fields can have multiple entries; they do not need to resolve to a single value, and in fact this is likely to occur fairly frequently in classifier-based systems which work with the general sense of a sentence, in contrast to dictionary-based systems which look for specific sets of words. Multiple event categories would be used in a single record if the source and recipient actors are the same; they would resolve to multiple records if the source and recipient actors are different, as might occur in a compound sentence.

\item  This can be used to create a common reference across multiple related events, such as demonstrations in multiple locations organized by the same group.

\item This is typically set to False when the record is part of a pre-processing pipeline

\item This slot will only be filled when the creator of the record has appropriate intellectual property rights for the text: this tends to be the exception rather than the rule
\end{enumerate}


\clearpage

\begin{table}[htp]
\caption{Information object for entities }
\begin{center}
\begin{tabular}{|l|l|}
\hline
Name & Content \\
\hline
code & 3-char top-level entity code (e.g., country)\\
sector & 3- or 6-char sector (GOV, MIL, etc)\\
entity\_text & extracted text for source \\
identifier\_id & unique identifier ID for source [see Note 1]\\
identifier\_text & unique identifier name for source [see Note 1]\\
religion & religion (code or text) \\
ethnicity & ethnicity (code or text) \\
office & office or official position (code or text) \\
gender & gender (code or text) \\
age & integer \\
\hline
\end{tabular}
\end{center}
\label{tab:actorinfo}
\noindent \textbf{Notes:}
\begin{enumerate}
\item These fields would be used to resolve the name of an entity that occurs in multiple forms---for example ``Islamic State'', ``IS'', ``ISIS'', ``Daesh''---into a single form or code. This should be the Wikidata ID for the entity. For example, the Islamic State's is https://www.wikidata.org/wiki/Q2429253 and its canonical Wikidata name is ``Islamic State of Iraq and the Levant''.
\end{enumerate}
\end{table}%

\begin{table}[htp]
\caption{Information object for text }
\begin{center}
\begin{tabular}{|l|l|}
\hline
Name & Content \\
\hline
sequence & sequence number of sentence \\
start & character offset for start of text  \\
end &  character offset for end of text   \\
text\_story & list of sentences from full story text \\
\hline
\end{tabular}
\end{center}
\label{tab:textinfo}
\end{table}%


\begin{table}[htp]
\caption{Information object for size }
\begin{center}
\begin{tabular}{|l|l|}
\hline
Name & Content \\
\hline
dead & number killed \\
injured & number injured \\
arrested & number arrested \\
\hline
\end{tabular}
\end{center}
\label{tab:sizeinfo}
\noindent \textbf{Notes:}
\begin{enumerate}
\item These fields are included as standard names because they are most likely to be used in event systems, but users should feel free to add additional fields for numbers that are not related to location.
\end{enumerate}
\end{table}%

\begin{table}[htp]
\caption{Information object for citations }
\begin{center}
\begin{tabular}{|l|l|}
\hline
Name & Content \\
\hline
corpus & name or other identifying information\\
citation &  bibliographic citation or database identifier for text\\
url &  URL for text\\
title &  title for text\\
language & language of text (ISO 639-1 two-letter codes)\\
publication & name of text publisher\\
license & license covering text\\
copyright & copyright covering text\\
coder &  identifying information for any event extraction system used\\
codebook &  reference for the codebook used to code the text,\\
& e.g. \texttt{plover-base-1.3.1} or \texttt{plover-protest-0.3}\\
version &  version of data set\\
\hline
\end{tabular}
\end{center}
\label{tab:citeinfo}
\end{table}%


\begin{table}[htp]
\caption{Location object: location information returned by Mordecai3, drawing from the Geonames database. }
\begin{center}
\begin{tabular}{|l|p{10cm}|}
\hline
Name & Content  \\
\hline
extracted\_place & original place name extracted from the text \\
resolved\_place & name of geographical location the event was resolved to (unicode). The rest of the fields provide more information on the returned location\\
geonameid & integer id of record in geonames database \\
lat & latitude in decimal degrees\\
lon & longitude in decimal degrees \\
city & name of the city \\
district & name of the admin 2 (district/county) level \\
province & name of the admin 1 (province/governorate/state) level \\
country & name of the country \\
country\_code & country code (3 character ISO code, to match the actor/recipient countries \\
feature\_class & high-level code, such as A for area or P for populated place. see http://www.geonames.org/export/codes.html\\
feature\_code & detailed feature type, such as PPLX for neighborhood, ADM2 for district, etc. See http://www.geonames.org/export/codes.html \\
resolution & code indicating the level of resolution. 5=sub-city, 4=city, 3=district, 2=province, 1=country \\
\hline
\end{tabular}
\end{center}
\label{tab:locations}

\end{table}


\clearpage

\section{Adding to PLOVER: protest example}\label{sec:adding_to_plover}


OEDA was founded on the principle that there should not be ``one data set to rule them all'': different implementations will have different strengths. As an example, a protest-specific coder could add more fields to the event record for things like the participant size (a numeric amount or size category), the number of people who were injured, the number of people arrested, etc. This section briefly outlines how PLOVER could be extended to code specific event types in greater detail. A protest-optimized coder could also include protest-specific contexts like the ones in Table \ref{tab:protestcontext}.

\begin{table}[htp]
\caption{PROTEST contexts}
\begin{center}
\begin{tabular}{|l|l|}
\hline
Name & Content \\
\hline
election   &   elections\\
political   &   political and constitutional reforms\\
economic &   economy, jobs\\
food           &   food, water, subsistence\\
env-disaster            &   environmental issues, disasters incl. earthquakes, floods, fires\\
discrimination            &   ethnic discrimination, ethnic issues\\
religion           &   religious discrimination, religious issues\\
education            &   education\\
foreign            &   foreign affairs/relations\\
war            &   domestic war, violence, terrorism\\
rights             &   human rights, democracy\\
pro-govt             &   pro-government\\
independence & independence or separatist movements\\
\hline
\end{tabular}
\end{center}
\label{tab:protestcontext}
\raggedright{Adapted from Salehyan and Hendix, \textit{Social Conflict Analysis Database} (SCAD)
Version 3.2: \url{https://www.strausscenter.org/images/codebooks/SCAD\_32\_Codebook.pdf}}\\~
\end{table}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{CAMEO vs. PLOVER}

As noted in the introduction, CAMEO was originally developed for academic research under U.S. National Science Foundation funding in the early 2000s, and was based on the WEIS system. The canonical citation for CAMEO is \cite{SGY09}, and the detailed manual, ca. 2012, is found at \texttt{\footnotesize http://eventdata.parusanalytics.com/data.dir/cameo.html}.  The CAMEO event framework was very much the work of Deborah Gerner and \"Om\"ur Yilmaz, with contributions by various coders in the Kansas Event Data System project; the enitity framework was strongly influenced by the VRA ``IDEA'' coding system developed in the late 1990s \citep{BBOJT03}. The CAMEO manual contains an extended discussion of the issues considered in transitioning from WEIS to CAMEO. Additional details on the development of the automated coding underlying CAMEO can be found in \cite{Schrodt06TPM} or {\texttt{\footnotesize http://eventdata.parusanalytics.com/utilities.dir/KEDS.History.0611.pdf}.

Considerable additional work on CAMEO was done in the early 2010s first in the context of the DARPA ICEWS research program, then later in the operational deployment of ICEWS by teams at BBN and Lockheed which was eventually incorporated into the Dataverse public data: details of this work on found in the internal documentation of that data.

\section{Summary of changes}

\begin{itemize}

\item A set of standardized names (``fields'') for JSON (\url{http://www.json.org/}) records are specified for both the core event data fields and for extended information such as geolocation and extracted texts; most of these fields are optional and where available we use existing specifications, for example the \url{http://geonames.org} geographical location field names, ISO-3166 country identifiers and ISO-8601 date and time formats.

\item Only the 2-digit event ``cue categories'' have been retained from CAMEO.

\item The details in the 3- and 4-digit categories are now delegated to the optional \texttt{mode} and \texttt{context} fields: see Section \ref{ssec:ecm} for further discussion of this.

\item A set of scaled ``PLOVER scores'' has been systematically derived from the ``Goldstein scores'' found in the ICEWS data set.

\item The CAMEO 01 and 02 categories dealing with comments have been eliminated.\fn{Ironically, this reverses a decision McClelland belatedly made---and later regretted---in the WEIS specification in the 1960s.}

\item The CAMEO 08 ``YIELD'' category has been split into verbal (\plcat{CONCEDE}) and material (\plcat{RETREAT}) components.

\item The ``target actor" event component was renamed \txt{recipient} for clarity and to better match the terminology used in the NLP literature on event extraction \citep{halterman2020extracting}. ``Source actor'' was renamed \txt{actor} to reduce confusion with the textual source of the event.

\item \texttt{Actors/Recipient} entries are now standardized using references to Wikipedia.

\item The complexity of substate codes has been limited, and the allowable substate modifiers have been substantially simplified.

\item Standard optional fields have been defined for some categories, and \txt{recipient} is optional in some categories.

\end{itemize}

%\newpage

\section{CAMEO to PLOVER translation}\label{ssec:ctp}

\begin{table}[htp]
\caption{PLOVER equivalents to CAMEO cue categories}
\begin{center}
\begin{tabular}{|c|l|l|}
\hline
CAMEO code & CAMEO text & PLOVER category \\
\hline
01 & MAKE PUBLIC STATEMENT & dropped \\
02 & APPEAL & dropped \\
03 & EXPRESS INTENT TO COOPERATE & AGREE \\
04 & CONSULT & CONSULT \\
05 & ENGAGE IN DIPLOMATIC COOPERATION & SUPPORT \\
06 & ENGAGE IN MATERIAL COOPERATION & COOPERATE \\
07 & PROVIDE AID & AID \\
08 & YIELD (081 to 083) & CONCEDE \\
08 & YIELD (084 to 087) & RETREAT \\
09 & INVESTIGATE & ACCUSE \\
10 & DEMAND & REQUEST \\
11 & DISAPPROVE & ACCUSE \\
12 & REJECT & REJECT \\
13 & THREATEN & THREATEN \\
14 & PROTEST & PROTEST \\
15& EXHIBIT FORCE POSTURE & MOBILIZE \\
16 & REDUCE RELATIONS & SANCTION \\
17 & COERCE & COERCE \\
18 & ASSAULT & ASSAULT \\
19 & FIGHT & ASSAULT \\
20 & USE UNCONVENTIONAL MASS VIOLENCE & FIGHT (see Note 1) \\
\hline

\end{tabular}
\end{center}
\label{tab:xlate}
\end{table}%

\noindent \textbf{Notes:}

\begin{enumerate}
\item For unconventional weapons, the  \txt{mode} in the \plcat{FIGHT} record would be set to \plmod{unconventional}. \item Generally, everything at the 3- and 4-digit level should simply be reduced to the 2-digit cue category and converted accordingly. Depending on your specific application, you might want to make some exceptions to this---for example a CAMEO  ``015: Acknowledge or claim responsibility'' might be considered \plcat{AGREE} and a CAMEO ``016: Deny responsibility'' might be considered REJECT---but we are not making general recommendations on this. Except to suggest that for the benefit of those trying to replicate your work, you carefully document any such decisions.
\end{enumerate}


%\newpage

\section{Summary of event categories }

\begin{tabular}{lccp{1.5in}p{1.2in}}
\toprule
Event Type & Quad & Modes & Requires Recipient & Other Fields \\
\midrule
AGREE & \multirow{4}{*}{V-Coop.} \\
CONSULT &  & Yes \\
SUPPORT & \\
CONCEDE  & \\
\midrule
COOPERATE & \multirow{3}{*}{M-Coop.} & 	& Yes \\
AID & & Yes \\
RETREAT & & Yes \\
\midrule
REQUEST & \multirow{4}{*}{V-Conf.} & Yes  \\
ACCUSE & & Yes \\
REJECT & & Yes\\
THREATEN & & Yes \\
\midrule
PROTEST & \multirow{5}{*}{M-Conf.} & Yes 	& Yes & event\_loc \\
SANCTION & & Yes 			& Yes \\
MOBILIZE & & Yes \\
COERCE && Yes \\
ASSAULT && Yes & Only if one-sided or SideAB, otherwise all participants in source & event\_loc, dead, injured, size \\
\bottomrule
\end{tabular}

\begin{table}[htp]
\caption{Quad categories in PLOVER}
\begin{center}
\begin{tabular}{|l|l|c|}
\hline
Quad category & PLOVER categories & Numeric\\
\hline
Verbal cooperation & AGREE, CONSULT, SUPPORT, CONCEDE &  1 \\
Material cooperation & COOPERATE, AID, RETREAT & 2 \\
Verbal conflict & REQUEST, ACCUSE, REJECT, SANCTION, THREATEN & 3\\
Material conflict & PROTEST,  MOBILIZE, COERCE, ASSAULT & 4\\
\hline

\end{tabular}
\end{center}
\label{default}
\end{table}

\section{A note on \plcat{CRIME}}

A separate event category for crime has been added and removed several times as PLOVER was being drafted. While criminal activity is important to capture in event data \citep{osorio2015contagion, osorio2017supervised}, we have decided to not include a separate event category for it for several reasons:

\begin{enumerate}

	\item Whether activity is criminal or not often depends on on the identity of the actor: actions undertaken by rebel groups may not fit within a definition of \plcat{CRIME}, while the same action taken by a drug cartel might. We have generally tried to avoid relying on the identities of actors in order to define events, due in part to the implementation of past coders, which did not use actor information to code event types.

	\item Crime overlaps with other event categories, especially \plcat{ASSAULT}, which would make it difficult to train a \plcat{CRIME} classifier that did not pick up events that better belong in other categories.
\end{enumerate}


\noindent That said, PLOVER still includes mechanisms for crime-type events to be coded. Researchers who are interested in criminal behavior have two primary options for locating it in PLOVER events:

\begin{enumerate}
	\item Identify events taken by criminal actors. As coders move away from hand-constructed dictionaries to resolve actors, many more groups will be coded. Researchers will be able to subset events to those undertaken by specific criminal groups (e.g. the Sinaloa Cartel) or by using the CRM actor code.
	
	\item Use the \plcon{crime} and \plcon{illegal\_drugs} contexts: see Table \ref{tab:general-contexts}.
\end{enumerate}


\section{Some residual issues}\label{sec:nothing}

In the discussions leading to the development of PLOVER, several additional open issues were raised that we have decided to remain agnostic on are listed below. These issues have not yet been fully implemented in most coding projects employing PLOVER to date.

\begin{description}

\item[Temporal markup:] This is emerging as a major issue in event extraction, particular among users who are interested in the long-standing objective of automated chronology generators. While there are some significant efforts on this in the NLP community---\url{http://www.timeml.org/}---we don't feel we currently have the experience required to make recommendations.

\item[De-duplication:] There is no consensus on this beyond noting that the widely-used ``one-a-day filtering'' is controversial, and it is a topic where there is currently active research and experimentation, so we're leaving it alone.

\item[Required entities:]PLOVER, in contrast to CAMEO, makes the \txt{recipient} optional for some event types. One outstanding question is whether the \txt{actor} should also be optional for some event types. Some event types often leave the \txt{actor} implicit, for example, ``4 people were arrested/killed in a suicide bombing etc." These have no explicit, named \txt{actor} so they will not be coded by PLOVER. Similarly, many natural disasters do not fit neatly into an entity-centric approach to coding (``mudslides destroyed dozens of houses"). We could consider relaxing this requirement to increase our recall, but at the potential cost of more false positives and greater conceptual complexity.

\end{description}


\bibliographystyle{humannat}
\bibliography{PLOVER}

\end{document}