Utiliser des expressions Arcade

ArcGIS Arcade est un langage d’expression portable, léger et sécurisé qui peut exécuter des calculs mathématiques, manipuler du texte et évaluer des instructions logiques. Il prend également en charge les expressions à plusieurs instructions, les variables et les instructions de contrôle du flux. Ce qui différencie particulièrement le langage Arcade des autres langages d’expression et de script est qu’il inclut les types de données d’entité et de géométrie. Arcade est souvent utilisé pour effectuer un calcul avec des champs de couche et une géométrie.

Remarques sur l’utilisation

Si vous utilisez des expressions Arcade, gardez les points suivants à l’esprit :

  • Les expressions Arcade sont prises en charge dans les outils Détecter les incidents, Calculer un champ, Filtrer par expression, Apparier les champs, Joindre les entités, Créer des zones tampon et Reconstruire les traces.
  • Les expressions peuvent comporter des attributs issus des flux en entrée et des sources, ainsi que de valeurs qui décrivent l’analyse dans laquelle l’expression est configurée.
  • Dans le générateur d’expressions, les variables de profil peuvent être développées pour afficher une liste de champs, des valeurs temporelles, des champs cible et des champs de jointure. Les expressions ArcGIS Velocity font appel aux variables de profil suivantes :
    • $feature : dans tous les outils à l’exception de Join Features (Joindre les entités), cette variable contient les champs attributaires des entités en entrée issues des flux et des sources. Des expressions qui utilisent des valeurs attributaires d’entité en sélectionnant des champs de cette variable peuvent être générées.
    • $analytic : cette variable contient des valeurs spécifiques de l’analyse, comme $analytic.AnalyticStartTime et $analytic.AnalyticLastEndTime.
      • Pour convertir ces valeurs de variable d’analyse d’un entier epoch (1646409900000) en une date, utilisez la fonction Date() de Arcade. Pour plus de détails, reportez-vous à la rubrique Fonctions de date de la documentation ArcGIS Arcade.
    • $target : dans l’outil Join Features (Joindre des entités), pour l’expression Join Condition (Condition de jointure), cette variable de profil contient les champs attributaires du flux cible ou de la source.
    • $join : dans l’outil Join Features (Joindre des entités), pour l’expression Join Condition (Condition de jointure), cette variable de profil contient les champs attributaires de la source de jointure.
  • Accédez aux champs et composants de structure dans le générateur d’expressions Arcade.
    • Dans la fenêtre Profile variables (Variables de profil), accédez aux champs, variables et composants de la structure liés à la catégorie (par exemple, $feature, $analytic, $target ou $join).

      Accéder aux champs et variables

    • Permet d’afficher les champs ou variables liés à cette variable.

      Répertorier les champs et variables liés à la catégorie

  • Fournissez vos propres exemples de valeurs pour les tests d’expression Arcade.
    • Arcade fournit des valeurs échantillonnées par défaut pour chaque outil en fonction de la structure entrante. Vous pouvez mettre à jour ces valeurs échantillonnées lorsque vous générez les expressions de chaque outil.
    • Pour ajuster les exemples de valeurs pour les tests d’expression Arcade, procédez comme suit :
      • En fonction de la structure entrante, si vous cliquez pour mettre à jour une expression Arcade, la fenêtre Configure an Arcade expression (Configurer une expression Arcade) s’ouvre.
      • Dans l’onglet $feature, notez que pour chaque champ entrant, une valeur échantillonnée est affichée en fonction de ce type de données. Par exemple, chacun des champs de type chaîne possède l'exemple de valeur Pacific. Pour créer et tester une expression valide pour différents jeux de données, vous devez modifier les valeurs échantillonnées fournies pour un champ afin que l’expression Arcade puisse évaluer l’expression et renvoyer le type de données correct renvoyé par l’expression.

        Accéder à l’onglet $feature pour modifier les valeurs échantillonnées

      • Ajustez la valeur échantillonnée si elle est utilisée dans les tests et évaluations d’expression Arcade.

        Mettre à jour les exemples de valeurs utilisés dans la logique d’expression Arcade

      • Cliquez sur Run (Exécuter) dans le coin supérieur gauche de la fenêtre Configure an Arcade expression (Configurer une expression Arcade) pour exécuter l’expression Arcade. L’expression est évaluée en fonction des données échantillonnées mises à jour fournies.
  • Créez des expressions Arcade capables de gérer les valeurs nulles et les valeurs 0.
    • Dans les opérations mathématiques, le langage d’expression Arcade traite les valeurs nulles comme des valeurs 0 pour l’évaluation. C’est pourquoi les expressions mathématiques Arcade créées dans ArcGIS Velocity doivent tenir compte des valeurs nulles de vos données.
    • Tenez compte des valeurs nulles dans vos données en traitant ces valeurs. Étudiez l’expression $feature.DistanceToFeature <= 5. Il convient de créer cette expression dans le langage Arcade de sorte qu’elle gère les valeurs nulles telles que $feature.DistanceToFeature != null && $feature.DistanceToFeature <= 5. Dans ce type d’expression, <= 5 est une opération mathématique et si la valeur du champ DistanceToFeature est nulle, elle est évaluée comme une valeur 0 compatible avec l’expression.

