Note
Go to the end to download the full example code.
Ensemble Analysis¶
This tutorial analyses multiple simulation runs together with the
Ensemble object, using the GX members in
examples/data/gx/ensemble.
Instead of one long trace, an ensemble combines several shorter runs. QUENDS provides three ways to turn an ensemble into a mean with an honest uncertainty:
Ensemble Average – average the members onto a common grid, then analyse that single averaged trace,
Serialization (pooled block means) – pool the per-member block means,
Inverse-Variance-Weighted (IVW) – weight each member’s mean by its inverse variance.
For single-trace analysis, see the DataStream Class guide. Trim/statistics
parameters follow the QUENDS paper analysis notebooks for the stellarator GX
ensemble (method="threshold", window_size=50, start_time=100,
threshold=0.19).
Import QUENDS
import glob
from pathlib import Path
import quends as qnds
def example_data_dir() -> Path:
"""Find the shared example data directory during script or gallery runs."""
starts = []
if "__file__" in globals():
starts.append(Path(__file__).resolve())
starts.append(Path.cwd().resolve())
for start in starts:
for parent in [start, *start.parents]:
for candidate in (parent / "examples" / "data", parent / "data"):
if candidate.is_dir():
return candidate
raise FileNotFoundError("Could not locate examples/data")
COL = "HeatFlux_st"
DATA_DIR = example_data_dir()
plotter = qnds.Plotter()
Data Loading¶
Ensemble.from_files loads each CSV into a member DataStream.
gx_files = sorted(glob.glob(str(DATA_DIR / "gx" / "ensemble" / "tprim_2_5_*.out.csv")))
ens = qnds.Ensemble.from_files(gx_files, COL)
print("ensemble members:", len(ens.members()))
ensemble members: 4
Plotting all members together with the ensemble average.
plot = plotter.plot_ensemble_with_average(
ens, variables_to_plot=[COL], condensed_legend=True, show=True
)

