Commande RCOMMAND

Transmet une table Analytics à un script R externe sous forme de cadre de données et crée une nouvelle table dans le projet Analytics à l'aide de la sortie du script R externe.

Syntaxe

RCOMMAND FIELDS champ<...n> RSCRIPT chemin_vers_script TO nom_table <IF test> <WHILE test> <FIRST plage|NEXT plage> <KEEPTITLE> <SEPARATOR caractère> <QUALIFIER caractère> <OPEN>

Paramètres

Nom Description
FIELDS nom_champ <...n>

Champs ou expressions de la table Analytics source à inclure dans le cadre de données envoyé au script R.

Selon l'édition d'Analytics que vous utilisez, il se peut que vous rencontriez des erreurs lors de l'envoi de données contenant certains caractères spéciaux vers R :

  • non Unicode "\"
  • Unicode "ÿ" ou "Ŝ"

  • Les deux boîtes de dialogue écrivant des caractères comme des blocs, des carrés noirs et des barres verticales discontinues

Remarque

Les données de langues mixtes ne sont pas prises en charge, comme une table contenant à la fois des caractères japonais et des caractères chinois.
RSCRIPT chemin_vers_script

Chemin d'accès complet ou relatif au script R sur le système de fichiers. Entourez chemin_vers_script de guillemets.
TO nom_table

Emplacement vers lequel envoyer les résultats de la commande :

  • nom_table enregistre les résultats dans une table Analytics

    Indiquez nom_table sous forme de chaîne entre guillemets avec une extension de fichier .FIL. Par exemple : TO "Sortie.FIL"

    Par défaut, le fichier de données de table (.FIL) est enregistré dans le dossier contenant le projet Analytics.

    Utilisez un chemin de fichier absolu ou relatif pour enregistrer le fichier de données dans un autre dossier existant :

    • TO "C:\Sortie.FIL"
    • TO "Résultats\Sortie.FIL"

    Remarque

    La longueur des noms des tables est limitée à 64 caractères alphanumériques, sans l'extension .FIL. Le nom peut inclure le caractère de soulignement ( _ ), mais aucun autre caractère spécial ni espace. Le nom ne peut pas commencer par un chiffre.

La table de sortie est créée à partir du cadre de données ou de la matrice que le script R renvoie.
IF test

optionnel

 Condition devant être remplie pour que l'enregistrement actuel soit traité. Le cadre de données transmis au script R contient uniquement les enregistrements qui remplissent la condition.
WHILE test

optionnel

Expression conditionnelle qui doit être vraie afin de traiter chaque enregistrement. La commande est exécutée jusqu'à ce que la condition soit évaluée comme fausse ou lorsque la fin de la table est atteinte.

Remarque

Si vous utilisez WHILE conjointement avec FIRST ou NEXT, le traitement des enregistrements s'arrête dès qu'une limite est atteinte.
FIRST plage | NEXT plage

optionnel

Le nombre d'enregistrements à traiter :

  • FIRST pour commencer le traitement à partir du premier enregistrement jusqu'à ce que le nombre d'enregistrements spécifié soit atteint
  • NEXT pour commencer le traitement à partir de l'enregistrement actuellement sélectionné jusqu'à ce que le nombre d'enregistrements spécifié soit atteint

Utilisez plage pour indiquer le nombre d'enregistrements à traiter.

Si vous ignorez FIRST et NEXT, tous les enregistrements sont traités par défaut.

Attention

Dans la version actuelle, il existe un problème connu avec NEXT lors de l'exécution de RCOMMAND. Éviter d'utiliser cette option comme référence d'enregistrement peut rétablir la valeur sur le premier enregistrement quel que soit l'enregistrement sélectionné.
KEEPTITLE

optionnel

Traitez la première ligne de données en tant que noms de champs plutôt que comme données. Si vous ignorez ce paramètre, les noms des champs génériques sont utilisés.

Cette option est requise si vous souhaitez récupérer les données à l'aide des noms des colonnes dans le script R.
SEPARATOR caractère

optionnel

Caractère à utiliser comme séparateur de champs. Vous devez indiquer le caractère sous forme de chaîne entre guillemets.

Le caractère par défaut est une virgule.

Remarque