Exemples d’opérations et de fonctions mathématiques

Les expressions peuvent traiter les nombres mathématiquement. Le tableau ci-dessous présente des exemples d’opérations disponibles. Pour plus d’informations sur les opérations mathématiques dans Arcade, reportez-vous à la rubrique Fonctions mathématiques.

Opérateur

Explication

Exemple

Résultat

a + b

a plus b.

Le champ fieldname (nom du champ) contient la valeur 1,5

$target["fieldname"] + 2.5

4.0

a - b

a moins b.

Le champ fieldname (nom du champ) contient la valeur 3,3

$target["fieldname"]- 2.2

1.1

a * b

a multiplié par b.

Le champ fieldname (nom du champ) contient la valeur 2,0

$join["fieldname"] * 2.2

4.4

a / b

a divisé par b.

Le champ fieldname (nom du champ) contient la valeur 4,0

$join["fieldname"] / 1.25

3.2

abs( a )

Renvoie la valeur absolue (positive) de a.

Le champ fieldname (nom du champ) contient la valeur -1,5

abs($target["fieldname"])

1,5

log( a )

Renvoie le logarithme naturel (base E) de a.

Le champ fieldname (nom du champ) contient la valeur 1

log($join["fieldname"])

0

sin( a )

Renvoie le sinus trigonométrique de a. On suppose que l'entrée est un angle en radians.

Le champ fieldname (nom du champ) contient la valeur 1,5707

sin($target["fieldname"])

1

cos( a )

Renvoie le cosinus trigonométrique de a. On suppose que l'entrée est un angle en radians.

Le champ fieldname (nom du champ) contient la valeur 0

cos($join["fieldname"])

1

tan( a )

Renvoie la tangente de a. On suppose que l'entrée est un angle en radians.

Le champ fieldname (nom du champ) contient la valeur 0

tan($target["fieldname"])

0

sqrt( a )

Renvoie la racine carrée de a.

Le champ fieldname (nom du champ) contient la valeur 9

sqrt($join["fieldname"])

3

min( a, b )

Renvoie la valeur la plus basse entre a et b.

Le champ fieldname (nom du champ) contient les valeurs 1,5 et -3

min($join["fieldname"], -3)

-3

max( a, b )

Renvoie la valeur la plus élevée entre a et b.

Le champ fieldname1 (nom du champ 1) contient la valeur 1,5 et le champ fieldname2 (nom du champ 2) contient la valeur -3

max($target["fieldname1"], $join["fieldname2"])

1,5

constrain(<value>,<low>,<high>)

Renvoie la valeur en entrée si elle est comprise dans les limites de contrainte. Si la valeur en entrée est inférieure à la valeur basse, elle renvoie la valeur basse. Si la valeur en entrée est supérieure à la valeur haute, elle renvoie la valeur haute.

constrain($target["distance"], 0, 10)

constrain($join['Store dist'], 6, distance)

Renvoie 0 si la distance est inférieure à 0, 10 si la distance est supérieure à 10 et la distance dans les autres cas.

Renvoie 6 si la distance du point de vente est inférieure à 6, la distance si la distance du point de vente est supérieure à la distance, et la distance du point de vente dans les autres cas.

L’exemple de multiplication suivant pour une expression de condition de jointure utilisant un champ du jeu de données cible :

$target["Distance"] * 2 > $join["DistField"]

Exemples de fonctions de texte

Les expressions Arcade peuvent traiter du texte. Le tableau ci-dessous présente des exemples d’opérations disponibles. Pour en savoir plus sur les fonctions de texte dans Arcade, reportez-vous à la rubrique Fonctions de texte.

Opérateur

Explication

Exemple

Résultat

concatenate(<values>, <separator>)

