\documentclass{beamer}

\mode<presentation>
{
  \usetheme{Boadilla}
  \usecolortheme{seahorse}
  \setbeamertemplate{navigation symbols}{}
  \setbeamertemplate{caption}[numbered]
}

\usepackage{natbib}
\usepackage[french]{babel}
\usepackage[latin1,utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage{amsmath}
\usepackage{amssymb}
\DeclareMathOperator*{\argmin}{arg\,min} %argmin
\DeclareMathOperator*{\argmax}{arg\,max} %argmax
\usepackage[ruled, vlined, linesnumbered]{algorithm2e} %Algorithms
\newcommand{\From}{\textbf{from }} %Keywords algorithmes
\newcommand{\To}{\textbf{to }} %Keywords algorithmes

\usepackage{xcolor}
\usepackage{graphicx}
\usepackage{tikz-dependency} %Dependency trees
\usepackage{float} %Floating figures
\usepackage{natbib,hyperref} %Links
\usepackage[ruled, vlined, linesnumbered]{algorithm2e} %Algorithms
\usetikzlibrary{automata,arrows,positioning} %automate, transition machine

\newcommand{\stack}[1]{\ensuremath{\sigma_{#1}}}
\newcommand{\buf}[1]{\ensuremath{\beta_{#1}}}
\newcommand{\depset}[0]{\ensuremath{\Delta}}
\newcommand{\blue}[1]{{\color{blue} #1}}
\newcommand{\red}[1]{{\color{red} #1}}


\newcommand{\fm}  [0] {{\color{blue}{\tt fm}}}
\newcommand{\mcf} [0]{{\color{blue}{\tt mcf}}}
\newcommand{\mcd} [0]{{\color{blue}{\tt mcd}}}
\newcommand{\cla} [0]{{\color{blue}{\tt cla}}}
\newcommand{\bd} [0]{{\color{blue}{\tt bd}}}
\newcommand{\tm} [0]{{\color{blue}{\tt tm}}}
\newcommand{\as} [0]{{\color{blue}{\tt as}}}
\newcommand{\dicts}[0]{{\color{blue}{\tt dicts}}}
\newcommand{\cfw} [0]{{\color{blue}{\tt cfw}}}

\newcommand{\ID} [0]{{\color{blue}{\tt ID}}}
\newcommand{\MORPHO} [0]{{\color{blue}{\tt MORPHO}}}
\newcommand{\EMPTY} [0]{{\color{blue}{\tt EMPTY}}}
\newcommand{\FORM} [0]{{\color{blue}{\tt FORM}}}
\newcommand{\CPOS} [0]{{\color{blue}{\tt CPOS}}}
\newcommand{\POS} [0]{{\color{blue}{\tt POS}}}
\newcommand{\LEMMA} [0]{{\color{blue}{\tt LEMMA}}}
\newcommand{\FEATS} [0]{{\color{blue}{\tt FEATS}}}
\newcommand{\GOV} [0]{{\color{blue}{\tt GOV}}}
\newcommand{\LABEL} [0]{{\color{blue}{\tt LABEL}}}
\newcommand{\SENTSEG} [0]{{\color{blue}{\tt SENT\_SEG}}}
\newcommand{\AZ} [0]{{\color{blue}{\tt A \ldots Z}}}

\title[Présentation MACAON]{Présentation MACAON}
\author{Alexis Nasr\\ Franck Dary}
\institute{M2 - IAAA}
\date{\today}

\begin{document}
\maketitle

\frame{\frametitle{Table of contents}\tableofcontents} 

\section{Formats de fichiers}
\subsection{Multi Column File ({\tt mcf})}
\begin{frame}{Multi Column File (\mcf{})}
Format de fichier qui permet de représenter les données textuelles
et les annotations qui y sont attachées.

\begin{itemize}

  \item format ``en colonne''~:

  \begin{itemize}
  \item chaque ligne correspond à une unité textuelle minimale (token)
  \item chaque colonne correspond à un attribut du token
  \end{itemize}

  \item les colonnes sont séparées les unes des autres par une tabulation

  \item le nombre de colonnes est illimité

  \item l'interprétation de chaque colonne est décrite dans un fichier \mcd{} (Multi Column Description) 

  \item les lignes commençant par ``\#'' sont des commentaires (potentiellement des métadonnées)
    
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{\mcf{}~: exemple}
\footnotesize
\begin{verbatim}
La        det     le        1    det        0
diane     nc      diane     1    suj        0
chantait  v       chanter   0    root       0
dans      prep    dans     -1    mod        0
la        det     le        1    det        0
cour      nc      cour     -2    obj        0
des       prep    des      -1    dep        0
casernes  nc      caserne  -1    obj        0
.         poncts  .        -6    eos        1
Et        coo     et        0    root       0
le        det     le        1    det        0
vent      nc      vent      3    suj        0
du        prep    du       -1    dep        0 
matin     nc      matin    -1    obj        0
soufflait v       souffler -5    dep_coord  0
sur       prep    sur      -1    mod        0
les       det     le        1    det        0
lanternes nc      lanterne -2    obj        0
.         poncts  .        -9    eos        1
\end{verbatim}
\normalsize
\end{frame}

\subsection{Multi Column Description ({\tt mcd})}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{frame}[fragile]{Multi Column Description (\mcd{})}

Un fichier \mcd{} associe une étiquette à chaque colonne d'un fichier \mcf{}, exemple mcd du format conllu :

\begin{verbatim}
0 ID
1 FORM
2 LEMMA
3 POS
4 EMPTY
5 MORPHO
6 GOV
7 LABEL
8 EMPTY
9 EMPTY
\end{verbatim}
  
\end{frame}

\begin{frame}[fragile]{Etiquettes}

  \begin{itemize}

    \item Une étiquette permet d'associer un nom explicite à une colonne

    \item Elles permettent d'accéder au contenu de la colonne à l'aide de {\it Word Features} décrites dans un fichier \fm{}.

      \item Exemples d'étiquettes~:
      \begin{itemize}
        \item {\tt \ID{}} indice du token dans sa phrase
        \item {\tt \FORM{}} la forme du token
        \item {\tt \POS{}} sa partie de discours
        \item {\tt \LEMMA{}} son lemme
        \item {\tt \MORPHO{}} traits morphologiques
        \item {\tt \GOV{}} l'indice de son gouverneur
        \item {\tt \LABEL{}} sa fonction syntaxique
        \item {\tt \EMPTY{}} colonne vide
  \end{itemize}
  \end{itemize}
\end{frame}

\subsection{Feature Model ({\tt fm})}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{frame}{Features}
Fonctions permettant de représenter différents aspects d'une configuration\vspace{0.6cm}

Il existe plusieurs types de features, pour les construire, on utilise des {\bf fonctions d'adresse} et des {\bf fonctions d'attribut}.

Toutes les Features sont codées dans le fichier {\tt transition\_machine/src/FeatureBank.cpp}\vspace{0.6cm}

  
\end{frame}

\begin{frame}{Fonction d'adresse}
Une fonction d’adresse indique à quel token on fait
référence dans une configuration. Elle se compose de :
\begin{itemize}
    \item Un objet cible {\color{blue}{b}}(buffer) ou {\color{blue}{s}}(stack)
    \item Un indice relatif dans l'objet (ex : 2 ou -3)
    \item un certain nombre (voir 0) de ces fonctions qui vont se combiner entres elles : 
\begin{table}[]
\begin{tabular}{|l|l|}
\hline
\color{blue}{ldep}  & dépendent le plus à gauche \\ \hline
\color{blue}rdep  & dépendent le plus à droite \\ \hline
\color{blue}l2dep  & dépendent le 2ème plus à gauche \\ \hline
\color{blue}r2dep  & dépendent le 2ème plus à droite \\ \hline
\color{blue}gov  & gouverneur \\ \hline
\end{tabular}
\end{table}
\end{itemize}
Exemple : s.2.gov.l2dep qui désigne le deuxième dépendent le plus à gauche du gouverneur du token en position 2 dans la pile.
\end{frame}

\begin{frame}{Fonction d'attribut}
Une fonction d'attribut permet d'extraire une certaine information d'un token.\vspace{0.4cm}
Elle se compose d'une combinaison des éléments suivants :
\begin{table}[]
\begin{tabular}{|l|l|}
\hline
\color{blue}{\'{E}tiquette}  & une colonne du \mcd{}\\ \hline
\color{blue}U  & L'étiquette commence-t-elle par une majuscule ?\\ \hline
\color{blue}fasttext  & découpe l'étiquette en paquets de lettres \\ \hline
\color{blue}nbr  & nombre de dépendants droits \\ \hline
\color{blue}nbl  & nombre de dépendants gauches \\ \hline
\end{tabular}
\end{table}

Exemple : FORM.U est-ce que la forme du token commence par une majuscule ?

\end{frame}

\begin{frame}{Features composées}
La majorités des features sont la concaténation (avec ``\#'') d'une fonction d'adresse et d'une fonction d'attribut, exemples :
\begin{itemize}
    \item s.1.ldep.ldep\#LABEL La fonction syntaxique du dépendant le plus à gauche du dépendant le plus à gauche du token en position 1 de la pile.
    \item b.-3\#LEMMA.fasttext La décomposition en paquets de lettres du lemme du token en position -3 dans le buffer.
    \item s.0.gov\#nbr Le nombre de dépendants droits du gouverneur du token en sommet de pile.
\end{itemize}
\end{frame}

\begin{frame}{Features spéciales}
Il existe 2 autres types de features :
\begin{itemize}
    \item tc.X la Xème transition la plus récente dans l'historique des transitions qui ont menées à cette configuration. (X commence à 0)
    \item X\#DIST.Y Distance entre le token X et le token Y dans la phrase. Exemple : b.0\#DIST.s.0
\end{itemize}
\end{frame}

\begin{frame}[fragile]{Feature Model (\fm{})}
  
  \begin{itemize}
    
  \item Un fichier \fm{} définit une collection de Features qui vont permettre de décrire une configuration
  \item Ces Features sont utilisées par le classifieur pour prédire le prochain mouvement
  \item Chaque ligne d'un fichier \fm{} définit une Feature

  \end{itemize}

\end{frame}

\begin{frame}[fragile]{\fm{}~: Exemple}

\begin{verbatim}
b.1#POS
b.1#MORPHO
b.2#POS
b.2#MORPHO
b.-2#LABEL
b.-1#LABEL
b.0#LABEL
s.0#LABEL
s.1#LABEL
b.-1.gov#POS
b.-1.gov#MORPHO
s.0.gov#POS
s.0.gov#MORPHO
s.1.gov#POS
s.1.gov#MORPHO
\end{verbatim}

\end{frame}

\subsection{Dictionnaires ({\tt dicts})}
\begin{frame}[fragile]{\dicts{}}
Fichier qui définit des dictionnaires qui vont contenir les paires \textit{feature value} $\rightarrow$ \textit{embedding}, exemple :
\footnotesize
\begin{verbatim}
#Name          Dimension Mode       PretrainedFilename #
########################################################
Parser_actions 18        Embeddings _
Parser_bool    2         OneHot     _
Parser_int     16        Embeddings _
Parser_form    100       Embeddings _
\end{verbatim}
\normalsize
\begin{itemize}
    \item Name : nom du dictionnaire
    \item Dimension : taille des embeddings
    \item Mode : Embeddings ou OneHot
    \item PretrainedFilename : chemin vers un dictionnaire déjà complet (pretraining des embeddings)
\end{itemize}
\end{frame}

\subsection{Classifiers ({\tt cla})}
\begin{frame}[fragile]{\cla{}}
Type de fichier qui permet de décrire un classifieur (qui traite l'information à un certain niveau) exemple : parser, tagger, lemmatizer...
\begin{verbatim}
Name : Parser
Type : Prediction
Oracle : parser
Feature Model : parser.fm
Action Set : parser.as
Topology : (500,RELU,0.3)
Dynamic : yes
\end{verbatim}
Ici Topology représente un MultiLayerPerceptron d'une couche cachée de taille 500 de fonction d'activation REctifiedLinearUnit et de 30\% de dropout.
\end{frame}

\subsection{Buffer Description ({\tt bd})}
\begin{frame}[fragile]{\bd{}}
Type de fichier qui permet de décrire le buffer de la machine.\\
Chaque ligne du fichier \bd{} décrit une bande du buffer, exemple :
\footnotesize
\begin{verbatim}
#Index Name   ref/hyp dict    Policy   Must print?#
###################################################
0      ID     ref     none    FromZero 1
1      FORM   ref     form    FromZero 1
3      POS    ref     pos     FromZero 1
5      MORPHO ref     morpho  FromZero 1
0      SGN    hyp     sgn     FromZero 0
0      EOS    hyp     eos     FromZero 0
\end{verbatim}
\normalsize
\begin{enumerate}
    \item Index : Indice de la colonne du format de sortie dans laquelle le contenu de cette bande sera écrit.
    \item Name : Nom de cette bande.
    \item ref/hyp : Le contenu de cette bande est donné (ref) ou prédit (hyp).
    \item dict : Le nom du dictionnaire qui contient les valeurs de cette bande.
    \item Policy : Le dictionnaire est figé (Final) ou peut évoluer (FromZero) ?
    \item Must print ? : Faut-il afficher cette bande dans la sortie ?
\end{enumerate}
\end{frame}

\subsection{Transition Machine ({\tt tm})}
\begin{frame}[fragile]{\tm{}}
Type de fichier qui décrit la Transition Machine.\\
Une telle machine ressemble à un automate, elle comporte des états et des transitions étiquetées qui relient ces états entre eux.\\ A chaque état est associé un classifieur. Exemple :
\footnotesize
\begin{verbatim}
Name : Parser Machine
Dicts : parser.dicts
%CLASSIFIERS
strategy strategy.cla
signature signature.cla
parser parser.cla
%STATES
strategy strategy
signature signature
parser parser
%TRANSITIONS
strategy signature MOVE signature
strategy parser MOVE parser
parser strategy *
signature strategy *
\end{verbatim}
\normalsize
\end{frame}

\begin{frame}[fragile]{\tm{}}
\begin{enumerate}
    \item Name : Le nom de la machine.
    \item Dicts : Le fichier qui décrit les dictionnaires.
    \item CLASSIFIERS : Sur chaque ligne le nom d'un classifieur et le fichier qui le décrit.
    \item STATES : Sur chaque ligne le nom d'un état de la machine et le nom du classifieur correspondant.
    \item TRANSITIONS : sur chaque ligne on a un état de départ, un état d'arrivée, et l'étiquette sur la transition.
\end{enumerate}
Dans l'exemple donné plus haut, l'état parser s'occupe de construire l'arbre syntaxique, l'état signature appose une signature sur chaque mot (qui comporte des informations sur les parties de discours possibles pour ce mot) et l'état strategy s'occupe de décider à qui il donne la main à un instant t (à parser ou à signature).
\end{frame}

\begin{frame}[fragile]{\tm{}}
Toujours dans le même exemple, l'état initial est strategy car il est définit le premier.\\
\begin{enumerate}
    \item On peut passer de l'état strategy à l'état signature avec l'action MOVE signature.
    \item On peut passer de l'état strategy à l'état parser avec l'action MOVE parser.
    \item On passe de l'état parser à l'état strategy avec n'importe quelle action.
    \item On passe de l'état signature à l'état strategy avec n'importe quelle action.
\end{enumerate}
\end{frame}

\subsection{Action Set ({\tt as})}
\begin{frame}[fragile]{\as{}}
Type de fichier qui définit la liste des actions que peut effectuer un classifieur. Exemple :
\footnotesize
\begin{verbatim}
REDUCE
LEFT ccomp
RIGHT ccomp
LEFT dep
RIGHT dep
LEFT cop
RIGHT cop
LEFT conj
RIGHT conj
LEFT iobj
RIGHT iobj
EOS
Default : SHIFT
\end{verbatim}
\normalsize
L'action préfixée par Default : est celle utilisée par defaut quand aucune autre action n'est applicable. Les actions sont ordonnées par priorité décroissante, lorsque 2 actions sont possibles on préfère celle de plus grande priorité.
\end{frame}

\section{Installation et utilisation}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{frame}[fragile]{Dépots GIT}

  Le projet macaon est réparti sur deux dépôts GIT~:
  
  \begin{itemize}
    
  \item \blue{\tt macaon} contient le code des différents modules
    {\tt https://gitlab.lis-lab.fr/franck.dary/macaon}
    
  \item \blue{\tt macaon\_data} contient les données primaires ainsi que les procédures de compilation des modèles à partir des données primaires
    {\tt https://gitlab.lis-lab.fr/franck.dary/macaon\_data}
    
  \end{itemize}
\end{frame}

\subsection{Installation des dépendances}
\begin{frame}[fragile]{{\tt macaon}}

macaon dépend des bibliothèques :
\begin{itemize}
    \item dynet
    \item fasttext
    \item boost\_program\_options
\end{itemize}
Et des logiciels g++, CMake, python3\\
\end{frame}

\begin{frame}[fragile]{installer dynet}
\begin{verbatim}
mkdir eigen3 && cd eigen3
git clone https://github.com/eigenteam/eigen-git-mirror.git .
\end{verbatim}
\url{https://dynet.readthedocs.io/en/latest/install.html#}
\end{frame}

\begin{frame}[fragile]{Installer fasttext}
\begin{verbatim}
mkdir fasttext && cd fasttext
git clone https://github.com/facebookresearch/fastText.git .
mkdir build && cd build
cmake .. && make -j && sudo make install
\end{verbatim}
\end{frame}

\begin{frame}[fragile]{Installer boost\_program\_options}
Télécharger boost
\url{https://dl.bintray.com/boostorg/release/1.71.0/source/boost_1_71_0.tar.gz}
\begin{verbatim}
tar -xvf boost_1_71_0.tar.gz
cd boost_1_71
./bootstrap.sh --with-libraries=program_options
sudo ./b2 install
\end{verbatim}
\end{frame}

\subsection{Installation de macaon}
\begin{frame}[fragile]{Installer macaon}
\begin{verbatim}
cd macaon
mkdir build
cd build
cmake .. && make -j && sudo make install
\end{verbatim}
\end{frame}

\subsection{Télécharger les corpus}
\begin{frame}[fragile]{Télécharger les corpus}
\begin{verbatim}
TODO
\end{verbatim}
\end{frame}

\begin{frame}[fragile]{Entraîner un outil}
Une fois macaon\_data présent sur l'ordinateur, on ajoute la ligne suivante au .bashrc
\begin{verbatim}
export MACAON_DIR=chemin/vers/macaon_data
\end{verbatim}
Ensuite on se rend dans un dossier où les outils sont déjà configurés :
\begin{verbatim}
cd macaon_data/UD_any/
\end{verbatim}
On indique où se trouvent nos données (corpus) : Dans le fichier config renseigner le dossier où se trouvent les corpus.\\ \vspace{0.2cm}
On extrait certaines informations des corpus (à ne faire qu'une fois) :
\begin{verbatim}
cd data
make
cd ..
\end{verbatim}
\end{frame}

\subsection{Entraînement et évaluation}
\begin{frame}[fragile]{Entraîner un outil}
Toujours dans le dossier macaon\_data/UD\_any/ on lance :
\begin{verbatim}
./train.sh NOMLANGUE parser parser_maLangue
\end{verbatim}

Qui va entraîner un parser nommé ``parser\_maLangue'', en utilisant les données issues des corpus de NOMLANGUE.\\\vspace{0.2cm}
Par exemple pour entraînter un parser sur le français on peut faire :
\begin{verbatim}
./train.sh fr parser parser_fr
\end{verbatim}
On peut ajouter des arguments à la commande, par exemple pour le mode debug :
\begin{verbatim}
./train.sh fr parser parser_fr --debug
\end{verbatim}
Pour voir la liste de tous les arguments possibles :
\begin{verbatim}
macaon_train --help
\end{verbatim}
\end{frame}

\begin{frame}[fragile]{Entraîner un outil}
Une fois l'entraînement terminé, le modèle sera automatiquement évalué sur le corpus de test, le résultat sera affiché comme ça :
\footnotesize
\begin{verbatim}
Metric     | Precision |    Recall |  F1 Score | AligndAcc
-----------+-----------+-----------+-----------+-----------
Tokens     |    100.00 |    100.00 |    100.00 |
Sentences  |     98.48 |     98.01 |     98.25 |
Words      |    100.00 |    100.00 |    100.00 |
UPOS       |    100.00 |    100.00 |    100.00 |    100.00
XPOS       |    100.00 |    100.00 |    100.00 |    100.00
UFeats     |    100.00 |    100.00 |    100.00 |    100.00
AllTags    |    100.00 |    100.00 |    100.00 |    100.00
Lemmas     |    100.00 |    100.00 |    100.00 |    100.00
UAS        |     91.40 |     91.40 |     91.40 |     91.40
LAS        |     88.53 |     88.53 |     88.53 |     88.53
CLAS       |     90.88 |     84.32 |     87.48 |     84.32
MLAS       |     90.70 |     84.16 |     87.31 |     84.16
BLEX       |     90.88 |     84.32 |     87.48 |     84.32
\end{verbatim}
\normalsize
Pour le parsing, on s'intéresse aux lignes UAS et LAS. 

\end{frame}

\begin{frame}[fragile]{\'{E}valuer un outil}
Une fois l'entraînement terminé, on peut aussi évaluer l'outil manuellement comme suit :
\footnotesize
\begin{verbatim}
bin/maca_tm_parser_fr \
~/ud/fr/fr_test.conllu data/conllu.mcd > output.txt
\end{verbatim}
\normalsize
Ainsi output.txt contiendra la prédiction du parser, on va ensuite ajouter des colonnes vides à cette sortie car le script d'évaluation a besoin de 10 colonnes :
\footnotesize
\begin{verbatim}
../tools/conlluAddMissingColumns.py \
output.txt data/conllu.mcd > output.conllu
\end{verbatim}
\normalsize
Maintenant on utilise un script d'évaluation pour comparer la prédiction et le gold :
\footnotesize
\begin{verbatim}
../scripts/conll18_ud_eval.py \
~/ud/fr/fr_test.conllu output.conllu -v
\end{verbatim}
\normalsize
\end{frame}

\end{document}