Guide de migration SAS du package Banff#

Dans ce guide#

Le public cible de ce guide est constitué des utilisateurs de Banff 2.08.002 basé sur SAS ou d’une version antérieure qui migrent vers Banff 3.x basé sur Python. Il résume les informations sur les modifications apportées dans la version 3, y compris les nouveaux noms des paramètres et des tables, ainsi que des exemples de la manière dont les programmes SAS qui appellent des procédures Banff peuvent être convertis en programmes Python équivalents.

Ce document n’est pas destiné aux nouveaux utilisateurs de Banff car il ne fournit pas un aperçu complet des procédures Banff. Veuillez vous référer au Guide de l’utilisateur pour obtenir des détails complets sur l’utilisation de chaque procédure, de ses paramètres et de ses tables.

Table des matières#

Procédures disponibles
Paramètres de procédure
- Tableau des paramètres et types de procédures
- Nouvelles options de procédure
Tables de procédures
- Tableau des identifiants du table de procédure
- Modifications apportées aux tables
Specification des tables
Modifications notables des procédures
- Modifications apportées aux tables d’entrée
- Modifications apportées aux tables de sortie
Autres options d’exécution Python
Considérations relatives aux performances
Erreurs et exceptions
Fonctions utilitaires

Procédures disponibles#

Pour obtenir la liste des procédures disponibles, consultez le Guide de l’utilisateur.

Chaque procédure a été convertie en prenant le code source de la procédure Banff 2.08.002 dépendant de SAS et en le modifiant pour produire une procédure code source ouvert, qui est “encapsulée” dans un paquet Python. Les calculs mathématiques sous-jacents restent inchangés.

En raison des différences entre SAS et Python, les utilisateurs doivent adapter la façon dont ils spécifient les paramètres et les tables ; les ensembles de paramètres et de tables restent en grande partie inchangés (bien que la plupart des identifiants de paramètres et des identifiants de table aient changé).

Paramètres de procédure#

De nombreux noms de paramètres ont été modifiés pour mieux suivre les conventions de dénomination Python courantes.

Les identifiants utilisés dans les programmes SAS correspondent aux identifiants et types Python suivants:

Tableau des paramètres et types de procédures#

Identifiant SAS	Identifiant Python	Type Python	Remarque
`ACCEPTNEGATIVE`	`accept_negative`	`bool`
`ACCEPTZERO`	`accept_zero`	`bool`
`BETAE`	`beta_e`	`int` or `float`
`BETAI`	`beta_i`	`int` or `float`
`BOUNDSTAT`	`outlier_stats`	`bool`	MODIFIÉ : concerne désormais le contenu de la table `outstatus_detailed`
`BY`	`by`	`str`
`CARDINALITY`	`cardinality`	`int` or `float`
`DATAEXCLVAR`	`data_excl_var`	`str`
`DECIMAL`	`decimal`	`int` or `float`
`DISPLAYLEVEL`	`display_level`	`int` or `float`
`EDITS`	`edits`	`str`
`ELIGDON`	`eligdon`	`str`
`EXPONENT`	`exponent`	`int` or `float`
`EXTREMAL`	`extremal`	`int` or `float`
`HISTEXCLVAR`	`hist_excl_var`	`str`
`ID`	`unit_id`	`str`
`IMPLY`	`imply`	`int` or `float`
`LOWERBOUND`	`lower_bound`	`int` or `float`
~~`MATCHFIELDSTAT`~~	~~`match_field_stat`~~	~~`bool`~~	OBSOLÈTE : utilisez plutôt la table de sortie `outmatching_fields`
`MAXCARDINALITY`	`extremal`	`int` or `float`
`MAXIMPLIEDEDITS`	`imply`	`int` or `float`
`MDM`	`mdm`	`int` or `float`
`MEI`	`mei`	`int` or `float`
`METHOD`	`method`	`str`
`MII`	`mii`	`int` or `float`
`MINDONORS`	`min_donors`	`int` or `float`
`MINOBS`	`min_obs`	`int` or `float`
`MODIFIER`	`modifier`	`str`
`MRL`	`mrl`	`int` or `float`
`MUSTIMPUTE`	`must_impute`	`str`
`MUSTMATCH`	`must_match`	`str`
`N`	`n`	`int` or `float`
`NLIMIT`	`n_limit`	`int` or `float`
`NOBYSTATS`	`no_by_stats`	`bool`
`OUTLIERSTAT`	`outlier_stats`	`bool`	MODIFIÉ : concerne désormais le contenu de la table `outstatus_detailed`
`PCENTDONORS`	`percent_donors`	`int` or `float`
`POSTEDITS`	`post_edits`	`str`
`RANDNUMVAR`	`rand_num_var`	`str`
`RANDOM`	`random`	`bool`
~~`REJECTNEGATIVE`~~	~~`reject_negative`~~	~~`bool`~~	OBSOLÈTE : spécifiez plutôt `accept_negative=False`
~~`REJECTZERO`~~	~~`reject_zero`~~	~~`bool`~~	OBSOLÈTE : spécifiez plutôt `accept_zero=False`
`SEED`	`seed`	`int` ou `float`
`SIDE`	`side`	`str`
`SIGMA`	`sigma`	`str`
`STARTCENTILE`	`start_centile`	`int` ou `float`
`TIMEPEROBS`	`time_per_obs`	`int` ou `float`
`UPPERBOUND`	`upper_bound`	`int` ou `float`
`VAR`	`var`	`str`
`VERIFYEDITS`	`verify_edits`	`bool`
`VERIFYSPECS`	`verify_specs`	`bool`
`WEIGHT`	`weight`	`str`
`WEIGHTS`	`weights`	`str`
`WITH`	`with_var`	`str`