Concatène les valeurs et renvoie une chaîne.

  • values : une matrice de valeurs de chaînes à concaténer.
  • separator (facultatif) : séparateur à utiliser pour la concaténation si le paramètre values (valeurs) est une matrice, ou une chaîne à concaténer si une valeur unique est fournie pour le premier paramètre. Si elle n’est pas renseignée, elle sera vide.

Le champ fieldname (nom du champ) contient une valeur ArcGIS Velocity

concatenate([$target["fieldname"], "is", "great!"], ' ')

ArcGIS Velocity est formidable !

find(<searchText>, <text>, <startPos>)

Trouve une chaîne à l’intérieur d’une chaîne. Les caractères génériques ne sont pas pris en charge.

  • searchText : la sous-chaîne à rechercher.
  • text : le texte à rechercher.
  • startPos (facultatif) : l’index en base zéro de l’emplacement dans la chaîne où s’effectue la recherche.

Le champ fieldname1 (nom du champ 1) contient la valeur 14NorthStreet et le champ fieldname2 (nom du champ 2) contient la valeur North

find($target["fieldname2"], $join["fieldname1"])

2

lower(<value>)

Convertit une chaîne en minuscule.

  • value : chaîne à convertir en minuscules.

Le champ fieldname (nom du champ) contient la valeur ANALYTICS

lower($join["fieldname"])

analyse

L’exemple de texte suivant utilise la recherche et inférieur :

find(("north"), lower("146NorthStreet")) == False

Exemples de fonctions de date

Arcade peut traiter des dates. Dans Arcade, les valeurs de mois vont de 0 (janvier) à 11 (décembre), les jours vont de 1 à 31, les heures vont de 0 (minuit) à 23 (23 h), les minutes et secondes vont de 0 à 59 et les millisecondes, de 0 à 999.

Le tableau ci-dessous présente des exemples d’opérations disponibles. Pour en savoir plus sur les fonctions de date dans Arcade, reportez-vous à la rubrique Fonctions de date.

Opérateur

Explication

Exemple

Résultat

date( <value>, <month>, <day>, <hour>, <minute>)

Analyse une valeur ou un ensemble de valeurs dans une chaîne de date.

  • value (facultatif) : nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC ou nombre représentant une année. Si une année est spécifiée, le mois et le jour doivent être également renseignés dans les paramètres suivants. Cette valeur peut également être une chaîne de date ou une chaîne ISO 8601 à convertir en date.
  • month (facultatif) : mois (de 0 à 11), où 0 correspond à janvier et 11 à décembre.
  • day (facultatif) : jour du mois (1 à 31).
  • hour (facultatif) : heure de la journée (0 à 23).
  • minute (facultatif) : minute de l’heure (0 à 59).
  • second (facultatif) : seconde de la minute (0 à 59).
  • millisecond (facultatif) : milliseconde de la seconde (0 à 999).

fieldname contient la valeur 1476987783555.

Exemple 1 : Date($target["fieldname"])

Exemple 2 : Date(2017,0,14,0)

Exemple 3 : Date()

Exemple 1 : 20 oct 2016 11:23:03

Exemple 2 : 14 Jan 2017 00:00:00

Exemple 3 : renvoie l’heure actuelle

DateDiff(<date1>, <date2>, <units>)

Opère une soustraction entre deux dates et renvoie la différence dans les unités spécifiées.

  • date1 : la valeur de date à partir de laquelle on soustrait une deuxième date.
  • date2 : la valeur de date à soustraire de la première date indiquée.
  • startpos (facultatif) : les unités dans lesquelles renvoyer la différence entre les deux dates données. Les unités prises en charge sont les millisecondes, les secondes, les minutes, les heures, les jours, les mois et les années. Les millisecondes sont la valeur par défaut.

Exemple 1 : DateDiff(Date(2017,1,14,0), Date())

Exemple 2 : DateDiff(Date(2017,1,14,0), Date(), "Years")

Le résultat est fonction de la date à laquelle vous exécutez la commande.

Exemple 1 : -20532129137

Exemple 2 : -0,6546783768647119

Year(<dateValue>)

Renvoie l'année de la date donnée.

  • value : une valeur de date à partir de laquelle on récupère l’année.

Exemple 1 : le champ fieldname est un champ de type Date avec la valeur 09 Oct 2017 04:30:43 pm.

Year($join["fieldname"])

Exemple 2 : le champ fieldname est un champ de type chaîne au format chaîne ISO 8601 avec la valeur 2012-09-27.

