Overview¶

Task-focused recipes for common jobs. Each one is short and assumes you’ve met the basics in the Quickstart.

Sample data for these guides¶

The recipes below assume a small ensemble.bendl, a plans.jsonl, a chain.ben / chain.xben pair, and a gerrymandria.json dual graph in your working directory. To follow along, create them all with this snippet:

import json

import networkx as nx

from binary_ensemble import BendlEncoder, BenEncoder, encode_ben_to_xben

# A small dual graph: an 8x8 grid with unit population, contiguous stripe districts,
# and a GEOID20-style key to sort on.
SIDE = 8
graph = nx.convert_node_labels_to_integers(nx.grid_2d_graph(SIDE, SIDE))
for node in graph.nodes:
    _row, col = divmod(node, SIDE)
    graph.nodes[node].update(TOTPOP=1, district=col // 2 + 1, GEOID20=f"{node:04d}")
adjacency = nx.adjacency_data(graph)
n_nodes = SIDE * SIDE

# The GerryChain how-to reads the dual graph from this file.
with open("gerrymandria.json", "w") as handle:
    json.dump(adjacency, handle)

# 120 toy plans on the grid's nodes.
plans = [[(node + step) % 4 + 1 for node in range(n_nodes)] for step in range(120)]

# A self-describing bundle (graph + metadata + the plans)...
encoder = BendlEncoder("ensemble.bendl", overwrite=True)
encoder.add_graph(adjacency, sort=None)
encoder.add_metadata({"sampler": "demo", "seed": 0})
with encoder.ben_stream() as ensemble:
    for plan in plans:
        ensemble.write(plan)

# ...the same plans as JSONL...
with open("plans.jsonl", "w") as handle:
    for sample, plan in enumerate(plans, start=1):
        handle.write(json.dumps({"assignment": plan, "sample": sample}) + "\n")

# ...and as plain BEN / XBEN streams.
with BenEncoder("chain.ben", overwrite=True) as ensemble:
    for plan in plans:
        ensemble.write(plan)
encode_ben_to_xben("chain.ben", "chain.xben", overwrite=True)