Fichiers de métadonnées

Au total, le processeur Banff utilise 18 tables de métadonnées, qui peuvent être classées comme suit:

Tables décrivant le déroulement global du processus:

• JOBS (obligatoire): définit le flux global du processus, y compris les étapes du processus à exécuter et le séquençage

• PROCESSCONTROLS: les contrôles de processus facultatifs donnent plus de contrôle sur les étapes individuelles du processus

Tables définissant les paramètres des étapes de processus pour les procédures Banff intégrées:

• VERIFYEDITSPECS: spécifications pour la procédure verifyedits

• OUTLIERSPECS: spécifications pour la procédure outlier

• ERRORLOCSPECS: spécifications pour la procédure errorloc

• DONORSPECS: spécifications pour la procédure donorimp

• ESTIMATORSPECS: spécifications pour la procédure estimator

• ESTIMATORS: paramètres supplémentaires pour la table inestimator

• ALGORITHMS: paramètres supplémentaires pour la table inalgorithm

• PRORATESPECS: spécifications pour la procédure prorate

• MASSIMPUTATIONSPECS: spécifications pour la procédure massimp

Tables utilisées pour définir les modifications, utilisées par les procédures verifyedits,editstats,errorloc,deterministic,donorimp et prorate:

• EDITS: Liste des modifications individuelles

• EDITGROUPS: Combinaisons de modifications référencées par des étapes de processus individuelles

Paramètres utilisés par plusieurs procédures:

• VARLISTS: Listes de variables et ordre de tri

• WEIGHTS: Poids, utilisés par certaines procédures

• EXPRESSIONS: Expressions d’exclusion utilisées par certaines procédures

Paramètres des étapes de processus pour les procédures définies par l’utilisateur:

• USERVARS: Spécifications pour les procédures définies par l’utilisateur (plugins)

Gestion des données:

• PROCESSOUTPUTS: Spécifiez les sorties à enregistrer pour chaque procédure

Remarques générales

• Les champs de métadonnées d’ID tels que jobid ou controlid peuvent comporter jusqu’à 100 caractères

• Les noms de variables sur vos ensembles de données d’entrée peuvent comporter jusqu’à 64 caractères.

• Sensibilité à la casse: la cohérence doit être maintenue entre les métadonnées en ce qui concerne la casse. Cela inclut la correspondance des champs tels que specID et controlID ainsi que des noms de variables.

• Les noms de variables doivent respecter la casse des noms de colonnes sur l’entrée applicable. Dans certains contextes, revenu et INCOME peuvent être considérés comme des variables différentes sur une table, mais dans d’autres, ils ne le sont pas. Par exemple, les expressions metadata ne sont pas sensibles à la casse. Pour cette raison, il est recommandé de ne pas réutiliser les noms de colonnes simplement avec une casse différente et de respecter la casse dans les fichiers de données et de métadonnées.

Jobs

Définissez vos flux de processus d’édition de données statistiques.

Colonne	Type	Clé primaire	Clé étrangère	Obligatoire	Description
jobid	string	✔		✔	La valeur de la colonne jobid est utilisée pour extraire de la table toutes les lignes appartenant à la même stratégie E&I ou au même bloc de processus.
seqno	float	✔		✔	L’ordre d’exécution est défini par la colonne seqno qui est lue de la valeur la plus basse à la plus grande. Le processeur Banff s’exécutera même s’il y a des écarts dans les valeurs seqno. Par exemple, une valeur de SEQNO=10 peut être suivie dans la ligne suivante par une valeur de 20.
controlid	string		✔		Pointe vers un ID défini dans la table de métadonnées ProcessControls.
process	string		✔	✔	La valeur de la colonne de processus identifie le nom de la procédure ou du plug-in Banff à exécuter.
specid	string		✔	✔	La colonne specid pointe vers un ID dans d’autres tables de métadonnées en fonction de la valeur de la colonne PROCESS.
editgroupid	string		✔		La colonne editgroupid pointe vers une entrée dans la table de métadonnées EditGroups.
byid	string		✔		La colonne byid pointe vers la table de métadonnées VarLists. Elle peut être utilisée par toutes les procédures à l’exception de VerifyEdits et du processus Job. La liste de variables indiquée sera utilisée pour le traitement par groupe.
acceptnegative	string				La colonne acceptnegative est utilisée pour indiquer si les valeurs négatives sont considérées comme des valeurs valides ou non par le processus. Si elle n’est pas spécifiée (laissée vide) ou si la valeur est N, l’option accept negative ne sera pas spécifiée, sinon (si la valeur de la colonne est Y), l’option accept negative sera définie sur True.