Exemple de spécification de paramètres en Python#

Le code suivant montre comment spécifier différents types Python associés à certains paramètres courants.

foo = banff.donorimp(
    min_donors=2,
    percent_donors=0.1,
    accept_negative=True,
    edits="""x1>=-5; 
    x1<=15; 
    x2>=30; 
    x1+x2<=50;""",
    by="province city",
    unit_id='IDENT',
    trace=True,
    # ... etc. (tables)
)

Exemple de spécification de paramètres SAS

proc donorimputation
    /* etc. (tables) ... */
    mindonors=2
    pcentdonors=0.1
    acceptnegative
    edits="x1>=-5; 
    x1<=15; 
    x2>=30; 
    x1+x2<=50;"
    ;
    by province city;
    id IDENT;
run;

paramètre	note
`unit_id`	Un seul nom de variable
`by`	une liste de 0 ou plusieurs noms de variables séparés par des espaces
`cardinality`	exclut un nombre, voir le guide d’utilisation pour obtenir des conseils
`time_per_obs`	s’attend à un nombre, voir le guide d’utilisation pour obtenir des conseils
`accept_negative`	boolean: `True`-> spécifié, <non spécifié> -> non spécifié
`edits`	envelopper les chaînes multilignes avec des guillemets triples (`"""edit>=string"""`)

Nouvelles options de procédure#

Les nouvelles options incluent

exclude_where_indata
exclude_where_indata_hist
prefill_by_vars
presort
trace

Option `exclude_where_indata`#

Cette option exclut les enregistrements en fonction d’une expression SQL spécifiée par l’utilisateur. Pour plus de détails, consultez la documentation spécifique à la procédure.

Option `exclude_where_indata_hist`#

Cette option exclut les enregistrements basés sur une expression SQL spécifiée par l’utilisateur. Pour plus de détails, consultez la documentation spécifique à la procédure.

estimator

Option `prefill_by_vars`#

Cette option est disponible et activée par défaut dans toutes les procédures qui acceptent une table instatus. Voir Guide de l’utilisateur

Option `presort`#

Cette option est disponible et activée par défaut dans toutes les procédures qui acceptent des tables d’entrée. Voir Guide de l’utilisateur

Option `trace`#

Cette option est disponible dans toutes les procédures et contrôle la verbosité du journal de la console. Voir Guide de l’utilisateur

Tables de procédures#

De nombreux noms de paramètres de table ont été modifiés pour mieux suivre les conventions de dénomination Python courantes.

Les identifiants utilisés dans les programmes SAS correspondent aux identifiants suivants dans Python :

Tableau des identifiants du table de procédure#

Identifiant SAS	Identifiant Python	Remarque
`ALGORITHM`	`inalgorithm`
`AUX`	`indata_hist`	pas d’option “AUX” en Python, utilisez plutôt `indata_hist`
`DATA`	`indata`
`DATASTATUS`	`instatus`
`DONORMAP`	`outdonormap`
`ESTIMATOR`	`inestimator`
`HIST`	`indata_hist`
`HISTSTATUS`	`instatus_hist`
`INSTATUS`	`instatus`	nouveau: désormais accepté par la procédure `errorloc`, voir Ajout de instatus à Errorloc
`OUT`	`outdata`
`OUTACCEPTABLE`	`outacceptable`
`OUTDATA`	`outdata`
`OUTEDITAPPLIC`	`outedit_applic`
`OUTEDITSTATUS`	`outedit_status`
`OUTGLOBALSTATUS`	`outglobal_status`
`OUTKEDITSSTATUS`	`outk_edits_status`
`OUTRANDOMERROR`	`outrand_err`
`OUTREDUCEDEDITS`	`outedits_reduced`
`OUTESTEF`	`outest_ef`
`OUTESTLR`	`outest_lr`
`OUTESTPARMS`	`outest_parm`
`OUTVARSROLE`	`outvars_role`
`OUTREJECT`	`outreject`
`OUTSTATUS`	`outstatus`	nouveau: désormais produit par la procédure `massimp`, voir Ajout de outstatus à l’imputation de masse
`OUTSUMMARY`	`outsummary`
`STATUS`	`instatus`
Added in Banff 3.1.1	`outstatus_detailed`	produit par `outlier`, voir Modifications du statut Outlier Outstatus
Added in Banff 3.1.1	`outmatching_fields`	produit par `donorimp`, voir Modifications apportées au statut d’imputation par donneur

