ProRealTime · ProBuilder
ONCE et BarIndex en ProBuilder : initialiser une fois et compter les barres
Comment ONCE initialise une variable une seule fois et comment BarIndex numérote les barres : compteurs, états persistants, délai entre signaux et attente d’historique en ProBuilder.
ONCE et BarIndex répondent à deux questions que pose le modèle d’exécution de ProBuilder, où le code est relu sur chaque barre. ONCE variable = valeur initialise une variable une seule fois, lors de la première lecture du code ; aux barres suivantes, la ligne est ignorée et la variable conserve la valeur calculée précédemment. BarIndex renvoie le numéro de la barre en cours, en partant de 0 pour la barre la plus ancienne de l’historique chargé. Ensemble, ils permettent de construire des compteurs, de mémoriser un état et d’attendre qu’il y ait assez d’historique avant de calculer.
Cette page explique leur fonctionnement exact, leurs usages typiques et leurs pièges. Elle fait partie de la rubrique Le langage ProBuilder et prolonge le guide Variables et calculs.
Pourquoi ONCE est nécessaire
Lorsqu’une ligne comme compteur = 0 figure dans votre code, elle est exécutée sur chaque barre : la variable est remise à zéro à chaque relecture. C’est le comportement voulu pour une variable de signal, mais pas pour un compteur ou un état qui doit traverser le temps. ONCE résout ce problème : la ligne n’est traitée qu’à la première lecture du programme.
La documentation officielle illustre la différence avec deux programmes identiques, à l’exception du mot-clé ONCE :
ONCE compteur = 0 // exécuté une seule fois
ONCE i = 0 // exécuté une seule fois
IF i <= 5 THEN
compteur = compteur + i
i = i + 1
ENDIF
RETURN compteur
Avec ONCE, ce programme renvoie 15 : sur les six premières barres, i vaut successivement 0, 1, 2, 3, 4 et 5 et s’ajoute au compteur (0 + 1 + 2 + 3 + 4 + 5 = 15), puis la condition i <= 5 devient fausse et le compteur ne bouge plus. Sans ONCE, compteur et i sont remis à zéro sur chaque barre ; la condition est donc toujours vraie mais n’ajoute que 0, et le programme renvoie 0.
Les usages typiques de ONCE
Initialiser un état
Un indicateur de tendance à états (haussier, baissier, neutre) a besoin d’un état de départ, puis ne doit changer que sur un signal :
ONCE etat = 0 // neutre au démarrage, une seule fois
IF Close CROSSES OVER Average[50](Close) THEN
etat = 1 // passage en tendance haussière
ELSIF Close CROSSES UNDER Average[50](Close) THEN
etat = -1 // passage en tendance baissière
ENDIF
RETURN etat // l'état persiste entre deux signaux
À proprement parler, une variable jamais affectée vaut déjà 0 ; mais écrire ONCE etat = 0 rend l’intention explicite et devient indispensable dès que la valeur initiale est autre chose que zéro, par exemple ONCE plusBas = 999999.
Calculer une valeur de référence une fois pour toutes
La documentation de ProRealCode montre aussi ONCE appliqué à un calcul, par exemple ONCE premierMinimum = Lowest[10](Low) : la valeur est calculée lors de la première lecture et n’est plus modifiée ensuite. Retenez qu’elle porte alors sur le tout début de l’historique, pas sur la période récente.
Ce que ONCE ne fait pas
ONCE ne crée pas une « constante » : la variable reste modifiable ensuite par n’importe quelle affectation. Il n’empêche pas non plus la réinitialisation lorsque l’indicateur est entièrement recalculé (changement d’unité de temps, rechargement de l’historique, modification du code) : la documentation précise que la variable n’est réinitialisée qu’au redémarrage complet du script, et c’est bien ce qui se produit dans ces cas.
BarIndex : le compteur de barres
BarIndex vaut 0 sur la barre la plus ancienne chargée dans le graphique, 1 sur la suivante, et augmente de 1 à chaque barre. Sur la barre la plus récente, il est égal au nombre de barres chargées moins un. Ce n’est ni une date ni un prix : seulement une position dans les données.
Attendre assez d’historique
C’est l’usage le plus courant. Une moyenne de 200 périodes n’a pas de sens sur les 200 premières barres du graphique, faute de données. Un test sur BarIndex permet de ne rien calculer, ou de ne rien afficher, tant que l’historique est insuffisant :
periode = 200
IF BarIndex >= periode THEN
mm = Average[periode](Close)
ELSE
mm = Undefined // rien n'est tracé au début du graphique
ENDIF
RETURN mm
Le même réflexe s’impose avant toute boucle qui lit Close[i] avec un i important.
Mesurer l’ancienneté d’un événement
En mémorisant le BarIndex d’un événement, on obtient à tout moment le nombre de barres écoulées depuis : BarIndex - barreSignal. C’est la base des filtres du type « pas de nouveau signal moins de 10 barres après le précédent » ou des sorties temporelles.
Servir de coordonnée horizontale
Les instructions graphiques (DRAWTEXT, DRAWSEGMENT, DRAWARROWUP…) utilisent par défaut BarIndex comme abscisse. Pour dessiner sur la barre courante, on passe BarIndex ; pour la barre précédente, BarIndex - 1 ou BarIndex[1]. Le guide DRAWTEXT, DRAWARROW et objets graphiques en donne de nombreux exemples. La fonction DateToBarIndex permet, à l’inverse, de convertir une date en index de barre pour placer un objet à une date précise.
IntradayBarIndex : le compteur de la séance
IntradayBarIndex fonctionne comme BarIndex, mais repart de 0 au début de chaque journée : la première barre de la séance vaut 0, la deuxième 1, etc. Il sert à repérer les premières barres de la journée, par exemple pour mesurer le range d’ouverture. Son usage détaillé est présenté sur la page IntradayBarIndex de la rubrique des instructions.
Exemple complet : filtre de signaux espacés
Cet indicateur affiche un signal haussier lorsque le prix franchit le plus haut des 20 barres précédentes, mais impose au moins 15 barres entre deux signaux. Il combine ONCE, BarIndex et la mémorisation d’un état.
// Cassure du plus haut 20 barres, avec un délai minimal entre deux signaux
periode = 20
delaiMin = 15
ONCE derniereBarreSignal = -1000 // valeur initiale très ancienne, posée une seule fois
plusHaut = Highest[periode](High[1]) // plus haut des 20 barres précédentes (barre courante exclue)
signal = 0 // remis à zéro sur chaque barre
IF BarIndex > periode THEN // assez d'historique
ecart = BarIndex - derniereBarreSignal // barres écoulées depuis le dernier signal
IF Close > plusHaut AND ecart >= delaiMin THEN
signal = 1
derniereBarreSignal = BarIndex // mémorise la barre du signal
ENDIF
ENDIF
RETURN signal AS "Cassure filtrée"
Notez l’écriture Highest[periode](High[1]) : en appliquant la fonction à la série décalée d’une barre, on exclut la barre courante du calcul. Sans ce décalage, la clôture ne pourrait jamais dépasser un plus haut qui inclut déjà le plus haut de sa propre barre (une clôture ne dépasse jamais le plus haut de sa bougie), et la cassure ne serait jamais détectée. C’est une erreur classique dans les indicateurs de breakout.
Deux variables, deux comportements : signal est remise à zéro à chaque barre, tandis que derniereBarreSignal n’est initialisée qu’une fois grâce à ONCE et ne change qu’au moment d’un signal. La valeur initiale de -1000 garantit que le premier signal n’est pas bloqué par le délai.
Pièges à connaître
- BarIndex dépend de l’historique chargé. Si vous chargez plus ou moins de barres, la même bougie n’a plus le même
BarIndex. Ne codez jamais une logique qui dépend d’une valeur absolue deBarIndex(par exemple « à partir de la barre 500 ») : raisonnez toujours en écarts. - CALCULATEONLASTBARS change le point de départ. Lorsque le calcul est limité aux N dernières barres, les valeurs initialisées par
ONCEle sont au début de cette fenêtre, et non au début de l’historique. - ONCE sur une variable recalculée plus bas : si une ligne ordinaire réaffecte la variable sur chaque barre, l’effet de
ONCEdisparaît. Vérifiez qu’aucune affectation inconditionnelle ne vient l’écraser. - Barre courante non clôturée : en temps réel, la dernière barre est relue à chaque mise à jour du prix. Un état modifié sur cette barre peut l’être plusieurs fois avant la clôture.
Ces situations reviennent souvent dans le guide des erreurs fréquentes en ProBuilder.
FAQ
Quelle est la différence entre ONCE x = 0 et x = 0 ?
x = 0 est exécuté sur chaque barre et remet donc la variable à zéro à chaque relecture du code. ONCE x = 0 n’est exécuté qu’à la première lecture : ensuite, la variable conserve sa valeur d’une barre à l’autre, sauf si une autre instruction la modifie.
BarIndex commence-t-il à 0 ou à 1 ?
À 0. La barre la plus ancienne de l’historique chargé porte l’index 0, la suivante 1, et ainsi de suite. Sur la barre la plus récente, BarIndex vaut le nombre de barres chargées moins un.
Comment compter les barres depuis un signal ?
Mémorisez le BarIndex de la barre du signal dans une variable, puis calculez BarIndex moins cette variable sur les barres suivantes. Initialisez la variable avec ONCE à une valeur très ancienne pour ne pas bloquer le premier signal.
Quelle différence entre BarIndex et IntradayBarIndex ?
BarIndex compte les barres depuis le début de l’historique chargé, sans jamais repartir à zéro. IntradayBarIndex repart de 0 à la première barre de chaque journée, ce qui le rend adapté aux logiques de séance.