ProcessControls

Définir les spécifications des contrôles de processus.

Column	Type	Primary Key	Foreign Key	Required	Description
controlid	string	✔		✔	ID utilisé pour identifier le contrôle.
targetfile	string	✔		✔	Le nom du fichier de jeu de données auquel appliquer le contrôle. Ce champ n’est PAS obligatoire si parameter=EDIT_GROUP_FILTER.
parameter	string	✔		✔	Le type de contrôle de processus à appliquer.
value	string			✔	La requête (dans la syntaxe SQL-lite) à appliquer pour ce contrôle. Ce champ n’est pas obligatoire et doit être vide si parameter=EDIT_GROUP_FILTER.

Edits

Définissez les modifications de cohérence linéaire à utiliser par les procédures Banff.

Column	Type	Primary Key	Foreign Key	Required	Description
editid	string	✔		✔	ID utilisé pour identifier la modification.
leftside	string			✔	Le côté gauche de l’équation.
operator	string			✔	L’opérateur, les valeurs valides incluent >, >=, <, <=, = et !=.
rightside	string			✔	Le côté droit de l’équation.
modifier	string				La valeur du modificateur. La valeur par défaut de PASS indique que l’équation doit être True, FAIL peut être spécifié pour indiquer que l’équation doit être fausse. ACCEPTE et REJET sont également des valeurs valides et peuvent être utilisées à la place de PASS et FAIL respectivement.

EditGroups

Définir des ensembles de modifications à référencer par des étapes de processus individuelles.

Colonne	Type	Clé primaire	Clé étrangère	Obligatoire	Description
editgroupid	string	✔		✔	ID utilisé pour identifier le groupe de modifications.
editid	string	✔	✔	✔	ID utilisé pour identifier la modification appartenant au groupe.

Expressions

Expressions SQL utilisées pour exclure les donneurs du traitement dans la procédure DonorImp ou les enregistrements à utiliser dans les calculs de la procédure Estimator.

Column	Type	Primary Key	Foreign Key	Required	Description
expressionid	string	✔		✔	L’ID utilisé pour identifier l’expression.
expressions	string			✔	L’expression SQL.

Uservars

Définir les noms et les valeurs des variables de substitution dans les processus définis par l’utilisateur (plugins).

Column	Type	Primary Key	Foreign Key	Required	Description
process	string	✔		✔	Le nom du processus défini par l’utilisateur auquel cette uservar s’applique. Il doit s’agir du même nom (ou de l’un des noms) que celui utilisé lors de l’appel de factory.register() dans la fonction register() requise pour un module UDP.
specid	string	✔		✔	Le specid de l’étape de travail spécifique à laquelle cette uservar s’applique.
var	string	✔		✔	Le nom de cette variable.
value	string			✔	La valeur de la variable. Pour les valeurs numériques, convertissez la valeur de chaîne donnée au format souhaité dans l’UDP à l’aide de cette variable.

Varlists

Répertorie les noms des variables utilisées dans les instructions de procédure qui nécessitent une liste de noms de variables. Tous les noms de variables dans la colonne fieldid qui ont la même valeur que varlistid seront collectés et utilisés avec l’instruction pour laquelle la liste est créée. La variable seqno définit l’ordre dans lequel les variables apparaîtront dans la liste. seqno est obligatoire et est important en particulier pour l’instruction BY.

