Trend#
Trend measures how closely generated data preserves pairwise relationships between columns. It compares numeric correlations and joint categorical frequencies, then averages the pair scores with equal weight.
Use Trend alongside Shape to assess dependencies that matching marginal distributions can conceal. These pairwise checks can still miss differences involving three or more columns.
To examine relationships within real-defined subpopulations, use Conditional Fidelity.
Score#
Property |
Value |
|---|---|
Metric selection |
|
Report key |
|
Range |
\([0,1]\) |
Direction |
Higher means closer pairwise relationships |
Detailed output |
One score per column pair |
Required columns |
At least two |
Read the generated-real score alongside its matched real-real reference; independent real samples also differ. See Methodology for the shared comparison procedure.
Example: find a broken relationship#
Use the shared customer example to create data.
The toy generator permutes spend, weakening its relationship with visits.
Trend exposes this change in the pair scores:
from tabgen_eval import evaluate
report = evaluate(data, metrics=["trend"], details=True, seed=23)
score = report["trend/trend"]
print(score.value, score.ideal)
print(report.details("trend").sort_values("score"))
report.fidelity.plot(kind="pairs", metric="trend").show()
View the source values
| column_1 | column_2 | score |
|---|---|---|
| visits | spend | 0.4381 |
| visits | tenure | 0.9957 |
| visits | segment | 0.7100 |
| spend | tenure | 0.8664 |
| spend | segment | 0.7100 |
| tenure | segment | 0.4600 |
The heatmap highlights the weakened visits–spend relationship, which an
overall average or matching marginal distributions can conceal.
Definition#
Let \(R\) and \(G\) denote the matched real and generated samples. For each unordered column pair \((j,k)\), compute the similarity appropriate to its column types.
Numeric–numeric pairs#
Let \(\widehat\rho_{R,jk}\) and \(\widehat\rho_{G,jk}\) be the Pearson correlations of the two numeric columns within each sample. Their similarity is
Pearson correlations lie in \([-1,1]\), so their absolute difference can reach \(2\). Equal correlations score \(1\), even if other aspects of the joint distributions differ. Correlation is undefined if either column is constant within either sample, or fewer than two usable paired rows remain.
Pairs containing categorical columns#
Categorical columns retain their category identities. A numeric column paired with a categorical column is first divided into up to ten quantile bins fitted on the real sample. Tied boundaries reduce the number of bins. Generated values outside the reference range are assigned to the nearest edge bin.
Let \(\widehat p_{R,jk}(a,b)\) and \(\widehat p_{G,jk}(a,b)\) be the normalized joint frequencies on this shared category or bin space. The score is one minus total variation distance:
The joint table captures marginal frequencies as well as association. Categories seen on only one side contribute to the discrepancy. Reference-fitted numeric bins make mixed-type Trend directional: exchanging the real and generated tables can change the score.
Aggregate#
For the set \(P\) of pairs with defined scores,
Each usable pair has equal weight. Undefined pairs are excluded. If no pair
is usable, the aggregate is NaN. With fewer than two declared columns, Trend
is marked NOT_APPLICABLE.
Pair details#
With details=True, report.details("trend") returns column_1, column_2,
and score for each pair, including NaN for undefined pairs. These are the
components used in the generated-real aggregate. See
component tables for shared
retention behavior.
Missing values#
Missing values are handled pairwise, separately on each side. Numeric correlations use rows where both values are finite. Joint tables exclude rows with a missing category or an unassigned numeric bin. Different pairs can therefore use different numbers of observations.
Sampling uses the full row pools before these pairwise exclusions.