Modifications apportées aux tables#

Un aperçu des modifications est fourni dans les sous-sections suivantes, avec des liens vers des informations détaillées. Pour une liste complète des informations détaillées, voir Modifications notables des procédures.

Suppression des variables `by`#

Les variables by ont été supprimées de nombreuses tables de sortie. Voir BY Variables sur les tables de sortie pour plus de détails.

Normalisation de la table `outstatus`#

voir aussi Tables de sortie > outstatus

La table « outstatus » est désormais standardisée dans toutes les procédures qui la produisent. De nouvelles tables de sortie ont été introduites dans les procédures Donor Imputation, Mass Imputation et Outlier pour prendre en compte ce changement.

Ajout de la table `instatus`#

La procédure Errorloc accepte désormais une table instatus.

Spécification des tables#

Pour plus d’informations sur la spécification des tables d’entrée et de sortie, les formats pris en charge, etc., veuillez consulter le Guide de l’utilisateur

Modifications notables des procédures#

Modifications apportées aux tables d’entrée#

Ajout de `instatus` à la procédure Errorloc#

Errorloc accepte désormais une table instatus.

La procédure Errorloc traite sa table instatus de manière quelque peu différente des autres procédures. Pour favoriser la sélection des champs marqués pour imputation, pour chaque ligne dans instatus avec un indicateur d’état de FTI, la valeur correspondante dans indata sera traitée comme si elle était manquante.

Modifications apportées aux tables de sortie#

Variables BY sur les tables de sortie#

Dans les procédures basées sur SAS, les variables « by » étaient incluses dans de nombreuses tables de sortie essentiellement par défaut à chaque fois qu’un traitement par groupe était effectué. Dans Banff 3.1.1 cependant, les variables « by » ne sont incluses que dans les tables suivantes:

Estimator
- outacceptable
- outest_ef
- outest_lr
- outest_parm
- outrand_err
Outlier
- outsummary

Normalisation des tables `outstatus`#

Toutes les tables « outstatus » sont désormais normalisées et contiennent exactement les colonnes suivantes

Nom de la colonne	Remarque
`<unit-id>`	colonne nommée d’après la colonne `unit_id` de la table `indata`
`FIELDID`	nom de la colonne à laquelle s’applique le statut
`STATUS`	le code d’état
`VALUE`	valeur de la variable à laquelle s’applique le statut*

*Colonne VALUE Pour les procédures qui produisent une table outdata, la valeur provient de là. Sinon, la valeur provient de la table indata.

De plus, les informations non relatives au statut produites auparavant par les procédures Imputation par donneur et Outlier ont été supprimées. Voir ci-dessous pour plus d’informations.

Modifications apportées à Imputation par donneur `outstatus`#

Imputation par donneur génère désormais une table outstatus standardisée. Les données qui ont été supprimées de outstatus sont disponibles dans la nouvelle table de sortie facultative outmatching_fields. Cette nouvelle table est désactivée par défaut. Spécifiez True ou toute autre option de sortie valide pour l’activer. Cette nouvelle table remplace l’option match_field_stat, qui est désormais obsolète.

Ajout de `outstatus` à la procédure d’Imputation de masse#

Imputation de masse produit une table outstatus avec l’indicateur IMAS.

Modifications apportées à Outlier `outstatus`#

Outlier génère désormais une table outstatus standardisée. Les données qui ont été supprimées de outstatus sont disponibles dans la nouvelle table facultative outstatus_detailed. Cette nouvelle table contient les variables <unit_id>, FIELDID, OUTLIER_STATUS (anciennement OUTSTATUS, à ne pas confondre avec la variable status de la table oustatus) et toutes les variables activées en spécifiant outlier_stats=True. La table est activée par défaut. Spécifiez False pour la désactiver.

Autres options d’exécution Python#

Prise en charge de la langue maternelle#

Banff produit un journal qui peut afficher des messages en anglais ou en français. Pour plus de détails, consultez la section paramétrage de la langue du journal du guide de l’utilisateur.

Option `capture`#

Lors de l’exécution dans Jupyter Notebooks, certains messages de journal peuvent être manquants. La spécification de capture=True dans un appel de procédure peut résoudre le problème. Pour plus de détails, consultez suppression et dépannage des messages de journal dans le guide de l’utilisateur.

Considérations relatives aux performances#

Certaines options et formats de tableau peuvent offrir des performances optimales. Pour plus de détails, consultez Considérations relatives aux performances.

Erreurs et exceptions#

Les erreurs sont traitées différemment dans SAS et dans Python, où elles sont appelées exceptions. Pour plus de détails, consultez Erreurs et exceptions dans le guide de l’utilisateur.

Fonctions utilitaires#

Travailler avec des fichiers SAS en Python#

Le paquet banff fournit quelques fonctions utiles pour lire des fichiers SAS en Python. Pour plus de détails, consultez Travailler avec des fichiers SAS dans Python dans le guide de l’utilisateur.