Résumé

putdoc, puthtml… Oubliez! Depuis plusieurs années il est possible d’exécuter un programme Stata avec le notebook Jupyter grâce au noyau Stata_kernel de K.Barron ou plus récemment avec la librairie usine pystata (version 17). Du côté de RStudio on pouvait également exécuter un programme Stata dans un document Rmarkdown, avec le package statamarkdown. Mais l’exécution de Stata se faisant en mode batch. En 2022 avec l’arrivée du Quarto, et le nouveau noyau Jupyter nbstata de Tim Huegerich, on dispose d’une solution particulièrement efficace d’édition pour ce logiciel.

Documentation nbstata: https://github.com/hugetim/nbstata
Prérequis:
- Stata 17 minimum
- Version récente de Python
- Notebook Jupyter
- Installation du kernel nbstata

Avant de débuter ce tutoriel, concernant les avantages et les inconvénients d’utiliser le notebook Jupyter:

Les graphiques sont affichés sous le programme et non dans une fenêtre externe.
Le programme est exécuté dans des cellules de codes et non dans un éditeur de programme. Avec Jupyter, les macros temporaires restent enregistrées d’une cellule de codes à une autre. C’est plutôt pratique pour construire un programme pas à pas sans avoir à exécuter systématique les parties qui déclarent les macros temporaires en amont.
Le noyau nbstata permet d’enregistrer l’ensemble des cellules dans un fichier .do.
Niveau inconvénient ou limite d’utilisation. Les notebooks ne permettent pas d’afficher à la volée la base de données ou la frame active. Son utilisation n’est donc pas forcément adaptée au traitement et à la manipulation d’une base de données.

Installation de Jupyter

Une fiche est déjà disponible [Lien]. A l’Ined l’installation est largement facilité avec l’outil applined développé par le service informatique.

Pour vérifier que tout est bien installé:

Vérification pour Python: dans Stata, exécuter python query, et éventuellement tester une opération simple: python: 1+1
Vérification pour Jupyter: pour lancer le notebook, dans l’invite de commande windows (cmd dans la barre de recherche), exécuter jupyter notebook

Installation de nbstata

Les étapes sont bien décrites dans le document de Tim Huegerich.

Dans l’invite de commande windows exécuter successivement

pip install nbstata

Puis à minima:

python -m nbstata.install

Optionnellement, si on souhaite récupérer la couleur syntaxique

pip install jupyterlab_stata_highlight2

Utilisation de nbstata dans un notebook Jupyter

Dans new on choisit le kernel nbstata
Une fois le noyau chargé on peut exécuté dans les cellules une plusieurs lignes de programme.
Si on souhaite écrire du texte, on change le format de la cellule qui est par défaut code.
Pour afficher l’aide par exemple, on utilise un magik: %help nom_commande. La liste des magiks est donnée dans la documentation.
Contrairement à l’exécution de Stata dans son interface, les macro temporaires (local) sont conservées en mémoire d’une cellule à une autre.
On peut enregistrer l’ensemble des cellules en mode code dans un fichier .do

En résumé:

Remarque: on peut installer le notebook Jupyter dans VScode. On peut donc l’utiliser comme interface pour documenter un programme au lieu d’un navigateur Web. En revanche, il ne sera pas possible de récupérer un .do à partir des commandes exécuter dans les cellules.

Utilisation de nbstata dans un document Quarto

On indique de le header de la page (yaml) l’utilisation de jupyter et du noyau nbstata

---
title: "Exécution de Stata sous Quarto avec nbstata

jupyter: nbstata
---

