Formule

Fonctionne sur le champs integer, float, et date (support date en bêta) ❌ !

La formules est une suite d'opération mathématique permettant d'obtenir un résultat.

Dans notre cas d'utilisation cette feature permet de créer des variables par des formules mais aussi via la valeurs d'autre variables dans le dataset.

Cette feature est particulièrement utile pour modéliser des relations logiques entre tes données : calculer un prix TTC à partir d'un prix HT, dériver un score à partir de plusieurs métriques, ou encore borner une valeur dans une plage réaliste.

Contraintes importantes

Les variables doivent être déclarées avant le champ qui les utilise. La formule est évaluée au moment de la génération du champ cible : seuls les champs définis au-dessus dans le YAML sont accessibles. Si tu références un champ déclaré après, il ne sera pas encore disponible et la génération échouera.

Ne pas combiner formula avec saisonnality, correlation ou d'autres patterns — ces features modifient la valeur générée après coup, ce qui entrerait en conflit avec le résultat de ta formule.

Créer une formule

Pour activer ce mode de calcul, il suffit d'ajouter le champ formula dans la définition de ton champ YAML. La valeur est une expression mathématique sous forme de chaîne de caractères.

Les champs du dataset se référencent directement par leur fieldName. Si ton champ s'appelle budget, tu écris simplement budget dans ta formule — pas de syntaxe spéciale, pas de préfixe.

Le champ rules.range reste utilisable pour borner le résultat final si la formule peut produire des valeurs hors de la plage souhaitée. (Pas sûr en bêta)

//Variable d'origine présente dans la formule ci-dessous
- fieldName: budget
    type: integer
    rules:
      range:
        min: -10
        max: 101
- fieldName: test_formula
    type: integer
    
    formula : "sqrt(budget)* pi"
    

Liste d'exemple plus complexe

Scénario : tu génères des profils d'emprunteurs avec un score de risque calculé à partir de plusieurs indicateurs financiers, en utilisant des fonctions logarithmiques et des racines pour modéliser des relations non-linéaires réalistes (comme en vrai scoring bancaire).

# Revenu annuel brut (en €)
- fieldName: revenu_annuel
  type: float
  rules:
    range:
      min: 15000
      max: 200000

# Montant total des dettes en cours (en €)
- fieldName: dette_totale
  type: float
  rules:
    range:
      min: 0
      max: 150000

# Nombre d'années d'historique de crédit
- fieldName: anciennete_credit
  type: integer
  rules:
    range:
      min: 0
      max: 30

# Nombre d'incidents de paiement sur 24 mois
- fieldName: incidents_paiement
  type: integer
  rules:
    range:
      min: 0
      max: 10

# Ratio dette / revenu (DTI — Debt To Income)
# Plus il est élevé, plus le profil est risqué
- fieldName: dti_ratio
  type: float
  formula: "clamp(dette_totale / revenu_annuel, 0, 1)"

# Capacité financière — racine carrée du revenu normalisée
# Croît moins vite que le revenu : un revenu x4 ne donne pas x4 de capacité
- fieldName: capacite_financiere
  type: float
  formula: "sqrt(revenu_annuel / 1000)"

# Poids de l'historique — logarithmique
# Les premières années comptent beaucoup, les suivantes de moins en moins
- fieldName: poids_historique
  type: float
  formula: "log(anciennete_credit + 1)"

# Pénalité incidents — exponentielle inversée
# 0 incident = pénalité nulle, chaque incident supplémentaire pèse de plus en plus
- fieldName: penalite_incidents
  type: float
  formula: "1 - exp(-incidents_paiement * 0.4)"

# Score brut composite (0 à ~10)
- fieldName: score_brut
  type: float
  formula: "capacite_financiere * poids_historique * (1 - dti_ratio) * (1 - penalite_incidents)"

# Score final normalisé sur 100 avec bruit réaliste de ±3%
# et borné pour ne jamais dépasser 100 ni descendre sous 0
- fieldName: score_risque
  type: float
  formula: "clamp(round(noise(score_brut * (100 / (sqrt(200) * log(31))), 3) * 10) / 10, 0, 100)"

Scénario : tu génères des mesures acoustiques dans différents environnements (salle de concert, open space, entrepôt...) avec le niveau sonore perçu calculé selon la distance à la source, les propriétés du milieu, et l'absorption de l'air.

# Puissance acoustique de la source en Watts (ex: 0.001W = conversation, 100W = concert)
- fieldName: puissance_source
  type: float
  rules:
    range:
      min: 0.001
      max: 100.0

# Distance entre la source et le récepteur en mètres
- fieldName: distance_metres
  type: float
  rules:
    range:
      min: 0.5
      max: 500.0

# Coefficient d'absorption de l'air selon l'humidité (0.001 à 0.01 dB/m)
- fieldName: absorption_air
  type: float
  rules:
    range:
      min: 0.001
      max: 0.010

