polyphys 1.0.0__py3-none-any.whl

polyphys/tests/manage/test_organizer.py

@@ -0,0 +1,1495 @@
+"""Tests for :mod:`polyphys.manage.organizer`.
+
+Most inputs come from the ``make_lineage_tree`` factory in
+``polyphys/tests/conftest.py``: tiny ``.npy`` files named for the
+``ChainCyl`` parser, under a directory whose name contains hyphens, as
+every lineage directory name does. File ``(e, w, s)`` (ensemble, whole,
+segment, each from 1; ``s = 0`` for a whole file) holds
+``1000 * e + 100 * w + 10 * s + k`` in row ``k``, so every expected sum,
+concatenation, and replicate statistic below is written down by hand from
+that rule. Expected lineage names come from the parser applied to the
+written filename, never from the strings the tree builds.
+
+The space tests build a small ``analysis`` phase on disk; their expected
+``t_index`` and ``time`` values come from the ``dt`` field and the dump
+period of the group's trajectory (``adump`` for ``all``, ``bdump`` for
+``bug``) encoded in the filenames. The stamp tests use the column layout of the
+SciOps probe phase's stamp files: genealogy columns, parser attributes, and
+``n_frames``.
+"""
+import logging
+import os
+import re
+from pathlib import Path
+from typing import get_args
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from polyphys.manage.organizer import (
+    BULK_NAME_MAP,
+    children_stamps,
+    create_fullname,
+    ens_avg_from_bin_edge,
+    ens_avg_from_df,
+    ens_avg_from_ndarray,
+    ens_from_bin_edge,
+    ens_from_df,
+    ens_from_mat_t,
+    ens_from_vec,
+    ensemble,
+    ensemble_avg,
+    make_database,
+    parents_stamps,
+    rename_bulk_columns,
+    save_artifact,
+    space_hists,
+    space_tseries,
+    whole_from_file,
+    whole_from_segments,
+)
+from polyphys.tests.synthetic import ChainCyl
+from polyphys.manage.types import PhaseT, StageT
+from polyphys.manage.utils import round_to_multiple
+
+# A Pandas4Warning marks a deprecated pandas call; fail on it.
+pytestmark = pytest.mark.filterwarnings("error::pandas.errors.Pandas4Warning")
+
+
+# Fixtures: lineage trees and the names the parser gives their files
+
+
+@pytest.fixture
+def segment_tree(make_lineage_tree):
+    """Return a segment tree: 2 ensembles x 2 wholes x 2 segments x 3 rows."""
+    return make_lineage_tree(ChainCyl, group="bug", n_rows=3)
+
+
+@pytest.fixture
+def whole_tree(make_lineage_tree):
+    """Return a whole tree: 2 ensembles x 2 wholes x 3 rows."""
+    return make_lineage_tree(
+        ChainCyl, group="bug", lineage="whole", n_rows=3
+    )
+
+
+def _parsed_names(tree, attr):
+    """Map each tree file's (ensemble, whole) indices to a parsed name."""
+    return {
+        index[:2]: getattr(
+            ChainCyl(str(path), tree.lineage, tree.group, ispath=True),
+            attr,
+        )
+        for path, index in tree.index.items()
+    }
+
+
+@pytest.fixture
+def segment_whole_names(segment_tree):
+    """Return the parsed whole name of each (ensemble, whole) of the tree."""
+    return _parsed_names(segment_tree, "whole")
+
+
+@pytest.fixture
+def whole_names(whole_tree):
+    """Return the parsed whole name of each (ensemble, whole) in whole_tree."""
+    return _parsed_names(whole_tree, "whole")
+
+
+@pytest.fixture
+def ensemble_names(whole_tree):
+    """Return the parsed ensemble_long name of each ensemble in whole_tree."""
+    return {
+        e: name for (e, _), name in
+        _parsed_names(whole_tree, "ensemble_long").items()
+    }
+
+
+@pytest.fixture
+def write_segments(tmp_path):
+    """Factory: write arrays as segments j01, j02, ... of one whole."""
+    stem = (
+        "N20r5.5lz25.0ac1.0nc100dt0.005bdump1000adump5000ens1"
+    )
+
+    def _write(arrays):
+        directory = tmp_path / "ChainCyl-bug-segment"
+        directory.mkdir(exist_ok=True)
+        paths = []
+        for seg_id, array in enumerate(arrays, start=1):
+            path = directory / f"{stem}.j{seg_id:02d}.bug.binEdge.npy"
+            np.save(path, np.asarray(array))
+            paths.append(str(path))
+        return paths
+
+    return _write
+
+
+# Naming and persistence
+
+
+def test_create_fullname_joins_with_hyphens():
+    """A full name is the name, group, and property joined by hyphens."""
+    assert create_fullname("w", "bug", "rhoMon") == "w-bug-rhoMon"
+
+
+def test_save_artifact_writes_ndarray_to_npy(tmp_path):
+    """An array is saved as <filename>.npy and loads back unchanged."""
+    data = np.arange(3.0)
+    save_artifact("w-bug-rhoMon", data, tmp_path)
+    np.testing.assert_array_equal(np.load(tmp_path / "w-bug-rhoMon.npy"), data)
+
+
+def test_save_artifact_writes_dataframe_to_csv_without_index(tmp_path):
+    """A DataFrame is saved as <filename>.csv without its index."""
+    data = pd.DataFrame({"a": [1.0, 2.0], "b": [3.0, 4.0]}, index=[5, 6])
+    save_artifact("w-bug-rhoMon", data, tmp_path)
+    pd.testing.assert_frame_equal(
+        pd.read_csv(tmp_path / "w-bug-rhoMon.csv"),
+        data.reset_index(drop=True),
+    )
+
+
+def test_save_artifact_writes_dict_entries_by_measure(tmp_path):
+    """Each '<prop>-<measure>' entry is saved as <filename>-<measure>.npy."""
+    data = {"rhoMon-mean": np.array([1.0]), "rhoMon-var": np.array([2.0])}
+    save_artifact("w-bug-rhoMon", data, tmp_path)
+    assert sorted(os.listdir(tmp_path)) == [
+        "w-bug-rhoMon-mean.npy", "w-bug-rhoMon-var.npy"
+    ]
+    np.testing.assert_array_equal(
+        np.load(tmp_path / "w-bug-rhoMon-var.npy"), [2.0]
+    )
+
+
+def test_save_artifact_rejects_unsupported_type(tmp_path):
+    """Data that is not an array, a DataFrame, or a dict raises TypeError."""
+    with pytest.raises(TypeError, match="Unsupported data type list"):
+        save_artifact("w-bug-rhoMon", [1.0, 2.0], tmp_path)
+
+
+@pytest.mark.parametrize(
+    "group, directory",
+    [
+        pytest.param("bug", "N20-bug-ens", id="with-group"),
+        pytest.param(None, "N20-ens", id="without-group"),
+    ],
+)
+def test_make_database_creates_sibling_phase_directory(
+    tmp_path, group, directory
+):
+    """The new directory is <phase>/<prefix>-<group>-<stage> beside the old."""
+    old = tmp_path / "probes" / "N20-bug-segment"
+    new = make_database(old, "analysis", "ens", group)
+    assert new == str(tmp_path / "analysis" / directory) + "/"
+    assert Path(new).is_dir()
+
+
+def test_make_database_returns_existing_directory(tmp_path):
+    """Asking twice for the same directory returns the same path."""
+    old = tmp_path / "probes" / "N20-bug-segment"
+    first = make_database(old, "analysis", "ens", "bug")
+    assert make_database(old, "analysis", "ens", "bug") == first
+
+
+def test_make_database_logs_reuse_of_existing_directory(
+    tmp_path, caplog, capsys
+):
+    """Reusing a directory logs an INFO record naming it and prints nothing."""
+    old = tmp_path / "probes" / "N20-bug-segment"
+    make_database(old, "analysis", "ens", "bug")
+    caplog.set_level(logging.INFO, logger="polyphys.manage.organizer")
+
+    make_database(old, "analysis", "ens", "bug")
+
+    assert [(record.levelname, record.getMessage()) for record in
+            caplog.records] == [
+        ("INFO", f"Reusing the existing directory "
+                 f"{tmp_path / 'analysis' / 'N20-bug-ens'}.")]
+    assert capsys.readouterr().out == ""
+
+
+def test_make_database_rejects_unknown_phase(tmp_path):
+    """A phase outside the phase vocabulary raises ValueError."""
+    with pytest.raises(ValueError, match="'nope' is an invalid option"):
+        make_database(tmp_path / "probes" / "N20-bug-segment", "nope", "ens",
+                      "bug")
+
+
+def test_phase_vocabulary_is_the_settled_set():
+    """PhaseT declares the nine phase names of AGENTS.md in data-flow order."""
+    assert get_args(PhaseT) == (
+        "simsAll", "simsCont", "logs", "trjs", "probes", "analysis", "viz",
+        "galaxy", "allInOne",
+    )
+
+
+@pytest.mark.parametrize("phase", get_args(PhaseT))
+def test_make_database_accepts_every_declared_phase(tmp_path, phase):
+    """Every phase that PhaseT declares is accepted and names the directory."""
+    new = make_database(tmp_path / "probes" / "N20-bug-segment", phase,
+                        "ens", "bug")
+    assert Path(new).parent.name == phase
+
+
+def test_make_database_rejects_singular_phase_name(tmp_path):
+    """The singular 'simAll' of the old PhaseT is no longer accepted."""
+    with pytest.raises(ValueError, match="'simAll' is an invalid option"):
+        make_database(tmp_path / "probes" / "N20-bug-segment", "simAll",
+                      "ens", "bug")
+
+
+def test_make_database_rejects_unknown_stage(tmp_path):
+    """A stage outside StageT raises ValueError and names no directory."""
+    with pytest.raises(ValueError, match="'ensemble' is an invalid option"):
+        make_database(tmp_path / "probes" / "N20-bug-segment", "analysis",
+                      "ensemble", "bug")
+    assert get_args(StageT) == ("segment", "wholeSim", "ens", "ensAvg",
+                                "space", "galaxy")
+
+
+def test_make_database_rejects_group_with_hyphen(tmp_path):
+    """A group holding the field separator '-' raises ValueError before any
+    directory is made, since it would shift every hyphen-split field."""
+    old = tmp_path / "probes" / "N20-bug-segment"
+
+    with pytest.raises(ValueError, match="'bug-x'.*'-'"):
+        make_database(old, "analysis", "ens", "bug-x")
+
+    assert not (tmp_path / "analysis").exists()
+
+
+def test_make_database_rejects_old_directory_outside_a_phase(tmp_path):
+    """An old directory whose parent is not a phase directory raises
+    ValueError before any directory is made, instead of placing the new one
+    at the wrong depth."""
+    old = tmp_path / "root" / "N20-bug-segment"
+
+    with pytest.raises(ValueError, match="'root' is not a phase"):
+        make_database(old, "analysis", "ens", "bug")
+
+    assert not (tmp_path / "analysis").exists()
+
+
+# Building wholes
+
+
+def test_whole_from_segments_tseries_concatenates_in_segment_order(
+    segment_tree, segment_whole_names
+):
+    """A tseries whole is its segments' rows, j01 first, then j02."""
+    paths = [str(p) for p in segment_tree.paths]
+    wholes = whole_from_segments("gyrTMon", paths, ChainCyl, "bug",
+                                 "tseries")
+    np.testing.assert_array_equal(
+        wholes[segment_whole_names[(1, 2)]],
+        [1210.0, 1211.0, 1212.0, 1220.0, 1221.0, 1222.0],
+    )
+
+
+def test_whole_from_segments_histogram_sums_segments(
+    segment_tree, segment_whole_names
+):
+    """A histogram whole is the element-wise sum of its segments."""
+    paths = [str(p) for p in segment_tree.paths]
+    wholes = whole_from_segments("gyrTMon", paths, ChainCyl, "bug",
+                                 "histogram")
+    # (1210 + 1220, 1211 + 1221, 1212 + 1222)
+    np.testing.assert_array_equal(
+        wholes[segment_whole_names[(1, 2)]], [2430.0, 2432.0, 2434.0]
+    )
+
+
+def test_whole_from_segments_keys_wholes_by_parsed_name(
+    segment_tree, segment_whole_names
+):
+    """There is one whole per parsed whole name, whatever the directory."""
+    paths = [str(p) for p in segment_tree.paths]
+    wholes = whole_from_segments("gyrTMon", paths, ChainCyl, "bug",
+                                 "tseries")
+    assert "-" in segment_tree.root.name
+    assert list(wholes) == list(segment_whole_names.values())
+
+
+def test_whole_from_segments_bin_edge_keeps_shared_edges(write_segments):
+    """Identical segment edges reduce to one copy of them."""
+    edges = np.array([0.0, 1.0, 3.0])
+    paths = write_segments([edges, edges])
+    wholes = whole_from_segments("binEdge", paths, ChainCyl, "bug",
+                                 "bin_edge")
+    (whole,) = wholes.values()
+    np.testing.assert_array_equal(whole, edges)
+
+
+def test_whole_from_segments_bin_edge_rejects_differing_edges(write_segments):
+    """Segments of one whole with different edges raise ValueError."""
+    paths = write_segments([[0.0, 1.0, 3.0], [0.0, 1.0, 4.0]])
+    with pytest.raises(ValueError, match="Bin edges are not identical"):
+        whole_from_segments("binEdge", paths, ChainCyl, "bug", "bin_edge")
+
+
+def test_whole_from_segments_saves_each_whole(
+    tmp_path, segment_tree, segment_whole_names
+):
+    """save_to writes each whole to <whole>-<group>-<prop>.npy."""
+    out = tmp_path / "out"
+    out.mkdir()
+    paths = [str(p) for p in segment_tree.paths]
+    wholes = whole_from_segments("gyrTMon", paths, ChainCyl, "bug",
+                                 "tseries", save_to=out)
+    name = segment_whole_names[(2, 1)]
+    np.testing.assert_array_equal(
+        np.load(out / f"{name}-bug-gyrTMon.npy"), wholes[name]
+    )
+
+
+@pytest.mark.parametrize("relation", ["histogram", "tseries", "bin_edge"])
+def test_whole_from_segments_rejects_descending_segment_ids(
+    segment_tree, relation
+):
+    """Segments of a whole given in descending segment_id order raise."""
+    paths = [str(p) for p in segment_tree.paths[1::-1]]
+    with pytest.raises(ValueError, match=r"segment_id .*\[2, 1\]"):
+        whole_from_segments("gyrTMon", paths, ChainCyl, "bug", relation)
+
+
+@pytest.mark.parametrize("relation", ["histogram", "tseries", "bin_edge"])
+def test_whole_from_segments_rejects_duplicate_segment(segment_tree, relation):
+    """A segment passed twice raises instead of being counted twice."""
+    first = str(segment_tree.paths[0])
+    with pytest.raises(ValueError, match=r"segment_id .*\[1, 1\]"):
+        whole_from_segments(
+            "gyrTMon", [first, first], ChainCyl, "bug", relation
+        )
+
+
+@pytest.mark.parametrize("relation", ["histogram", "tseries", "bin_edge"])
+def test_whole_from_segments_rejects_a_gap_in_segment_ids(tmp_path, relation):
+    """Segments j01 and j03 of one whole raise instead of being joined as if
+    adjacent, which would shift the time of every later frame."""
+    whole = "N20r5.5lz25.0ac1.0nc100dt0.005bdump1000adump5000ens1"
+    paths = []
+    for seg_id in (1, 3):
+        path = tmp_path / f"{whole}.j{seg_id:02d}.bug.gyrTMon.npy"
+        np.save(path, np.arange(3.0))
+        paths.append(str(path))
+
+    with pytest.raises(ValueError, match=re.escape(
+            f"The segments of whole '{whole}' skip a segment_id: [1, 3]")):
+        whole_from_segments("gyrTMon", paths, ChainCyl, "bug", relation)
+
+
+def test_whole_from_segments_accepts_interleaved_wholes(segment_tree):
+    """Wholes interleaved segment by segment give the same wholes."""
+    ordered = [str(p) for p in segment_tree.paths]
+    # All j01 files first, then all j02 files; each whole stays in order.
+    interleaved = ordered[0::2] + ordered[1::2]
+    expected = whole_from_segments("gyrTMon", ordered, ChainCyl, "bug",
+                                   "tseries")
+    wholes = whole_from_segments("gyrTMon", interleaved, ChainCyl, "bug",
+                                 "tseries")
+    assert list(wholes) == list(expected)
+    np.testing.assert_array_equal(
+        np.stack(list(wholes.values())), np.stack(list(expected.values()))
+    )
+
+
+def test_whole_from_segments_rejects_unknown_relation(segment_tree):
+    """A relation other than histogram, tseries, or bin_edge raises."""
+    paths = [str(p) for p in segment_tree.paths]
+    with pytest.raises(ValueError, match="'nope' is an invalid option"):
+        whole_from_segments("gyrTMon", paths, ChainCyl, "bug", "nope")
+
+
+def test_whole_from_file_loads_each_whole_by_parsed_name(
+    whole_tree, whole_names
+):
+    """Each whole file loads under its parsed whole name."""
+    wholes = whole_from_file(whole_tree.paths, ChainCyl, "bug")
+    assert "-" in whole_tree.root.name
+    assert list(wholes) == list(whole_names.values())
+    np.testing.assert_array_equal(
+        wholes[whole_names[(2, 1)]], [2100.0, 2101.0, 2102.0]
+    )
+
+
+def test_whole_from_file_accepts_grouped_paths(whole_tree):
+    """1-tuples of paths, as sort_filenames gives, load like bare paths."""
+    grouped = list(zip(map(str, whole_tree.paths)))
+    bare = whole_from_file(whole_tree.paths, ChainCyl, "bug")
+    wholes = whole_from_file(grouped, ChainCyl, "bug")
+    assert list(wholes) == list(bare)
+    np.testing.assert_array_equal(
+        np.stack(list(wholes.values())), np.stack(list(bare.values()))
+    )
+
+
+def test_whole_from_file_rejects_two_files_of_one_whole(tmp_path):
+    """Two files that parse to one whole name raise, naming both, instead of
+    the second silently replacing the first."""
+    whole = "N20r5.5lz25.0ac1.0nc100dt0.005bdump1000adump5000ens1"
+    paths = []
+    for folder in ("a", "b"):
+        (tmp_path / folder).mkdir()
+        path = tmp_path / folder / f"{whole}-bug-gyrTMon.npy"
+        np.save(path, np.arange(3.0))
+        paths.append(path)
+
+    with pytest.raises(ValueError, match=re.escape(
+            f"'{paths[0]}' and '{paths[1]}' are both whole '{whole}'")):
+        whole_from_file(paths, ChainCyl, "bug")
+
+
+def test_whole_from_file_rejects_unsupported_path_item():
+    """An item that is neither a path nor a sequence of one raises."""
+    with pytest.raises(TypeError, match="Unsupported path item"):
+        whole_from_file([42], ChainCyl, "bug")
+
+
+# Grouping wholes into ensembles
+
+
+def test_ens_from_vec_puts_one_whole_per_column():
+    """Each whole becomes a column, in the order of the dictionary."""
+    name, ens_df = ens_from_vec(
+        ("ens1", {"w2": np.array([1.0, 2.0]), "w1": np.array([3.0, 4.0])})
+    )
+    assert name == "ens1"
+    pd.testing.assert_frame_equal(
+        ens_df, pd.DataFrame({"w2": [1.0, 2.0], "w1": [3.0, 4.0]})
+    )
+
+
+def test_ens_from_vec_rejects_wholes_of_unequal_length():
+    """Wholes of 3 and 2 values raise, naming the ensemble and each length."""
+    with pytest.raises(ValueError, match=re.escape(
+            "The wholes of ensemble 'ens1' have unequal lengths: "
+            "w1 3, w2 2.")):
+        ens_from_vec(("ens1", {"w1": np.arange(3.0), "w2": np.arange(2.0)}))
+
+
+def test_ens_from_mat_t_stacks_wholes_along_axis_0():
+    """Matrices stack into (n_wholes, n_rows, n_cols) in dictionary order."""
+    a = np.array([[1.0, 2.0], [3.0, 4.0]])
+    b = np.array([[5.0, 6.0], [7.0, 8.0]])
+    name, stacked = ens_from_mat_t(("ens1", {"w1": a, "w2": b}))
+    assert name == "ens1"
+    np.testing.assert_array_equal(stacked, np.stack([a, b]))
+
+
+def test_ens_from_df_averages_wholes_row_by_row():
+    """Whole DataFrames average element-wise into one: (a + b) / 2."""
+    a = pd.DataFrame({"x": [1.0, 2.0], "y": [3.0, 4.0]})
+    b = pd.DataFrame({"x": [3.0, 6.0], "y": [5.0, 8.0]})
+    name, ens_df = ens_from_df(("ens1", {"w1": a, "w2": b}))
+    assert name == "ens1"
+    pd.testing.assert_frame_equal(ens_df, (a + b) / 2)
+
+
+def test_ens_from_df_rejects_wholes_of_unequal_length():
+    """A 3-row and a 2-row whole raise instead of averaging the last row over
+    one replicate."""
+    a = pd.DataFrame({"x": [1.0, 2.0, 3.0]})
+    b = pd.DataFrame({"x": [3.0, 6.0]})
+
+    with pytest.raises(ValueError, match=re.escape(
+            "The wholes of ensemble 'ens1' have unequal lengths: "
+            "w1 3, w2 2.")):
+        ens_from_df(("ens1", {"w1": a, "w2": b}))
+
+
+def test_ens_from_bin_edge_returns_shared_edges():
+    """Identical whole edges pass through as a copy of the shared array."""
+    edges = np.array([0.0, 1.0, 2.0])
+    name, out = ens_from_bin_edge(("ens1", {"w1": edges, "w2": edges.copy()}))
+    assert name == "ens1"
+    np.testing.assert_array_equal(out, edges)
+    assert not np.shares_memory(out, edges)
+
+
+@pytest.mark.parametrize(
+    "other",
+    [
+        pytest.param(np.array([0.0, 1.0, 3.0]), id="different-values"),
+        pytest.param(np.array([0.0, 1.0, 2.0, 3.0]), id="different-lengths"),
+    ],
+)
+def test_ens_from_bin_edge_raises_on_mismatch(other):
+    """Differing whole edges raise ValueError instead of being merged."""
+    with pytest.raises(ValueError, match="Bin edges are not identical"):
+        ens_from_bin_edge(
+            ("ens1", {"w1": np.array([0.0, 1.0, 2.0]), "w2": other})
+        )
+
+
+def test_ensemble_groups_wholes_by_state_point(
+    whole_tree, whole_names, ensemble_names
+):
+    """Wholes of two state points form two ensembles keyed by ensemble_long."""
+    wholes = whole_from_file(whole_tree.paths, ChainCyl, "bug")
+    ens = ensemble("gyrTMon", wholes, ChainCyl, "bug", "vector")
+    assert list(ens) == [ensemble_names[1], ensemble_names[2]]
+    assert list(ens[ensemble_names[2]].columns) == [
+        whole_names[(2, 1)], whole_names[(2, 2)]
+    ]
+
+
+def test_ensemble_takes_bin_center_from_each_ensemble_edges(
+    whole_tree, whole_names, ensemble_names
+):
+    """Each ensemble's bin_center comes from its own wholes' edges."""
+    wholes = whole_from_file(whole_tree.paths, ChainCyl, "bug")
+    edges_1 = np.array([0.0, 1.0, 3.0, 6.0])
+    edges_2 = np.array([0.0, 2.0, 4.0, 8.0])
+    whole_edges = {
+        whole_names[(1, 1)]: edges_1,
+        whole_names[(1, 2)]: edges_1,
+        whole_names[(2, 1)]: edges_2,
+        whole_names[(2, 2)]: edges_2,
+    }
+    ens = ensemble("gyrTMon", wholes, ChainCyl, "bug", "vector",
+                   whole_edges=whole_edges)
+    # Analytic midpoints of each ensemble's edges
+    np.testing.assert_allclose(
+        ens[ensemble_names[1]]["bin_center"], [0.5, 2.0, 4.5]
+    )
+    np.testing.assert_allclose(
+        ens[ensemble_names[2]]["bin_center"], [1.0, 3.0, 6.0]
+    )
+
+
+@pytest.mark.parametrize(
+    "whole_type, first, second, expected",
+    [
+        pytest.param(
+            "matrix",
+            np.array([[1.0, 2.0]]), np.array([[3.0, 4.0]]),
+            np.array([[[1.0, 2.0]], [[3.0, 4.0]]]),
+            id="matrix-stacks",
+        ),
+        pytest.param(
+            "dataframe",
+            pd.DataFrame({"x": [1.0, 2.0]}), pd.DataFrame({"x": [3.0, 6.0]}),
+            np.array([[2.0], [4.0]]),
+            id="dataframe-averages",
+        ),
+        pytest.param(
+            "bin_edge",
+            np.array([0.0, 1.0]), np.array([0.0, 1.0]),
+            np.array([0.0, 1.0]),
+            id="bin-edge-shares",
+        ),
+    ],
+)
+def test_ensemble_merges_by_whole_type(
+    whole_names, ensemble_names, whole_type, first, second, expected
+):
+    """matrix stacks, dataframe averages, and bin_edge shares the wholes."""
+    wholes = {whole_names[(1, 1)]: first, whole_names[(1, 2)]: second}
+    ens = ensemble("gyrTMon", wholes, ChainCyl, "bug", whole_type)
+    np.testing.assert_array_equal(np.asarray(ens[ensemble_names[1]]),
+                                  expected)
+
+
+def test_ensemble_saves_each_ensemble(
+    tmp_path, whole_tree, ensemble_names
+):
+    """save_to writes each ensemble to <ensemble_long>-<group>-<prop>.csv."""
+    out = tmp_path / "out"
+    out.mkdir()
+    wholes = whole_from_file(whole_tree.paths, ChainCyl, "bug")
+    ens = ensemble("gyrTMon", wholes, ChainCyl, "bug", "vector",
+                   save_to=out)
+    name = ensemble_names[2]
+    pd.testing.assert_frame_equal(
+        pd.read_csv(out / f"{name}-bug-gyrTMon.csv"), ens[name]
+    )
+
+
+def test_ensemble_rejects_unknown_whole_type(whole_tree):
+    """A whole_type outside the four accepted values raises ValueError."""
+    wholes = whole_from_file(whole_tree.paths, ChainCyl, "bug")
+    with pytest.raises(ValueError, match="'nope' is an invalid option"):
+        ensemble("gyrTMon", wholes, ChainCyl, "bug", "nope")
+
+
+@pytest.fixture
+def hist_wholes():
+    """Return two replicate histogram wholes of one state point."""
+    base = (
+        "N2000r10.5lz300.0ac1.0nc117000dt0.005bdump5000adump"
+        "10000ens"
+    )
+    return {
+        f"{base}1": np.array([1.0, 2.0, 3.0]),
+        f"{base}2": np.array([3.0, 4.0, 5.0]),
+    }
+
+
+@pytest.fixture
+def hist_edges(hist_wholes):
+    """Return the same non-uniform bin edges for every whole in hist_wholes.
+
+    The edges are non-uniform so a wrong center formula cannot pass by
+    accident.
+    """
+    return {name: np.array([0.0, 1.0, 3.0, 6.0]) for name in hist_wholes}
+
+
+def test_ensemble_vector_bin_center_is_edge_midpoints(hist_wholes,
+                                                      hist_edges):
+    """With whole_edges, a vector ensemble's bin_center is the midpoints."""
+    ens = ensemble(
+        "rhoMon", hist_wholes, ChainCyl, "bug", "vector",
+        whole_edges=hist_edges,
+    )
+    (ens_df,) = ens.values()
+    # Analytic midpoints of the edges [0, 1, 3, 6]
+    np.testing.assert_allclose(ens_df["bin_center"], [0.5, 2.0, 4.5])
+    pd.testing.assert_frame_equal(
+        ens_df.drop(columns="bin_center"), pd.DataFrame(hist_wholes)
+    )
+
+
+def test_ensemble_without_whole_edges_has_no_bin_center(hist_wholes):
+    """Without whole_edges, a vector ensemble has one column per whole only."""
+    ens = ensemble("rhoMon", hist_wholes, ChainCyl, "bug", "vector")
+    (ens_df,) = ens.values()
+    assert list(ens_df.columns) == list(hist_wholes)
+
+
+def test_ensemble_avg_keeps_bin_center_from_ensemble(hist_wholes,
+                                                     hist_edges):
+    """ensemble_avg passes an ensemble's bin_center through unchanged."""
+    ens = ensemble(
+        "rhoMon", hist_wholes, ChainCyl, "bug", "vector",
+        whole_edges=hist_edges,
+    )
+    (ens_df,) = ens.values()
+    avg = ensemble_avg("rhoMon", ens, "bug", "dataframe")
+    (avg_df,) = avg.values()
+    np.testing.assert_array_equal(avg_df["bin_center"], ens_df["bin_center"])
+    assert list(avg_df.columns) == [
+        "bin_center", "rhoMon-mean", "rhoMon-var", "rhoMon-sem"
+    ]
+
+
+@pytest.mark.parametrize("whole_type", ["matrix", "dataframe", "bin_edge"])
+def test_ensemble_rejects_whole_edges_for_non_vector(
+    whole_type, hist_wholes, hist_edges
+):
+    """whole_edges with any whole_type other than 'vector' raises."""
+    with pytest.raises(ValueError, match="'whole_edges' is only valid"):
+        ensemble(
+            "rhoMon", hist_wholes, ChainCyl, "bug", whole_type,
+            whole_edges=hist_edges,
+        )
+
+
+# Averaging over an ensemble
+
+
+def test_ens_avg_from_ndarray_statistics_along_axis_0():
+    """Two wholes a, b give mean (a+b)/2, var (a-b)^2/2, sem |a-b|/2."""
+    a = np.array([[1.0, 2.0], [3.0, 4.0]])
+    b = np.array([[2.0, 5.0], [3.0, 8.0]])
+    out = ens_avg_from_ndarray("gyrTMon", np.stack([a, b]))
+    assert list(out) == ["gyrTMon-mean", "gyrTMon-var", "gyrTMon-sem"]
+    # Float64 round-off on values of order 10
+    np.testing.assert_allclose(out["gyrTMon-mean"], (a + b) / 2, atol=1e-12)
+    np.testing.assert_allclose(out["gyrTMon-var"], (a - b) ** 2 / 2,
+                               atol=1e-12)
+    np.testing.assert_allclose(out["gyrTMon-sem"], np.abs(a - b) / 2,
+                               atol=1e-12)
+
+
+def test_ens_avg_from_df_leaves_input_unchanged():
+    """ens_avg_from_df returns a new frame and leaves its input unchanged."""
+    ens_data = pd.DataFrame({
+        "bin_center": [1.0, 2.0],
+        "w1": [4.0, 5.0],
+        "w2": [5.0, 7.0],
+    })
+    before = ens_data.copy()
+    out = ens_avg_from_df("density", ens_data, ["bin_center"])
+    assert out is not ens_data
+    pd.testing.assert_frame_equal(ens_data, before)
+    assert list(out.columns) == [
+        "bin_center", "density-mean", "density-var", "density-sem"
+    ]
+
+
+def test_ens_avg_from_df_statistics():
+    """Two wholes a, b give mean (a+b)/2, var (a-b)^2/2, sem |a-b|/2."""
+    a = np.array([4.0, 5.0])
+    b = np.array([5.0, 7.0])
+    ens_data = pd.DataFrame({"bin_center": [1.0, 2.0], "w1": a, "w2": b})
+    out = ens_avg_from_df("density", ens_data, ["bin_center"])
+    np.testing.assert_allclose(out["density-mean"], (a + b) / 2)
+    np.testing.assert_allclose(out["density-var"], (a - b) ** 2 / 2)
+    np.testing.assert_allclose(out["density-sem"], np.abs(a - b) / 2)
+    np.testing.assert_array_equal(out["bin_center"], [1.0, 2.0])
+
+
+def test_ens_avg_from_bin_edge_copies_1d_edges():
+    """A single 1D edge array, as ensemble_avg passes it, is copied."""
+    edges = np.array([0.0, 0.5, 1.0])
+    out = ens_avg_from_bin_edge(edges)
+    np.testing.assert_array_equal(out, edges)
+    assert not np.shares_memory(out, edges)
+
+
+def test_ens_avg_from_bin_edge_reduces_equal_sequence():
+    """A sequence of equal edge arrays reduces to one copy of them."""
+    edges = np.array([0.0, 0.5, 1.0])
+    np.testing.assert_array_equal(
+        ens_avg_from_bin_edge([edges, edges.copy()]), edges
+    )
+
+
+def test_ens_avg_from_bin_edge_rejects_differing_sequence():
+    """A sequence of differing edge arrays raises ValueError."""
+    edges = np.array([0.0, 0.5, 1.0])
+    with pytest.raises(ValueError, match="Bin edges are not identical"):
+        ens_avg_from_bin_edge([edges, np.array([0.0, 0.5, 2.0])])
+
+
+def test_ensemble_avg_bin_edge_keeps_edges():
+    """ensemble_avg with 'bin_edge' returns each ensemble's edges intact."""
+    edges = np.array([0.0, 0.5, 1.0, 1.5])
+    out = ensemble_avg("rhoMon", {"ens1": edges}, "all", "bin_edge")
+    np.testing.assert_array_equal(out["ens1"], edges)
+
+
+def test_ensemble_avg_ndarray_averages_each_ensemble():
+    """ensemble_avg with 'ndarray' gives each ensemble's statistics dict."""
+    a = np.array([[1.0, 2.0]])
+    b = np.array([[3.0, 6.0]])
+    out = ensemble_avg("gyrTMon", {"ens1": np.stack([a, b])}, "bug",
+                       "ndarray")
+    np.testing.assert_allclose(out["ens1"]["gyrTMon-mean"], [[2.0, 4.0]])
+
+
+def test_ensemble_avg_rejects_unknown_ens_type():
+    """An ens_type outside dataframe, ndarray, and bin_edge raises."""
+    with pytest.raises(ValueError, match="'nope' is an invalid option"):
+        ensemble_avg("gyrTMon", {"ens1": np.zeros(2)}, "bug", "nope")
+
+
+@pytest.mark.parametrize(
+    "ensembles, ens_type, filenames",
+    [
+        pytest.param(
+            {"ens1": pd.DataFrame({"w1": [1.0], "w2": [3.0]})},
+            "dataframe",
+            ["ens1-bug-rhoMon-ensAvg.csv"],
+            id="dataframe-csv",
+        ),
+        pytest.param(
+            {"ens1": np.zeros((2, 1, 1))},
+            "ndarray",
+            [
+                "ens1-bug-rhoMon-ensAvg-mean.npy",
+                "ens1-bug-rhoMon-ensAvg-sem.npy",
+                "ens1-bug-rhoMon-ensAvg-var.npy",
+            ],
+            id="ndarray-npy-per-measure",
+        ),
+        pytest.param(
+            {"ens1": np.array([0.0, 1.0])},
+            "bin_edge",
+            ["ens1-bug-rhoMon-ensAvg.npy"],
+            id="bin-edge-npy",
+        ),
+    ],
+)
+def test_ensemble_avg_saves_under_ens_avg_name(
+    tmp_path, ensembles, ens_type, filenames
+):
+    """save_to writes each result under <ensemble>-<group>-<prop>-ensAvg."""
+    ensemble_avg("rhoMon", ensembles, "bug", ens_type, save_to=tmp_path)
+    assert sorted(os.listdir(tmp_path)) == filenames
+
+
+# Stamps
+
+
+@pytest.fixture
+def segment_stamps():
+    """Return stamps of 2 wholes x 3 segments of one state point.
+
+    n_frames is 10, 20, 30 and gyr is 1, 2, 3 for the segments of w1, and
+    gyr is 4, 5, 6 for those of w2.
+    """
+    return pd.DataFrame({
+        "lineage_name": ["w1.j01", "w1.j02", "w1.j03",
+                         "w2.j01", "w2.j02", "w2.j03"],
+        "segment": ["w1.j01", "w1.j02", "w1.j03",
+                    "w2.j01", "w2.j02", "w2.j03"],
+        "whole": ["w1", "w1", "w1", "w2", "w2", "w2"],
+        "ensemble_long": ["s1"] * 6,
+        "ensemble": ["e1"] * 6,
+        "space": ["N20"] * 6,
+        "group": ["bug"] * 6,
+        "segment_id": [1, 2, 3, 1, 2, 3],
+        "ensemble_id": [1, 1, 1, 2, 2, 2],
+        "gyr": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
+        "n_frames": [10, 20, 30, 10, 20, 30],
+    })
+
+
+@pytest.fixture
+def whole_stamps():
+    """Return stamps of 2 state points x 2 wholes, each of 60 frames.
+
+    The second state point keeps replicates ens1 and ens3, as if ens2 had
+    failed, so the number of wholes differs from the last ensemble_id.
+    """
+    return pd.DataFrame({
+        "lineage_name": ["w1", "w2", "w3", "w4"],
+        "segment": ["N/A"] * 4,
+        "whole": ["w1", "w2", "w3", "w4"],
+        "ensemble_long": ["s1", "s1", "s2", "s2"],
+        "ensemble": ["e1", "e1", "e2", "e2"],
+        "space": ["N20"] * 4,
+        "group": ["bug"] * 4,
+        "segment_id": [0, 0, 0, 0],
+        "ensemble_id": [1, 2, 1, 3],
+        "n_frames": [60, 60, 60, 60],
+    })
+
+
+@pytest.fixture
+def write_stamps(tmp_path):
+    """Factory: write each row of a stamps frame to its own CSV file."""
+
+    def _write(stamps):
+        directory = tmp_path / "stamps"
+        directory.mkdir()
+        paths = []
+        for row in range(len(stamps)):
+            path = directory / f"{stamps.loc[row, 'lineage_name']}-stamps.csv"
+            stamps.iloc[[row]].to_csv(path, index=False)
+            paths.append((str(path),))
+        return paths
+
+    return _write
+
+
+def test_children_stamps_concatenates_in_input_order(
+    write_stamps, segment_stamps
+):
+    """Segment stamp files combine row by row, in the order given."""
+    paths = write_stamps(segment_stamps)
+    combined = children_stamps(paths, "segment")
+    pd.testing.assert_frame_equal(combined, segment_stamps)
+
+
+def test_children_stamps_whole_drops_segment_columns(
+    write_stamps, whole_stamps
+):
+    """Whole stamps lose 'segment' and 'segment_id', with a UserWarning."""
+    paths = write_stamps(whole_stamps)
+    with pytest.warns(UserWarning, match="'segment' and 'segment_id'"):
+        combined = children_stamps(paths, "whole")
+    pd.testing.assert_frame_equal(
+        combined, whole_stamps.drop(columns=["segment", "segment_id"])
+    )
+
+
+def test_children_stamps_whole_without_segment_columns_is_unchanged(
+    write_stamps, whole_stamps, capsys
+):
+    """Whole stamps without segment columns pass through, printing nothing."""
+    stamps = whole_stamps.drop(columns=["segment", "segment_id"])
+    paths = write_stamps(stamps)
+
+    combined = children_stamps(paths, "whole")
+
+    pd.testing.assert_frame_equal(combined, stamps)
+    assert capsys.readouterr().out == ""
+
+
+@pytest.mark.parametrize(
+    "stamps_fixture, child_lineage, filename",
+    [
+        pytest.param("segment_stamps", "segment",
+                     "N20-bug-stamps-segment.csv", id="segment"),
+        pytest.param("whole_stamps", "whole", "N20-bug-stamps-whole.csv",
+                     id="whole", marks=pytest.mark.filterwarnings(
+                         "ignore:'segment' and 'segment_id':UserWarning")),
+    ],
+)
+def test_children_stamps_saves_under_rows_lineage(
+    request, tmp_path, write_stamps, stamps_fixture, child_lineage, filename
+):
+    """save_to writes the result as <space>-<group>-stamps-<level>.csv, with
+    the lineage level of its rows."""
+    paths = write_stamps(request.getfixturevalue(stamps_fixture))
+
+    combined = children_stamps(paths, child_lineage, save_to=tmp_path)
+
+    pd.testing.assert_frame_equal(pd.read_csv(tmp_path / filename), combined)
+
+
+@pytest.fixture
+def write_research_stamps(tmp_path):
+    """Factory: write each row of a stamps frame, without its 'group'
+    column, to its own CSV named <lineage_name><suffix>, as the research
+    code's probe did (the group is in the file name, not a column)."""
+
+    def _write(stamps, suffix="-bug-stamps.csv"):
+        directory = tmp_path / "stamps"
+        directory.mkdir(exist_ok=True)
+        stamps = stamps.drop(columns=["group"])
+        paths = []
+        for row in range(len(stamps)):
+            path = directory / f"{stamps.loc[row, 'lineage_name']}{suffix}"
+            stamps.iloc[[row]].to_csv(path, index=False)
+            paths.append((str(path),))
+        return paths
+
+    return _write
+
+
+@pytest.mark.parametrize(
+    "stamps_fixture, child_lineage, filename",
+    [
+        pytest.param("segment_stamps", "segment",
+                     "N20-bug-stamps-segment.csv", id="segment"),
+        pytest.param("whole_stamps", "whole", "N20-bug-stamps-whole.csv",
+                     id="whole", marks=pytest.mark.filterwarnings(
+                         "ignore:'segment' and 'segment_id':UserWarning")),
+    ],
+)
+def test_children_stamps_without_group_column_takes_it_from_the_file_names(
+    request, tmp_path, write_research_stamps, stamps_fixture, child_lineage,
+    filename
+):
+    """Stamps without a 'group' column, as the research code wrote them, get
+    one after 'space' from their <name>-<group>-stamps.csv file names, and
+    save under that group."""
+    stamps = request.getfixturevalue(stamps_fixture)
+    paths = write_research_stamps(stamps)
+
+    combined = children_stamps(paths, child_lineage, save_to=tmp_path)
+
+    assert (combined.columns.get_loc("group")
+            == combined.columns.get_loc("space") + 1)
+    assert combined["group"].tolist() == ["bug"] * len(combined)
+    pd.testing.assert_frame_equal(pd.read_csv(tmp_path / filename), combined)
+
+
+def test_children_stamps_without_group_rejects_a_name_without_a_group(
+    write_research_stamps, segment_stamps
+):
+    """Stamps with neither a 'group' column nor <name>-<group>-stamps.csv
+    file names raise ValueError naming the file."""
+    paths = write_research_stamps(segment_stamps, suffix="-stamps.csv")
+    with pytest.raises(ValueError, match="w1.j01-stamps.csv"):
+        children_stamps(paths, "segment")
+
+
+def test_children_stamps_without_group_rejects_mixed_groups(
+    write_research_stamps, segment_stamps
+):
+    """File names that give more than one group raise ValueError naming
+    them, instead of taking the first."""
+    paths = (write_research_stamps(segment_stamps.iloc[:3].reset_index(
+                drop=True))
+             + write_research_stamps(segment_stamps.iloc[3:].reset_index(
+                drop=True), suffix="-all-stamps.csv"))
+    with pytest.raises(ValueError, match=r"\['all', 'bug'\]"):
+        children_stamps(paths, "segment")
+
+
+def test_children_stamps_takes_child_lineage_by_keyword(
+    write_stamps, segment_stamps
+):
+    """The level of the stamps is the keyword argument child_lineage."""
+    paths = write_stamps(segment_stamps)
+
+    combined = children_stamps(paths, child_lineage="segment")
+
+    assert combined["segment_id"].tolist() == [1, 2, 3, 1, 2, 3]
+
+
+def test_children_stamps_rejects_unknown_lineage():
+    """A lineage other than segment or whole raises ValueError."""
+    with pytest.raises(ValueError, match="'nope' is an invalid option"):
+        children_stamps([], "nope")
+
+
+def test_parents_stamps_segment_counts_segments_and_sums_frames(
+    segment_stamps
+):
+    """Segment stamps give one row per whole with n_segments and n_frames."""
+    parents = parents_stamps(segment_stamps, "segment")
+    assert parents["whole"].tolist() == ["w1", "w2"]
+    assert parents["n_segments"].tolist() == [3, 3]
+    # 10 + 20 + 30 frames per whole
+    assert parents["n_frames"].tolist() == [60, 60]
+
+
+def test_parents_stamps_whole_counts_wholes_per_ensemble(whole_stamps):
+    """Whole stamps give one row per state point with n_ensembles."""
+    parents = parents_stamps(whole_stamps, "whole")
+    assert parents["ensemble_long"].tolist() == ["s1", "s2"]
+    assert parents["n_ensembles"].tolist() == [2, 2]
+    assert parents["n_frames"].tolist() == [60, 60]
+    assert {"segment", "segment_id", "whole"}.isdisjoint(parents.columns)
+
+
+def test_parents_stamps_whole_drops_n_segments(whole_stamps):
+    """Whole stamps built from segments lose n_segments in their parents."""
+    stamps = whole_stamps.assign(n_segments=[3, 3, 3, 3])
+    parents = parents_stamps(stamps, "whole")
+    assert "n_segments" not in parents.columns
+
+
+def test_parents_stamps_applies_given_aggregation(segment_stamps):
+    """properties replaces the default 'last' aggregation of a column."""
+    parents = parents_stamps(segment_stamps, "segment",
+                             properties={"gyr": "mean"})
+    # Means of 1, 2, 3 and of 4, 5, 6
+    assert parents["gyr"].tolist() == pytest.approx([2.0, 5.0])
+
+
+@pytest.mark.parametrize(
+    "stamps_fixture, lineage, filename",
+    [
+        pytest.param("segment_stamps", "segment", "N20-bug-stamps-whole.csv",
+                     id="segment-to-whole"),
+        pytest.param("whole_stamps", "whole",
+                     "N20-bug-stamps-ensemble_long.csv",
+                     id="whole-to-ensemble_long"),
+    ],
+)
+def test_parents_stamps_saves_under_parents_lineage(
+    request, tmp_path, stamps_fixture, lineage, filename
+):
+    """save_to writes the parent stamps as <space>-<group>-stamps-<level>.csv,
+    with the lineage level of the parent rows."""
+    stamps = request.getfixturevalue(stamps_fixture)
+    parents = parents_stamps(stamps, lineage, save_to=tmp_path)
+    pd.testing.assert_frame_equal(pd.read_csv(tmp_path / filename), parents)
+
+
+@pytest.mark.parametrize("column", ["space", "group"])
+def test_parents_stamps_saving_without_a_name_column_raises(
+    tmp_path, whole_stamps, column
+):
+    """Saving parent stamps that lack 'space' or 'group' raises ValueError
+    naming the column, since the file name needs both."""
+    stamps = whole_stamps.drop(columns=[column])
+    with pytest.raises(ValueError, match=f"'{column}'"):
+        parents_stamps(stamps, "whole", save_to=tmp_path)
+
+
+@pytest.mark.parametrize(
+    "stamps_fixture, lineage",
+    [
+        pytest.param("segment_stamps", "segment", id="segment"),
+        pytest.param("whole_stamps", "whole", id="whole"),
+    ],
+)
+def test_parents_stamps_without_lineage_name_drops_child_column(
+    request, stamps_fixture, lineage
+):
+    """Stamps without 'lineage_name' still lose the child lineage column."""
+    stamps = request.getfixturevalue(stamps_fixture).drop(
+        columns="lineage_name")
+
+    parents = parents_stamps(stamps, lineage)
+
+    assert lineage not in parents.columns
+
+
+def test_parents_stamps_without_lineage_name_prints_nothing(
+    segment_stamps, capsys
+):
+    """An absent 'lineage_name' column is skipped without printing."""
+    stamps = segment_stamps.drop(columns="lineage_name")
+
+    parents_stamps(stamps, "segment")
+
+    assert capsys.readouterr().out == ""
+
+
+def test_parents_stamps_takes_child_lineage_by_keyword(segment_stamps):
+    """The level of the child stamps is the keyword argument child_lineage."""
+    parents = parents_stamps(segment_stamps, child_lineage="segment")
+
+    assert parents["n_segments"].tolist() == [3, 3]
+
+
+@pytest.mark.parametrize(
+    "stamps_fixture, child_lineage, key",
+    [
+        pytest.param("segment_stamps", "segment", "whole", id="segment"),
+        pytest.param("whole_stamps", "whole", "ensemble_long", id="whole"),
+    ],
+)
+def test_parents_stamps_rejects_a_missing_parent_name(
+    request, stamps_fixture, child_lineage, key
+):
+    """A child row with no parent name raises instead of being dropped by
+    the group-by."""
+    stamps = request.getfixturevalue(stamps_fixture)
+    stamps.loc[0, key] = np.nan
+
+    with pytest.raises(ValueError, match=re.escape(
+            f"1 stamps row has no {key!r}")):
+        parents_stamps(stamps, child_lineage)
+
+
+@pytest.mark.parametrize("column", ["n_frames", "segment_id", "whole"])
+def test_parents_stamps_rejects_aggregating_its_own_columns(
+    segment_stamps, column
+):
+    """A properties entry for a column the parent aggregates itself raises
+    instead of being overwritten silently."""
+    with pytest.raises(ValueError, match=re.escape(
+            f"properties cannot set {column!r}")):
+        parents_stamps(segment_stamps, "segment", properties={column: "max"})
+
+
+def test_parents_stamps_rejects_unknown_lineage(segment_stamps):
+    """A lineage other than segment or whole raises ValueError."""
+    with pytest.raises(ValueError, match="'nope' is an invalid option"):
+        parents_stamps(segment_stamps, "nope")
+
+
+# Space level: ensemble-averaged files of two state points that differ only
+# in the number of crowders. Both dump every 5000 steps with dt=0.005.
+
+
+@pytest.fixture
+def space_states():
+    """Return the ensemble_long names of the two synthetic state points."""
+    return [
+        "N200r10.5lz25.0ac2.0nc1000dt0.005bdump2000adump5000",
+        "N200r10.5lz25.0ac2.0nc2000dt0.005bdump2000adump5000",
+    ]
+
+
+@pytest.fixture
+def make_ens_avg_space(tmp_path, space_states):
+    """Factory: write one ensAvg CSV per state point, plus a decoy file.
+
+    Takes the property, one '-mean' column per state point, and the group
+    (default 'all'); '-var' and '-sem' are constant. Returns the ensAvg
+    directory, ending with '/'.
+    """
+
+    def _make(prop, means, group="all"):
+        ens_avg_dir = tmp_path / "analysis" / f"N200-{group}-ensAvg"
+        ens_avg_dir.mkdir(parents=True)
+        for state, mean in zip(space_states, means):
+            pd.DataFrame({
+                f"{prop}-mean": mean,
+                f"{prop}-var": np.full(len(mean), 0.1),
+                f"{prop}-sem": np.full(len(mean), 0.05),
+            }).to_csv(ens_avg_dir / f"{state}-{group}-{prop}-ensAvg.csv",
+                      index=False)
+        # A file of another property in the same directory must be ignored.
+        pd.DataFrame({"other-mean": [1.0]}).to_csv(
+            ens_avg_dir / f"{space_states[0]}-{group}-other-ensAvg.csv",
+            index=False,
+        )
+        return str(ens_avg_dir) + "/"
+
+    return _make
+
+
+@pytest.fixture
+def state_attr(space_states):
+    """Factory: an attribute of each state point, repeated n_rows times."""
+
+    def _values(attr, n_rows):
+        parsers = [ChainCyl(s, "ensemble_long", "all") for s in space_states]
+        return np.repeat([getattr(p, attr) for p in parsers], n_rows)
+
+    return _values
+
+
+def test_space_tseries_concatenates_ensembles(make_ens_avg_space,
+                                              state_attr):
+    """space_tseries reads every '-<prop>-ensAvg.csv' file and no other."""
+    database = make_ens_avg_space(
+        "gyrTMon", [[0.0, 1.0, 2.0], [10.0, 11.0, 12.0]]
+    )
+    space = space_tseries(database, "gyrTMon", ChainCyl, "N*", ["dcyl"],
+                          "all")
+    assert list(space.index) == list(range(6))
+    assert "other-mean" not in space.columns
+    # Files are sorted by name, so the nc1000 rows come first.
+    np.testing.assert_allclose(
+        space["gyrTMon-mean"], [0.0, 1.0, 2.0, 10.0, 11.0, 12.0]
+    )
+    np.testing.assert_allclose(space["dcyl"], state_attr("dcyl", 3))
+
+
+def test_space_tseries_reads_database_without_trailing_separator(
+        make_ens_avg_space):
+    """The directory is joined to the glob as a path, so it reads the same
+    files with or without a trailing separator."""
+    database = make_ens_avg_space(
+        "gyrTMon", [[0.0, 1.0, 2.0], [10.0, 11.0, 12.0]]
+    )
+
+    space = space_tseries(database.rstrip("/"), "gyrTMon", ChainCyl, "N*",
+                          [], "all")
+
+    np.testing.assert_allclose(
+        space["gyrTMon-mean"], [0.0, 1.0, 2.0, 10.0, 11.0, 12.0]
+    )
+
+
+def test_space_tseries_scales_t_index_and_time(make_ens_avg_space):
+    """For all, t_index is frame index times adump; time is t_index * dt."""
+    database = make_ens_avg_space("gyrTMon", [[0.0, 1.0, 2.0]] * 2)
+    space = space_tseries(database, "gyrTMon", ChainCyl, "N*", [], "all")
+    frames = np.array([0, 1, 2, 0, 1, 2])
+    # adump = 5000 and dt = 0.005 in the filenames
+    np.testing.assert_array_equal(space["t_index"], frames * 5000)
+    np.testing.assert_allclose(space["time"], frames * 5000 * 0.005)
+
+
+def test_space_tseries_scales_bug_by_bdump(make_ens_avg_space):
+    """For bug, t_index is frame index times bdump, not adump."""
+    database = make_ens_avg_space("gyrTMon", [[0.0, 1.0, 2.0]] * 2,
+                                  group="bug")
+    space = space_tseries(database, "gyrTMon", ChainCyl, "N*", [], "bug")
+    frames = np.array([0, 1, 2, 0, 1, 2])
+    # bdump = 2000 and dt = 0.005 in the filenames
+    np.testing.assert_array_equal(space["t_index"], frames * 2000)
+    np.testing.assert_allclose(space["time"], frames * 2000 * 0.005)
+
+
+def test_space_tseries_rejects_dump_key_argument(make_ens_avg_space):
+    """A dump keyword passed by position fails instead of binding divisor."""
+    database = make_ens_avg_space("gyrTMon", [[0.0, 1.0, 2.0]] * 2)
+    with pytest.raises(TypeError, match="takes 6 positional arguments"):
+        space_tseries(database, "gyrTMon", ChainCyl, "N*", [], "all",
+                      "adump")
+
+
+def test_space_tseries_adds_phi_bulk_c_by_default(make_ens_avg_space,
+                                                  state_attr):
+    """The crowder fraction comes from phi_bulk_c without being listed."""
+    database = make_ens_avg_space("gyrTMon", [[0.0, 1.0, 2.0]] * 2)
+    space = space_tseries(database, "gyrTMon", ChainCyl, "N*", ["dcyl"],
+                          "all")
+    assert "phi_c_bulk" not in space.columns
+    np.testing.assert_allclose(space["phi_bulk_c"],
+                               state_attr("phi_bulk_c", 3))
+
+
+def test_space_tseries_rounds_crowder_with_round_to_multiple(
+    make_ens_avg_space
+):
+    """phi_bulk_c_round is round_to_multiple of the crowder column."""
+    database = make_ens_avg_space("gyrTMon", [[0.0, 1.0, 2.0]] * 2)
+    space = space_tseries(database, "gyrTMon", ChainCyl, "N*", [], "all",
+                          divisor=0.05, round_to=2)
+    expected = space["phi_bulk_c"].apply(round_to_multiple, args=(0.05, 2))
+    np.testing.assert_array_equal(space["phi_bulk_c_round"], expected)
+
+
+def test_space_tseries_reads_named_crowder_attr(make_ens_avg_space,
+                                                state_attr):
+    """crowder_attr selects the parser attribute that is rounded."""
+    database = make_ens_avg_space("gyrTMon", [[0.0, 1.0, 2.0]] * 2)
+    space = space_tseries(database, "gyrTMon", ChainCyl, "N*", [], "all",
+                          crowder_attr="phi_bulk_m")
+    assert "phi_bulk_c" not in space.columns
+    np.testing.assert_allclose(space["phi_bulk_m"],
+                               state_attr("phi_bulk_m", 3))
+
+
+def test_space_tseries_saves_space_csv(tmp_path, make_ens_avg_space):
+    """is_save writes the returned frame to the analysis space directory."""
+    database = make_ens_avg_space("gyrTMon", [[0.0, 1.0, 2.0]] * 2)
+    space = space_tseries(database, "gyrTMon", ChainCyl, "N*", ["dcyl"],
+                          "all", is_save=True)
+    saved = tmp_path / "analysis" / "N200-all-space" / \
+        "N200-all-gyrTMon-space.csv"
+    pd.testing.assert_frame_equal(pd.read_csv(saved), space)
+
+
+def test_space_hists_concatenates_and_normalizes(make_ens_avg_space,
+                                                 state_attr):
+    """space_hists adds bin centers and each normalized histogram sums to 1."""
+    database = make_ens_avg_space(
+        "rhoMon", [[1.0, 2.0, 1.0], [2.0, 4.0, 2.0]]
+    )
+    bin_center = np.array([0.5, 1.5, 2.5])
+    space = space_hists(database, "rhoMon", ChainCyl, "N*", ["dcyl"],
+                        "all", bin_center=bin_center, normalize=True)
+    assert len(space) == 6
+    assert "other-mean" not in space.columns
+    np.testing.assert_allclose(space["bin_center"], np.tile(bin_center, 2))
+    np.testing.assert_allclose(space["bin_center-norm"],
+                               np.tile(bin_center / 2.5, 2))
+    # [1, 2, 1] / 4 and [2, 4, 2] / 8
+    np.testing.assert_allclose(space["rhoMon-norm"],
+                               [0.25, 0.5, 0.25, 0.25, 0.5, 0.25])
+    np.testing.assert_allclose(space["dcyl"], state_attr("dcyl", 3))
+    np.testing.assert_allclose(space["phi_bulk_c"],
+                               state_attr("phi_bulk_c", 3))
+
+
+def test_space_hists_zero_histogram_normalizes_to_zero(make_ens_avg_space):
+    """An all-zero histogram warns and gets a zero normalized column."""
+    database = make_ens_avg_space("rhoMon", [[0.0, 0.0], [0.0, 0.0]])
+    with pytest.warns(UserWarning, match="All values are zero"):
+        space = space_hists(database, "rhoMon", ChainCyl, "N*", [], "all",
+                            normalize=True)
+    np.testing.assert_array_equal(space["rhoMon-norm"], np.zeros(4))
+
+
+def test_space_hists_saves_space_csv(tmp_path, make_ens_avg_space):
+    """is_save writes the returned frame to the analysis space directory."""
+    database = make_ens_avg_space("rhoMon", [[1.0, 2.0, 1.0]] * 2)
+    space = space_hists(database, "rhoMon", ChainCyl, "N*", [], "all",
+                        is_save=True)
+    saved = tmp_path / "analysis" / "N200-all-space" / \
+        "N200-all-rhoMon-space.csv"
+    pd.testing.assert_frame_equal(pd.read_csv(saved), space)
+
+
+# Integration along the lineage: segment -> whole -> ensemble -> ensAvg
+# -> space, on one segment tree.
+
+
+def test_lineage_tseries_ensemble_average_matches_tree_values(
+    segment_tree, ensemble_names
+):
+    """Two wholes 100 apart average to 1000e + 150 + 10s + k, var 5000."""
+    paths = [str(p) for p in segment_tree.paths]
+    wholes = whole_from_segments("gyrTMon", paths, ChainCyl, "bug",
+                                 "tseries")
+    ens = ensemble("gyrTMon", wholes, ChainCyl, "bug", "vector")
+    avg = ensemble_avg("gyrTMon", ens, "bug", "dataframe")
+    ens_1 = avg[ensemble_names[1]]
+    np.testing.assert_allclose(
+        ens_1["gyrTMon-mean"],
+        [1160.0, 1161.0, 1162.0, 1170.0, 1171.0, 1172.0],
+    )
+    # var (ddof=1) of two values 100 apart is 100**2 / 2; sem is
+    # sqrt(5000 / 2). Float64 round-off on values of order 1e3.
+    np.testing.assert_allclose(ens_1["gyrTMon-var"], 5000.0, rtol=1e-12)
+    np.testing.assert_allclose(ens_1["gyrTMon-sem"], 50.0, rtol=1e-12)
+
+
+def test_lineage_saved_ens_avg_feeds_space_tseries(tmp_path, segment_tree):
+    """ensAvg files saved by ensemble_avg are the files space_tseries reads."""
+    ens_avg_dir = tmp_path / "analysis" / "N20-bug-ensAvg"
+    ens_avg_dir.mkdir(parents=True)
+    paths = [str(p) for p in segment_tree.paths]
+    wholes = whole_from_segments("gyrTMon", paths, ChainCyl, "bug",
+                                 "tseries")
+    ens = ensemble("gyrTMon", wholes, ChainCyl, "bug", "vector")
+    ensemble_avg("gyrTMon", ens, "bug", "dataframe", save_to=ens_avg_dir)
+    space = space_tseries(str(ens_avg_dir) + "/", "gyrTMon", ChainCyl,
+                          "N*", [], "bug")
+    # 2 ensembles x 6 frames; ensemble 2 is 1000 above ensemble 1
+    np.testing.assert_allclose(
+        space["gyrTMon-mean"],
+        [1160.0, 1161.0, 1162.0, 1170.0, 1171.0, 1172.0,
+         2160.0, 2161.0, 2162.0, 2170.0, 2171.0, 2172.0],
+    )
+    # bdump = 1000, the dump period of the bug trajectory, in the tree's
+    # filenames
+    np.testing.assert_array_equal(
+        space["t_index"], np.tile(np.arange(6), 2) * 1000
+    )
+
+
+def test_lineage_histogram_conserves_total_counts(segment_tree):
+    """Histogram counts summed over a space equal those over its segments."""
+    paths = [str(p) for p in segment_tree.paths]
+    wholes = whole_from_segments("gyrTMon", paths, ChainCyl, "bug",
+                                 "histogram")
+    ens = ensemble("gyrTMon", wholes, ChainCyl, "bug", "vector")
+    avg = ensemble_avg("gyrTMon", ens, "bug", "dataframe")
+    # Ensemble mean times 2 wholes, summed over bins and ensembles
+    total = 2 * pd.concat(avg.values())["gyrTMon-mean"].sum()
+    # Sum of 1000e + 100w + 10s + k over e, w, s in {1, 2} and k in
+    # {0, 1, 2}: 24 * (1500 + 150 + 15) + 8 * (0 + 1 + 2)
+    assert total == pytest.approx(39984.0, rel=1e-12)
+
+
+# Renaming the bulk-quantity columns of research-code tables
+
+
+@pytest.fixture
+def old_bulk_table():
+    """A stamp-like row with every research-code bulk name and two others."""
+    columns = {"ensemble_long": ["N20ac1nc100"], "nmon": [20]}
+    columns.update({old: [float(i)] for i, old in enumerate(BULK_NAME_MAP)})
+    return pd.DataFrame(columns)
+
+
+@pytest.mark.parametrize(
+    "old, new",
+    [
+        pytest.param("phi_m_bulk", "phi_bulk_m", id="phi_m"),
+        pytest.param("rho_m_bulk", "rho_bulk_m", id="rho_m"),
+        pytest.param("phi_c_bulk", "phi_bulk_c", id="phi_c"),
+        pytest.param("rho_c_bulk", "rho_bulk_c", id="rho_c"),
+        pytest.param("phi_c_bulk_one", "phi_bulk_c_one", id="phi_c_one"),
+        pytest.param("phi_c_bulk_two", "phi_bulk_c_two", id="phi_c_two"),
+        pytest.param("rho_c_bulk_one", "rho_bulk_c_one", id="rho_c_one"),
+        pytest.param("rho_c_bulk_two", "rho_bulk_c_two", id="rho_c_two"),
+        pytest.param("phi_hns_bulk", "phi_bulk_hns", id="phi_hns"),
+        pytest.param("rho_hns_bulk", "rho_bulk_hns", id="rho_hns"),
+        pytest.param("phi_c_bulk_round", "phi_bulk_c_round", id="phi_c_round"),
+    ],
+)
+def test_bulk_name_map_pairs_each_old_name_with_its_new_name(old, new):
+    """Every research-code bulk name maps to its <quantity>_bulk_<species>."""
+    assert BULK_NAME_MAP[old] == new
+
+
+def test_bulk_name_map_has_only_the_eleven_pairs():
+    """The map holds exactly the eleven research-code names and no alias."""
+    assert len(BULK_NAME_MAP) == 11
+
+
+def test_bulk_name_map_is_read_only():
+    """The map rejects assignment."""
+    with pytest.raises(TypeError, match="does not support item assignment"):
+        BULK_NAME_MAP["phi_c_bulk"] = "other"  # type: ignore[index]
+
+
+def test_rename_bulk_columns_renames_every_mapped_column(old_bulk_table):
+    """Each mapped column takes its new name and keeps its value."""
+    new = rename_bulk_columns(old_bulk_table)
+    for old, expected in BULK_NAME_MAP.items():
+        assert old not in new.columns
+        assert new[expected].tolist() == old_bulk_table[old].tolist()
+
+
+def test_rename_bulk_columns_keeps_other_columns_and_order(old_bulk_table):
+    """Unmapped columns and the column order are unchanged."""
+    new = rename_bulk_columns(old_bulk_table)
+    expected = [BULK_NAME_MAP.get(c, c) for c in old_bulk_table.columns]
+    assert list(new.columns) == expected
+    assert new["ensemble_long"].tolist() == ["N20ac1nc100"]
+    assert new["nmon"].tolist() == [20]
+
+
+def test_rename_bulk_columns_does_not_modify_its_input(old_bulk_table):
+    """The input table keeps the research-code names after the call."""
+    before = list(old_bulk_table.columns)
+    rename_bulk_columns(old_bulk_table)
+    assert list(old_bulk_table.columns) == before
+
+
+def test_rename_bulk_columns_leaves_new_names_unchanged(old_bulk_table):
+    """A table that already carries the PolyPhys names comes back equal."""
+    new = rename_bulk_columns(old_bulk_table)
+    pd.testing.assert_frame_equal(rename_bulk_columns(new), new)