Évitez d'utiliser des caractères qui apparaissent dans les champs d'entrée. Si le caractère SEPARATOR apparaît dans les données d'introduction, les résultats peuvent être affectés.
QUALIFIER caractère

optionnel

Caractère à utiliser en tant qu'identificateur de texte pour renvoyer à la ligne et identifier des valeurs de champs. Vous devez indiquer le caractère sous forme de chaîne entre guillemets.

Le caractère par défaut est un guillemet double.

Remarque

Évitez d'utiliser des caractères qui apparaissent dans les champs d'entrée. Si le caractère QUALIFIER apparaît dans les données d'introduction, les résultats peuvent être affectés.

OPEN

optionnel

Ouvre la table créée par la commande après l'exécution de la commande. Valide uniquement lorsque la commande crée une table de sortie.

Exemples

Faire fonctionner R (Hello world)

Vous créez un script « hello world » pour tester votre connexion entre Analytics et R :

Commande Analytics

RCOMMAND FIELDS "Bonjour"; ", le monde !" TO "r_résultat" RSCRIPT "C:\scripts\r_scripts\analyse.r"

Script R (analyse.r)

srcTable<-acl.readData()

# créer une table à renvoyer dans ACL
output<-data.frame(
  c(srcTable[1,1]),
  c(srcTable[1,2])
)

# ajouter les noms des colonnes et renvoyer la table dans ACL
colnames(output) <- c("Bonjour";"Objet")
acl.output<-output

Accès aux données des champs à l'aide des coordonnées des lignes et des colonnes

Vous envoyez un certain nombre de champs facture à un script R pour les faire analyser en dehors d'Analytics :

Commande Analytics

RCOMMAND FIELDS Code_Département Montant_Facture Date_Facture Numéro_Facture Numéro_fournisseur TO "r_résultat" RSCRIPT "C:\scripts\r_scripts\analyse.r"

Script R (analyse.r)

# Récupère le numéro de facture de la deuxième ligne du cadre de données dans le script R
srcTable<-acl.readData()
srcTable[2,4]

Accès aux données des champs à l'aide des noms de colonnes

Vous envoyez un certain nombre de champs facture à un script R pour les faire analyser en dehors d'Analytics. Vous utilisez l'option KEEPTITLE pour que les colonnes puissent être référencées par nom dans R :

Commande Analytics

RCOMMAND FIELDS Code_Département Montant_Facture Numéro_Facture TO "r_résultat" RSCRIPT "C:\scripts\r_scripts\analyse.r" KEEPTITLE

Script R (analyse.r)

# Récupère le numéro de facture de la deuxième ligne du cadre de données dans le script R
srcTable<-acl.readData()
srcTable["2","Numéro_Facture"]

Envoi des enregistrements de factures dépassant une valeur de 1000,00 au script R

Vous envoyez un certain nombre de champs facture à un script R pour les faire analyser en dehors d'Analytics. Vous utilisez IF pour limiter le nombre d'enregistrements envoyés à R. Seuls les enregistrements dont le montant des factures dépasse 1000,00 sont envoyés :

Commande Analytics

RCOMMAND FIELDS Code_Département Montant_Facture Numéro_Facture TO "r_résultat" IF Montant_Facture > 1000,00 RSCRIPT "C:\scripts\r_scripts\analyse.r" KEEPTITLE

Script R (analyse.r)

# Récupère le numéro de facture de la deuxième ligne du cadre de données dans le script R
srcTable<-acl.readData()
srcTable["2","Numéro_Facture"]

Envoi des enregistrements des factures et renvoi des montants de facture multipliés

Vous envoyez un certain nombre de champs facture à un script R pour les faire analyser en dehors d'Analytics. Le script R effectue une seule action par rapport à chaque cellule dans la colonne nommée :

Commande Analytics

RCOMMAND FIELDS Code_Département Montant_Facture Numéro_Facture TO "r_résultat" RSCRIPT "C:\scripts\r_scripts\analyse.r" KEEPTITLE

Script R (analyse.r)

# Renvoie une section de table ACL avec la valeur doublée
srcTable<-acl.readData()
acl.output<-srcTable["Montant_Facture"] * 2

Remarques

Remarque

Pour plus d'informations sur le fonctionnement de cette commande, consultez le Aide d'Analytics.

Référence à des données Analytics dans le script R