# Indice de réverbération du milieu (0=anéchoïque, 1=très réverbérant)
- fieldName: reverb_index
  type: float
  rules:
    range:
      min: 0.0
      max: 1.0

# Intensité acoustique en W/m²
# Loi du carré inverse : I = P / (4 * pi * r²)
# Plus on s'éloigne, l'énergie se répartit sur une sphère de plus en plus grande
- fieldName: intensite_acoustique
  type: float
  formula: "puissance_source / (4 * pi * distance_metres ** 2)"

# Niveau de pression acoustique brut en dB SPL
# Formule fondamentale : Lp = 10 * log10(I / I_ref) où I_ref = 10^-12 W/m²
# log(x / 10^-12) = log(x) + 12 * log(10) = log(x) + 12 * ln10
- fieldName: spl_brut
  type: float
  formula: "10 * (log(intensite_acoustique) + 12 * ln10)"

# Atténuation atmosphérique sur la distance (en dB)
# L'air absorbe le son proportionnellement à la distance
- fieldName: attenuation_air
  type: float
  formula: "absorption_air * distance_metres"

# Gain de réverbération — le son rebondit sur les parois et s'additionne
# Modélisé comme une racine carrée pour un effet de saturation réaliste
- fieldName: gain_reverb
  type: float
  formula: "6 * sqrt(reverb_index)"

# Niveau sonore perçu final en dB SPL avec bruit de mesure ±1.5%
# On soustrait l'atténuation et on ajoute la réverbération
- fieldName: spl_percu
  type: float
  formula: "clamp(noise(spl_brut - attenuation_air + gain_reverb, 1.5), 0, 194)"

Liste des variables et operateurs disponibles

Opérateur arythmétique

Symbole	Nom	Description	Exemple
+	Addition	Additionne deux valeurs.	10 + 5 → 15
-	Soustraction	Soustrait la deuxième valeur de la première.	10 - 5 → 5
*	Multiplication	Multiplie deux valeurs.	10 * 5 → 50
/	Division	Divise la première valeur par la deuxième.	10 / 4 → 2.5
**	Puissance	Élève le nombre à la puissance indiquée.	2 ** 3 → 8
%	Modulo	Retourne le reste d'une division entière.	10 % 3 → 1

Compariason et logiques

Symbole / Mot-clé	Type	Description
==	Comparaison	Vérifie si deux valeurs sont strictement égales.
!=	Comparaison	Vérifie si deux valeurs sont différentes.
< , >	Comparaison	Strictement inférieur ou strictement supérieur.
<= , >=	Comparaison	Inférieur ou égal / Supérieur ou égal.
and , &	Logique	Vrai si les deux conditions sont vraies.
or , `	`	Logique
not	Logique	Inverse l'état (Vrai devient Faux et vice versa).
^	Logique	XOR (Vrai si une seule des deux conditions est vraie).

Fonction Mathématiques avancé

Fonction	Description	Exemple
sqrt(x)	Racine carrée.	sqrt(16) → 4
abs(x)	Valeur absolue (rend le nombre positif).	abs(-5) → 5
log(x)	Logarithme népérien.	log(1) → 0
exp(x)	Exponentielle.	exp(0) → 1
sin, cos, tan	Fonctions trigonométriques (en radians).	sin(pi/2) → 1
round(x)	Arrondi à l'entier le plus proche.	round(2.6) → 3
floor(x)	Arrondi à l'entier inférieur.	floor(2.9) → 2
ceil(x)	Arrondi à l'entier supérieur.	ceil(2.1) → 3

Fonction Utilitaire

Fonction	Description	Exemple
if(cond, a, b)	Si la condition est vraie, retourne a, sinon b.	if(score > 10, "Gagné", "Perdu")
clamp(x, min, max)	Force une valeur à rester dans une fourchette.	clamp(15, 0, 10) → 10
min(a, b, ...)	Retourne la plus petite valeur d'une liste.	min(1, 5, -2) → -2
max(a, b, ...)	Retourne la plus grande valeur d'une liste.	max(1, 5, -2) → 5
noise(x, pct)	Ajoute un pourcentage de variation aléatoire à x.	noise(100, 10) → 90 à 110
coalesce(...)	Retourne la première valeur non nulle (non-None).	coalesce(null, "Salut") → "Salut"

Date et Constante

Constante	Valeur Approchée	Description
golden_ratio	1.61803...	Le Nombre d'Or (), utilisé en design et géométrie.
sqrt2	1.41421...	Racine carrée de 2 ().
sqrt3	1.73205...	Racine carrée de 3 ().
ln2	0.69314...	Logarithme népérien de 2.
ln10	2.30258...	Logarithme népérien de 10.
euler_mascheroni	0.57721...	Constante d'Euler (), utilisée en théorie des nombres.
days_between(a, b)	Fonction (en Bêta)	Calcule le nombre de jours entre deux dates.
add_days(date, n)	Fonction (en Bêta)	Ajoute n jours à une date donnée.
pi	π	La valeur π