Pour le bloc de codes sans option: on indique qu’on utilise stata: ```{stata}
Pour le bloc de codes avec option(s), on remplace #| (R,Python) par *|:

*| echo: false/true
*| eval: false/true

* Programme Stata

sysuse auto
tx scat price mpg

--- title: "Stata, Jupyter et Quarto: la solution nbstata" author: - name: "Marc Thévenin" affiliations: - name: "Ined" date: 08/30/2023 image: "https://posit.co/wp-content/uploads/2022/10/thumbnail-2.jpg" categories: - Notebook - Quarto - Jupyter abstract: | putdoc, puthtml... Oubliez! Depuis plusieurs années il est possible d'exécuter un programme Stata avec le notebook Jupyter grâce au noyau `Stata_kernel` de K.Barron ou plus récemment avec la librairie usine `pystata` (version 17). Du côté de RStudio on pouvait également exécuter un programme Stata dans un document Rmarkdown, avec le package `statamarkdown`. Mais l'exécution de Stata se faisant en mode batch. En 2022 avec l'arrivée du **Quarto**, et le nouveau noyau Jupyter **`nbstata`** de **Tim Huegerich**, on dispose d'une solution particulièrement efficace d'édition pour ce logiciel. --- <hr class="hr"> * Documentation nbstata: <https://github.com/hugetim/nbstata> * Prérequis: * Stata 17 minimum * Version récente de Python * Notebook Jupyter * Installation du kernel **nbstata** Avant de débuter ce tutoriel, concernant les avantages et les inconvénients d'utiliser le notebook Jupyter: * Les graphiques sont affichés sous le programme et non dans une fenêtre externe. * Le programme est exécuté dans des cellules de codes et non dans un éditeur de programme. Avec Jupyter, les macros temporaires restent enregistrées d'une cellule de codes à une autre. C'est plutôt pratique pour construire un programme pas à pas sans avoir à exécuter systématique les parties qui déclarent les macros temporaires en amont. * Le noyau `nbstata` permet d'enregistrer l'ensemble des cellules dans un fichier .do. * Niveau inconvénient ou limite d'utilisation. Les notebooks ne permettent pas d'afficher à la volée la base de données ou la frame active. Son utilisation n'est donc pas forcément adaptée au traitement et à la manipulation d'une base de données. # Installation de Jupyter Une fiche est déjà disponible [[Lien](https://mthevenin.github.io/assistoolsms/R/assist/posts/R_jupyter/R_jupyter.html#installation)]. A l'Ined l'installation est largement facilité avec l'outil **applined** développé par le service informatique. Pour vérifier que tout est bien installé: - Vérification pour Python: dans Stata, exécuter **`python query`**, et éventuellement tester une opération simple: **`python: 1+1`** - Vérification pour Jupyter: pour lancer le notebook, dans l'invite de commande windows (cmd dans la barre de recherche), exécuter **`jupyter notebook`** :::: {.center} ::: {.column width="65%"} ::: {.box_img} ![](anim1.gif) ::: ::: :::: # Installation de nbstata Les étapes sont bien décrites dans le document de Tim Huegerich. Dans l'invite de commande windows exécuter successivement ```{.mf} pip install nbstata ``` Puis à minima: ```{.mf} python -m nbstata.install ``` Optionnellement, si on souhaite récupérer la couleur syntaxique ```{.mf} pip install jupyterlab_stata_highlight2 ``` # Utilisation de nbstata dans un notebook Jupyter * Dans *new* on choisit le kernel nbstata * Une fois le noyau chargé on peut exécuté dans les cellules une plusieurs lignes de programme. * Si on souhaite écrire du texte, on change le format de la cellule qui est par défaut *code*. * Pour afficher l'aide par exemple, on utilise un magik: `%help nom_commande`. La liste des magiks est donnée dans la documentation. * Contrairement à l'exécution de Stata dans son interface, les macro temporaires (`local`) sont conservées en mémoire d'une cellule à une autre. * On peut enregistrer l'ensemble des cellules en mode *code* dans un fichier .do En résumé: :::: {.center} ::: {.column width="65%"} ::: {.box_img} ![](anim2.gif) ::: ::: :::: <br> Remarque: on peut installer le notebook Jupyter dans VScode. On peut donc l'utiliser comme interface pour documenter un programme au lieu d'un navigateur Web. En revanche, il ne sera pas possible de récupérer un .do à partir des commandes exécuter dans les cellules. # Utilisation de **nbstata** dans un document Quarto * On indique de le header de la page (yaml) l'utilisation de jupyter et du noyau nbstata ```{.yaml} --- title: "Exécution de Stata sous Quarto avec nbstata jupyter: nbstata --- ``` * Pour le bloc de codes sans option: on indique qu'on utilise stata: ` ```{stata}` * Pour le bloc de codes avec option(s), on remplace `#|` (R,Python) par `*|`: ```{.mf} *| echo: false/true *| eval: false/true * Programme Stata sysuse auto tx scat price mpg ``` :::: {.center} ::: {.column width="65%"} ::: {.box_img} ![](anim3.gif) ::: ::: ::::