Ensemble Average Approach¶
Average the members onto a common time grid, then analyse that single averaged trace exactly like a single run.
Build the averaged DataStream and check stationarity.
avg = ens.compute_average_ensemble()
print("averaged trace rows:", len(avg))
print("avg is_stationary:", avg.is_stationary(COL))
averaged trace rows: 740
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
avg is_stationary: {'HeatFlux_st': True}
Trim the averaged trace, then read off its ESS.
avg_trimmed = avg.trim(
method="threshold", window_size=50, start_time=100, threshold=0.19
)
print("avg sss_start:", avg_trimmed.trim_metadata.get("sss_start"))
print("avg ESS:", avg_trimmed.effective_sample_size())
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
avg sss_start: 126.838088
avg ESS: {'results': {'HeatFlux_st': 5}}
The Ensemble Average estimate of the mean and its uncertainty. We analyse the
trimmed averaged trace (average -> trim -> statistics), so the transient is
removed before the mean and its standard error are computed. NB: the
ensemble_average estimator does not trim internally – running it on a
raw, un-trimmed average folds the transient into the variance and greatly
inflates the uncertainty.
ea_stats = avg_trimmed.compute_statistics(method="non-overlapping")[COL]
print("Ensemble Average ->", ea_stats)
Ensemble Average -> {'mean': 7.9388704669023005, 'mean_uncertainty': 0.19515464434491112, 'variance': 0.152341340837555, 'confidence_interval': (7.556367363986275, 8.321373569818327), 'standard_deviation': 0.39030928868982223, 'pm_std': (7.743715822557389, 8.134025111247212), 'effective_sample_size': 5, 'window_size': 116, 'n_short_averages': 4, 'ess_blocks': 4.0, 'se_effective_n': 4.0, 'se_method': 'ess_blocks', 'independence_status': 'tau_window', 'independent': True, 'ljungbox_lags': [3], 'ljungbox_pvalues': [0.3350287414737564], 'ljungbox_pvalue': 0.3350287414737564, 'ci_method': 'normal', 'confidence_level': 0.95}
Serialization (Pooled Block Means) Approach¶
Rather than averaging the traces, pool the per-member block means. Trim every member first, then aggregate across members.
ens_trimmed = ens.trim(
column_name=COL, method="threshold", window_size=50, start_time=100, threshold=0.19
)
print("members stationary:", ens.is_stationary(COL)["results"])
print("ESS (pooled_block_means):", ens_trimmed.effective_sample_size(COL)["results"])
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
/home/runner/work/quends/quends/src/quends/base/data_stream.py:562: FutureWarning: adfuller currently returns a plain tuple whose length depends on the store and autolag arguments. In release 0.16 or after July 2027, whichever is later, the default behavior will switch to always returning an ADFullerResult. Set result_object=True to switch now, or result_object=False to keep the current behavior and silence this warning.
p_value = adfuller(self.data[column].dropna(), autolag="AIC")[1]
members stationary: {'Member 0': {'HeatFlux_st': True}, 'Member 1': {'HeatFlux_st': True}, 'Member 2': {'HeatFlux_st': True}, 'Member 3': {'HeatFlux_st': True}}
ESS (pooled_block_means): {'HeatFlux_st': 18.0}
The serialization estimate of the mean and its uncertainty, on the trimmed members.
ser_stats = ens_trimmed.compute_uncertainty(
method="pooled_block_means", column_name=COL
)["results"][COL]
print("Serialization ->", ser_stats)
Serialization -> {'mean': 7.7908794756513755, 'variance': 0.26615460503480276, 'ess_blocks': 18.0, 'n_short_averages': 18, 'mean_uncertainty': 0.12159920619139722, 'mean_uncertainty_sem_n': 0.12159920619139722, 'mean_uncertainty_sem_ess': 0.12159920619139722, 'se_method': 'sem_ess', 'warning': 'Not all members passed independence; using ESS-based SEM.', 'confidence_interval': (7.552545031516237, 8.029213919786514), 'pm_std': (7.669280269459978, 7.912478681842773), 'window_size': 20, 'member_window_sizes': [22, 25, 18, 16], 'window_size_summary': 20, 'window_size_summary_method': 'median', 'window_size_min': 16, 'window_size_max': 25, 'independent': False, 'independence_status': 'none_independent', 'ljungbox_pvalue': 0.09682347142711178, 'ljungbox_pvalues': [0.165023822342759, 0.15917836287685758, 0.09682347142711178, 0.5199384338884474], 'ljungbox_lags': [3, 3, 3, 5], 'ci_method': 'normal', 'confidence_level': 0.95, 'member_all_independent': False, 'member_some_best_p': False}
Inverse-Variance-Weighted (IVW) Approach¶
Combine the per-member means weighting each by its inverse variance, so better-resolved members count more. Trimming/stationarity are as above.
print("ESS (ivw):", ens_trimmed.effective_sample_size(COL, technique="ivw")["results"])
ivw_stats = ens_trimmed.compute_uncertainty(method="ivw", column_name=COL)["results"][
COL
]
print("IVW ->", ivw_stats)
ESS (ivw): {'HeatFlux_st': 20.0}
IVW -> {'mean': 7.829402193714083, 'mean_uncertainty': 0.09995143554953226, 'confidence_interval': (7.633497380036999, 8.025307007391167), 'pm_std': (7.729450758164551, 7.929353629263615), 'variance': 0.2992800397091752, 'ess_blocks': 20.0, 'n_short_averages': 20.0, 'se_method': 'ivw_member_means', 'warning': None, 'window_size': 17, 'member_window_sizes': [17, 17, 17, 17], 'window_size_summary': 17, 'window_size_summary_method': 'median', 'window_size_min': 17, 'window_size_max': 17, 'independence_status': 'all_independent', 'independent': True, 'ljungbox_pvalue': 0.19811360713708337, 'ljungbox_pvalues': [0.32862422830471566, 0.05366281164550079, 0.1164414685937777, 0.2937259200043394], 'ljungbox_lags': [4], 'ci_method': 'normal', 'confidence_level': 0.95, 'individual': None}
Computed on the trimmed steady-state data, the three approaches give consistent means with comparable uncertainties – a useful cross-check on an ensemble.
for name, r in [
("Ensemble Average", ea_stats),
("Serialization", ser_stats),
("IVW", ivw_stats),
]:
print(
f"{name:18s} mean={r.get('mean'):.4f} uncertainty={r.get('uncertainty', r.get('mean_uncertainty')):.4f}"
)
Ensemble Average mean=7.9389 uncertainty=0.1952
Serialization mean=7.7909 uncertainty=0.1216
IVW mean=7.8294 uncertainty=0.1000
Total running time of the script: (0 minutes 0.188 seconds)