Column	Type	Primary Key	Foreign Key	Required	Description
varlistid	string	✔		✔	ID utilisé pour identifier la liste de variables.
seqno	float	✔		✔	Définit l’ordre de cet identifiant de champ dans la liste de variables globale de la valeur la plus basse à la plus grande. Les espaces dans la séquence sont autorisés, les nombres doivent simplement former un ordre logique.
fieldid	string			✔	ID utilisé pour identifier ce champ spécifique dans la liste de variables.

Weights

Contient les noms des champs groupés par weightid et la valeur du poids pour chaque champ.

Column	Type	Primary Key	Foreign Key	Required	Description
weightid	string	✔		✔	ID utilisé pour identifier cette pondération.
fieldid	string	✔		✔	Identifie le champ auquel cette pondération s’applique.
weight	float			✔	La valeur de pondération du champ.

ProcessOutputs

Définissez les sorties à conserver pour chaque type de processus. Les métadonnées sont utilisées lorsque process_output_type est défini sur custom.

Column	Type	Primary Key	Foreign Key	Required	Description
process	string	✔		✔	Le nom du processus pour lequel enregistrer ce fichier de sortie.
output_name	string	✔		✔	Le nom de l’ensemble de données à créer et à conserver à la fin du processus spécifié, puis à enregistrer sur le disque à la fin de la tâche globale.

Métadonnées spécifiques aux procédures Banff intégrées

Les tables de métadonnées suivantes sont utilisées pour stocker les paramètres d’entrée des procédures Banff intégrées. Chaque table de métadonnées comprend la colonne specid, qui relie les paramètres spécifiques à la procédure répertoriés dans chaque ligne à l’étape de processus associée dans la table de métadonnées jobs.

• VERIFYEDITSPECS: Spécifications pour la procédure verifyedits

• OUTLIERSPECS: Spécifications pour la procédure outlier

• ERRORLOCSPECS: Spécifications pour la procédure errorloc

• DONORSPECS: Spécifications pour la procédure donorimp

• ESTIMATORSPECS: Spécifications pour la procédure estimator

• ESTIMATORS: Paramètres supplémentaires pour la table inestimator

• ALGORITHMS: Paramètres supplémentaires pour la table inalgorithm

• PRORATESPECS: Spécifications pour la procédure prorate

• MASSIMPUTATIONSPECS: Spécifications pour la procédure massimp

Pour obtenir des informations sur les paramètres des procédures Banff intégrées, veuillez consulter le guide de l’utilisateur Banff dans le référentiel des procédures Banff.

Conseils pour les programmeurs

Des schémas XML sont disponibles pour chaque fichier de métadonnées dans le sous-package banffprocessor.metadata.models. Ces schémas peuvent être utiles à des fins de débogage ou pour les développeurs d’applications qui doivent générer ces fichiers sans utiliser le modèle de métadonnées Excel. Par exemple, le schéma du fichier Algorithms.xml peut être imprimé avec les 2 lignes suivantes pour le code:

from banffprocessor.metadata.models.algorithms import Algorithms

print(Algorithms.get_schema())

Une base de données duckdb est utilisée pour stocker les métadonnées pendant le traitement et peut être exportée à la fin du processus à des fins de débogage ou d’information. La connexion à la base de données est accessible via l’attribut dbconn de votre objet Processor comme illustré dans l’extrait de code ci-dessous:

my_bp = Processor.from_file(input_file)
my_bp.dbconn.execute("EXPORT DATABASE '<chemin vers le dossier pour enregistrer les fichiers exportés>'")