La table Analytics est transmise au script sous forme de cadre de données R. Les cadres de données sont des objets de données tabulaires pouvant contenir des colonnes de différents modes - ou types - de données.

Pour utiliser le cadre de données créé par Analytics dans un script R, appelez la fonction acl.readData() et stockez le cadre de données renvoyé dans une variable :

# stocke la table Analytics dans un cadre de données appelé maTable qui peut être référencé tout au long du script
maTable<-acl.readData()

Pour extraire les données d'une cellule dans le cadre de données, vous pouvez utiliser l'une des approches suivantes :

  • Utilisation des coordonnées de ligne et de colonne :

    # Extrait la valeur dans la première ligne et la deuxième colonne du cadre de données
maTable[1,2]

    Remarque

    Les coordonnées dépendent de l'ordre des champs indiqué dans la commande et non du format de table ou de la vue ouverte.

  • À l'aide des noms de ligne et de colonne :

    # Extrait la valeur de la première ligne et de la colonne « monTitreColonne » du cadre de données
maTable["1";"monTitreColonne"]

    Vous devez indiquer l'option KEEPTITLE de la commande pour utiliser les noms de table.

    Les lignes sont intitulées « 1 », « 2 », « 3 » et incrémentées en conséquence. Vous pouvez également utiliser une combinaison de noms et de coordonnées.

Retransmission de données vers Analytics

Pour renvoyer un cadre de données ou une matrice dans Analytics et créer une nouvelle table, utilisez la syntaxe suivante :

# Retransmet le cadre de données de maNouvelleTable à Analytics pour créer une nouvelle table 
acl.output<-maNouvelleTable

Remarque

Vous devez renvoyer un cadre de données ou une matrice à Analytics lorsque le script R se termine. Assurez-vous que les colonnes du cadre de données ou de la matrice contiennent uniquement des valeurs atomiques et non des listes, des matrices, des tableaux ou des objets non atomiques. Si les valeurs ne peuvent pas être traduites en types de données Analytics, la commande échoue.

Mappages des types de données

Les types de données Analytics sont traduits en types de données R à l'aide d'un processus de traduction entre le projet Analytics et le script R :

Type de données Analytics Type(s) de données R
Logique Logique
Numérique Numérique
Caractère Caractère
DateHeure Date, POSIXct, POSIXlt

Limitation des performances et des tailles de fichiers

La durée d'exécution du script R et du traitement des données renvoyées est rallongée pour les données d'entrée supérieures à 1 Go. R ne prend pas en charge les fichiers d'entrée de 2 Go ou plus.

Le nombre d'enregistrements envoyés dans R influence aussi les performances. Dans le cas de deux tables présentant une taille de fichier identique mais un nombre d'enregistrements différent, le traitement de la table contenant le moins d'enregistrements sera plus rapide.

Gestion de données de type caractères multi-octets

Si vous envoyez des données à R dans un jeu de caractères multioctets, comme le chinois, vous devez définir le système local de manière approprié dans votre script R. Pour réussir l'envoi d'un table contenant des données multioctets à R, la première ligne du script R doit contenir la fonction suivante :

# Exemple qui définit les paramètres régionaux en chinois
Sys.setlocale("LC_ALL";"Chinois")

Pour obtenir plus d'informations sur Sys.setlocale( ), voir la documentation R.

Fichier trace R

Analytics enregistre les messages en langage R dans un fichier aclrlang.log dans le dossier de projet. Utilisez ce fichier trace pour le débogage des erreurs R

Astuce

Ce fichier trace se trouve dans le dossier de résultats des tâches analytiques d'Analytics Exchange.

Exécution de scripts R sur AX Serveur

Si vous rédigez une App Analyse à exécuter sur AX Serveur et que vous souhaitez travailler sur des scripts R externes :

  1. Chargez le fichier sous forme de fichier associé à l'App Analyse.
  2. Utilisez la balise d'analyse FILE pour identifier le(s) fichier(s).
  3. Faites référence au(x) fichier(s) à l'aide du chemin d'accès relatif ./nom_fichier.r.

Remarque

L'utilisation d'un fichier associé garantit que le compte du serveur d'application TomEE dispose des autorisations suffisantes pour accéder au fichier lors de l'exécution de R avec Analytics Exchange.