# La vitrine et l'envers du décor : le document computationnel Constat : Vitrine (résultats) bien différent de l'envers du décor (calculs, souvent plus désorganisé) Notes sur les outils * Jupyter intégré au gitlab => pour python, julia, R * export basé sur pandoc * Rstudio à installer et communiquer avec gitlab, pour R * export basé sur pandac * OrgMode : le plus puissant , nécessite emacs, un peu plus dur à apprendre=> permet de combiner différents langages * export pleinement personnalisable (obligatoire) * capacité à écrire directement du latex qui sera passé tel quel lors de l'export ## Exemples de travaux aux résultats controversés * article en économie ayant conduit à des politiques d'austérité * données brutes avec des erreurs de calculs, traitement de données douteux * auteurs répondent sur chaque point * en fait les calculs ont très peu de sens, pas justifié de faire des politiques d'austérité la dessus * __nécessité de publier toutes les données__ * IRM fonctionnelle * IRM avec un saumon mort montre que le bruit statistique peut être trop important => erreur numérique * met le doigt sur des problèmes méthodologiques * __nécessité de vérifier les calculs après coup__ * __nécessité de vérifier analyse__ * remise en cause fait partie du processus scientifique * __rigueur__ et __transparence__ indispensables ## Pourquoi est-ce difficile? 1. manque de données * sources, données * choix non expliqués suspicieux => garder dans le cahier de lab 2. erreurs dues aux ordinateurs => erreurs de calcul * logiciels propriétaires boites noires point and click, ou macro excel etc... * _mauvais utilisation des tableurs_ * __on doit avoir confiance en chaque brique__ 3. manque de rigueur et d'organisation * backup, historique, pas de contrôle qualité * manque d'intégration continue, revue de code ### Tout rendre public? * problèle social car on demande des articles courts * ne pas avoir peur de montrer des faiblesses, la transparence es t la clé * quelqu'un peut trouver une erreur * quelqu'un peut tirer avantage à ma place * se donner les moyens que tout soit __inspectable__ ### Outils à éviter et alternatives * outils propriétaires à éviter VS logiciels libres * _markown, orgmode_ VS _excel,word_ * langages libres * utiliser formats textes et non binaires => meilleure durabilité * ne pas être soumis aux restrictions d'un seul hebergeur * __gitlab__ VS dropbox ## Le document computationnel : principes Science moderne : 1. données 2. analyse, visualisations => parfois retours au données 3. publication = partie émergée de l'iceberg Recherche reproductible = pouvoir aller dans les 2 sens ### Objectifs du document * inspecter * refaire : vérifier, corriger, réutiliser ### Caractéristiques * vitrine : comme un article au format pdf * envers du décor : notebook jupyter par exemple * éditeur interactif * différents fragments de code avec résultats * images/ graphes * on peut choisir les parties à partager ou non * __1 seul document avec explication code résultat__ * export possible ## Présentation des outils ### Jupyter * comme pour atelier python * liste des commandes magiques : `%lsmagic` => utiles pour interargigr avec d'autres langages * possible d'écrire du R directement dedans, shell, perl etc... `%%sh` * production et partage de documents finaux : comprennent tous les résultats * commiter pour partager * ou export html classique * controler la visibilité avec bouton `hide code` dans view (mais je ne le vois pas dans mon jupyter local) ### OrgMode * permet de combiner différents langages * langage de balisage léger * fonctionne avec emcs * export en latex possible #### Fonctionnement * fichiers avec extension `.org` * images ne sont pas sauvées dans fichier `.org` mais sorties textuelles oui #### Lancement * `tab` permet de déplier les sections #### Exécution des blocs * template pour différens langages (r, python, shell) * exemple `` pour langage r * blocs pour des sorties textuels et blocs pour des sorties graphiques * insepecter les buffer pour voir les consoles actives dans les différents langages * attention il peut y avoir des incohérences si on modifie les données puis qu'on rééxécute la session * __tout rééexécuter depuis le début__ * commandes * `CTRL C CTRL C` pour exécuter un bloc * `alt-x org-babel-execute-buffer` : ré-éxécuter la session au complet * `ho` : exporter en html * `C-c C-q noexport enter` : exclure toute une section de l'export * avoir plusieurs langages avec template * commandes shell aussi * avec l'historique riche de la session =>on peut faire du ssh dedans ! se connecter à d'autres machines ! * plusieurs sessions possibles #### Production et partage du document final * attention au stockage penser aussi à stocker les fichiers produits (images etc) * une solution juste pour voir contenu : exporter html ou pdf * contrôler la visibilité (stocker aussi les fichiers produits si on veut permettre aux autres de voir) * `export results` VS `export both` * __difficulté/ avantage principal : maîtriser les raccourcis clavier !!__ ## Travailler avec les autres * produire un document publiable à partir d'un document computationnel demande env parfaitement configuré ! * convaincre co-auteurs : * co auteurs enthousiastes => faire le service après vente (vérifier même résultat quel que soit la machine) * co auteur veuillent s'investir juste _a minima_ : ils peuvent simplement modifier le texte en md et pas recalculer ou exporter le document final * co auteur qui ne changent pas leurs habitudes : alors avoir 1 doc computationnel et 1 doc qui inclut les figures générées * **tout doit être recalculable dans document computationnel** * partager son document avec des collègues * dropbox etc : pb de controle d'acces * gitlab : rendre dépot public => **nettoyer l'historique avant** (par exemple stockage de documents sous copyrights etc), mieux * de l'avoir à l'esprit dès le départ ! * archives ouvertes : HAL, Figshare/zenodo (CERN) ## Analyse comparée des différents outils * cours ou tutoriel => notebook Jupyter * constuire la solution au fur et à mesure * journal => orgmode * un seul auteur, chronologique, étiquette, liens * contient typiquement notes de réunions, bouts de code exécutables * recherche facile avec les étiquettes * cahier de laboratoire => orgmode * organisation sémantique avec conventions d'éditions du document * sections expériences /analyses, etc * plusieurs auteurs * article reproductible => orgmode, difficile avec Jupyter * possibilité de regénérer des figures, revenir aux sources * section cachées avec les morceaux de code pour générer les figures * export en latex possible directement * conclusion : Jupyter plus facile à prendre en main, orgmode plus puissant, y compris pour la navigation