Exemple 3 : le champ fieldname est un champ de type chaîne au format chaîne ISO 8601 dont la valeur est Year(Date($target["fieldname"])).

Exemple 1 : 2017

Exemple 2 : 2012

Opérateurs conditionnels

Les instructions conditionnelles peuvent utiliser les opérateurs suivants :

Opérateur

Explication

Exemple

Résultats

a > b

a < b

a est supérieur à b.

a est inférieur à b.

10 > 2

False

a >= b

a <= b

a est supérieur ou égal à b.

a est inférieur ou égal à b.

abs(-10) >= 10

True

a != b

a est différent de b.

abs(-3) != -3

True

a == b

a est égal à b.

abs(-5) == 5

True

<condition1> || <condition2>

La condition 1 ou la condition 2 est satisfaite.

(abs(-5) == 5) || (10 < 2)

True

<condition1> && <condition2>

La condition 1 et la condition 2 sont satisfaites.

(abs(-5) == 5) && (10 < 2)

False

L’exemple suivant d’expression de zone tampon utilise des conditions et fonctions avancées :

iif(field1 > field2, iif(field2 = 0, field3, field4), 0)

L’exemple suivant est un exemple de multiplication pour une condition de jointure :

iif(field1 > field2, iif(field2 = 0, field3, field4), 0) > $join["Distance"] * 2

Exemples d’opérateurs logiques

Outre les opérateurs conditionnels, des opérateurs logiques plus avancés peuvent être utilisés pour créer des expressions, comme illustré dans le tableau ci-dessous. Pour en savoir plus sur les fonctions logiques dans Arcade, reportez-vous à la rubrique Fonctions logiques.

Fonction

Explication

Exemple

Résultat

iif(<condition>,<true value>,<false value>)

Renvoie une valeur si une condition est true (vrai) et renvoie une autre valeur si la condition est false (faux).

Les éléments <true value> et <false value> peuvent être :

  • Un champ numérique. Si le nom du champ renferme un espace, utilisez des crochets.
  • Un nombre.
  • Une fonction.

iif($feature["field1"] > $feature["field2"], $feature["field1"], 0)

iif($feature["field1"] > $feature["field2"], iif($feature["field2"] = 0, $feature["field3"], $feature["field4"]), 0)

Renvoie field1 (champ 1) si field1 (champ 1) est supérieur à field2 (champ 2) et 0 dans les autres cas.

Renvoie le résultat de la deuxième fonction iif si field1 (champ 1) est supérieur à field2 (champ 2) et 0 dans les autres cas.

when(<expression1> , <result1> , <expression2> , <result2> , ... , <expressionN> , <resultN>, <default>)

Évalue une série d’expressions dans l’ordre jusqu’à ce que l’une soit true (vrai).

  • expression : une expression.
  • result : résultat de l’expression. Il peut s’agir d’un nombre ou d’un champ.
  • default : une valeur facultative si les expressions ne font l’objet d’aucune correspondance.

when(($feature["field1"] + 10) > 1, 1,($feature["field2"] + 10) > 2 , 2, $feature["field3"])

Si field1 (champ 1) + 10 est supérieur à 1, renvoie 1. Sinon, l’expression vérifie si field2 (champ 2) + 10 est supérieur à 2. Renvoie 2 si c'est le cas. Si ce n’est pas le cas, renvoie field3 (champ 3).

decode(<conditional val> , <case1> , <result1>, <case2>, <result2>, ... <caseN>, <resultN>, <defaultValue> )

Évalue une expression et compare sa valeur aux paramètres suivants. Si l’expression correspond, elle renvoie la valeur du paramètre suivant. Si aucune correspondance n’est trouvée, le dernier paramètre peut être une valeur de renvoi par défaut.

  • conditional val : valeur conditionnelle. Il peut s’agir d’un champ ou d’une expression.
  • case : une valeur à comparer à la valeur conditionnelle.
  • result : le résultat si le cas correspond à la valeur conditionnelle.
  • defaultValue : valeur facultative si aucune autre valeur n’est définie sur true (vrai).

decode($feature["field1"] + 3 , $feature["field1"], 1, $feature["field2"], 2, 0)

Compare l’égalité entre la valeur conditionnelle field1 (champ 1) + 3 et case1 (cas 1) field1 (champ 1). Si la condition est true (vrai), renvoie 1. Si la condition est false (faux), compare l’égalité entre field1 (champ 1) + 3 et field2 (champ 2). Si la condition est true (vrai), renvoie 2 ; sinon, renvoie 0.