---
title: Diagramme entité-relation des métadonnées du processeur Banff
---
erDiagram
    ALGORITHMS {
        string algorithmname PK
        string type
        string status
        string formula
        string description
    }
    DONORSPECS {
        string specid PK
        int mindonors
        real pcentdonors
        int n
        string eligdon
        boolean random
        int nlimit
        real mrl
        string dataexclvar FK
        string mustmatchid FK
        string posteditgroupid FK
    }
    EDITGROUPS {
        string editgroupid PK
        string editid PK
    }
    EDITS {
        string editid PK
        string leftside
        string operator
        string rightside
        string modifier
        string edit
    }
    ERRORLOCSPECS {
        string specid PK
        real cardinality
        real timeperobs
        string weightid
    }
    ESTIMATORS {
        string estimatorid PK
        int seqno PK
        string fieldid
        string auxvariables
        string weightvariable
        string variancevariable
        real varianceexponent
        string varianceperiod
        boolean excludeimputed
        boolean excludeoutliers
        int countcriteria
        real percentcriteria
        boolean randomerror
        string algorithmname FK    
    }
    ESTIMATORSPECS {
        string specid  PK
        string dataexclvar FK
        string histexclvar FK
        string Estimatorid FK
    }
    EXPRESSIONS {
        string expressionid PK
        string expressions
    }
    MASSIMPUTATIONSPECS {
        string specid
        int mindonors
        real pcentdonors
        boolean random
        int nlimit
        real mrl
        string mustimputeid
        string mustmatchid   
    }
    OUTLIERSPECS {
        string specid PK
        string method
        real mei
        real mii
        real mdm
        real exponent
        int minobs
        string varid
        string withid
        string dataexclvar FK
        real betae
        real betai
        string weight FK
        string sigma
        string side
        real startcentile
        boolean acceptzero
    }
    PRORATESPECS {
        string specid PK
        int decimal
        real lowerbound
        real upperbound
        string modifier
        string method
    }
    USERVARS {
        string process PK
        string specid PK
        string var PK
        string value
    }
    VARLISTS {
        string varlistid PK
        real seqno PK
        string fieldid
    }
    VERIFYEDITSPECS {
        string specid PK
        int imply
        int extremal
    }
    WEIGHTS {
        string weightid PK
        string fieldid  PK
        real weight        
    } 
    PROCESSCONTROLS {
        string controlid PK
        string targetfile PK
        string parameter PK
        string value
    }  
    PROCESSOUTPUTS {
        string process PK
        string output_name PK
    }
    JOBS {
        string jobid PK
        real seqno PK
        string controlid FK
        string process FK
        string specid FK
        string editgroupid FK
        string byid FK
        boolean acceptnegative
    }
    
    DONORSPECS ||--}o JOBS: "Définit les spécifications"
    ERRORLOCSPECS ||--}o JOBS: "Définit les spécifications"
    ESTIMATORSPECS ||--}o JOBS: "Définit les spécifications"
    OUTLIERSPECS ||--}o JOBS: "Définit les spécifications"
    PRORATESPECS ||--}o JOBS: "Définit les spécifications"
    MASSIMPUTATIONSPECS||--}o JOBS: "Définit les spécifications"
    VERIFYEDITSPECS ||--}o JOBS: "Définit les spécifications"
    USERVARS ||--}o JOBS: "Définit des paramètres personnalisés pour les plugins"

    EDITGROUPS ||--}o JOBS: "Définit le groupe d'édition"
    EDITGROUPS ||--}o DONORSPECS: "Définit le groupe d'édition de post"
    EDITS ||--}o EDITGROUPS: "Définit les groupes d'édition"
    
    ALGORITHMS ||--}o ESTIMATORS: "Définit un algorithme personnalisé"
    ESTIMATORS ||--}o ESTIMATORSPECS: "Définit l'estimateur"
    EXPRESSIONS ||--}o ESTIMATORSPECS: "Définit dataexclvar et histexclvar"
    EXPRESSIONS ||--}o DONORSPECS: "Définit dataexclvar"

    VARLISTS ||--}o JOBS: "Définit les variables utilisées pour créer des groupes de traitement"
    VARLISTS ||--}o DONORSPECS: "Définit mustmatchid"
    VARLISTS ||--}o OUTLIERSPECS: "Définit varid et withid"
    VARLISTS ||--}o MASSIMPUTATIONSPECS: "Defines mustimputeid"
    
    WEIGHTS ||--}o ERRORLOCSPECS: "Définit le poids variable"
    PROCESSCONTROLS ||--}o JOBS: "Définit les contrôles de processus"
    PROCESSOUTPUTS ||--}o JOBS: "Définit les ensembles de données à conserver"