camber-toolkit 0.1.0__py3-none-any.whl

camber/__init__.py

@@ -0,0 +1,3 @@
+"""CAMBER — Commissioning, Analytics & M&V for Building Energy Re-tuning."""
+
+__version__ = "0.1.0"

camber/ahu.py

@@ -0,0 +1,137 @@
+"""AHU-level diagnostics: simultaneous heating/cooling, economizer, SA behavior.
+
+An AHU that carries both a chilled-water coil (``CHW_Valve`` %) and a hot-water
+coil (``HHW_Valve`` %), plus mixed/return/supply air temps, OA damper, and an
+economizer command, supports these checks:
+
+1. **Simultaneous H/C at the AHU** -- CHW and HHW valves both open at once. This
+   is the central-plant analogue of the terminal-box reheat penalty and the most
+   direct read on coil-against-coil "fighting".
+2. **Economizer faults** -- when outdoor air is cooler than return air and within
+   the economizer high-limit, the OA damper should modulate open for free
+   cooling; flag intervals where it stays shut while the CHW valve is cooling.
+3. **Supply-air / mixed-air sanity** -- basic coverage + ranges so downstream
+   reset diagnostics have a vetted input.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+
+import pandas as pd
+
+from .schedules import occupied_mask
+
+AHU_MEASURES = [
+    "CHW_Valve", "HHW_Valve", "SupplyAir", "MixedAir", "ReturnAir",
+    "OSA", "OA_Damper", "EconoCmd", "DuctStatic", "DuctStaticSP",
+    "Occupancy", "WarmUp", "CoolDown",
+]
+
+
+@dataclass
+class AHUResult:
+    """AHU simultaneous heating/cooling and economizer diagnostics for one unit."""
+
+    equip: str
+    n_intervals: int
+    n_considered: int
+    chw_open_pct: float
+    hhw_open_pct: float
+    simultaneous_hc_pct: float          # both valves open
+    mean_overlap_when_simul: float      # mean min(CHW,HHW) during overlap
+    econ_opportunity_pct: float         # intervals economizer SHOULD help
+    econ_missed_pct: float              # of opportunity, damper stayed shut while cooling
+    coverage_start: str
+    coverage_end: str
+
+    def as_dict(self):
+        """Return the result as a plain dict."""
+        return asdict(self)
+
+
+def _pct(mask, n):
+    return round(100.0 * int(mask.sum()) / n, 2) if n else 0.0
+
+
+def _populated(df, col):
+    """Return df[col] only if present and not entirely null, else None.
+
+    Lets occupied_mask AND in a real occupancy point when one exists, while
+    falling back to the weekday window when the BAS point is empty/absent.
+    """
+    if col in df.columns and df[col].notna().any():
+        return df[col]
+    return None
+
+
+def analyze_ahu(df, equip, *, valve_thr=5.0, econ_high_limit_f=70.0,
+                damper_min_open=20.0, occupied_only=True):
+    """Compute AHU H/C + economizer metrics. ``df`` columns are measure names.
+
+    Threshold basis (economizer logic, PNNL Re-tuning Ch.6):
+      valve_thr=5.0 %       -- valve <5% open counted as shut (noise deadband).
+      econ_high_limit_f=70  -- economizer high limit; above this OAT, free cooling is
+                               disabled, so it's not an "opportunity". 70F is a common
+                               dry-bulb high-limit; verify against the site's sequence.
+      damper_min_open=20.0 %-- below ~20% the OA damper is at its minimum-position
+                               (ventilation only), i.e. not economizing. "20% damper is
+                               never 20% OA" (Ch.6) -- this gates the *damper command*,
+                               not the actual OA fraction.
+    The economizer-opportunity test also requires OA cooler than return air by a small
+    margin (oa < ra - 2.0 F); the 2F guard avoids flagging when OA and RA are
+    effectively equal (no useful free cooling, within sensor tolerance).
+    """
+    if "CHW_Valve" not in df.columns or "HHW_Valve" not in df.columns:
+        return None
+    work = df.copy()
+    n_all = len(work)
+    if n_all == 0:
+        return None
+
+    if occupied_only:
+        work = work[occupied_mask(
+            work.index,
+            occ=_populated(work, "Occupancy"),
+            warmup=work["WarmUp"] if "WarmUp" in work.columns else None,
+            cooldown=work["CoolDown"] if "CoolDown" in work.columns else None,
+        )]
+    n = len(work)
+    if n == 0:
+        return None
+
+    chw = work["CHW_Valve"]
+    hhw = work["HHW_Valve"]
+    chw_open = chw > valve_thr
+    hhw_open = hhw > valve_thr
+    simul = chw_open & hhw_open
+    overlap_mag = work.loc[simul, ["CHW_Valve", "HHW_Valve"]].min(axis=1)
+
+    # Economizer: opportunity = cooling called (CHW open) AND OA cooler than return
+    # AND OA below high-limit. Missed = opportunity but OA damper effectively shut.
+    if "OSA" in work.columns and "ReturnAir" in work.columns:
+        oa = work["OSA"]
+        ra = work["ReturnAir"]
+        opp = chw_open & (oa < ra - 2.0) & (oa < econ_high_limit_f)
+        if "OA_Damper" in work.columns:
+            missed = opp & (work["OA_Damper"].fillna(0) < damper_min_open)
+        else:
+            missed = pd.Series(False, index=work.index)
+        opp_pct = _pct(opp, n)
+        missed_pct = round(100.0 * int(missed.sum()) / int(opp.sum()), 2) if opp.sum() else 0.0
+    else:
+        opp_pct = missed_pct = 0.0
+
+    return AHUResult(
+        equip=equip,
+        n_intervals=n_all,
+        n_considered=n,
+        chw_open_pct=_pct(chw_open, n),
+        hhw_open_pct=_pct(hhw_open, n),
+        simultaneous_hc_pct=_pct(simul, n),
+        mean_overlap_when_simul=round(float(overlap_mag.mean()), 1) if simul.any() else 0.0,
+        econ_opportunity_pct=opp_pct,
+        econ_missed_pct=missed_pct,
+        coverage_start=str(df.index.min()),
+        coverage_end=str(df.index.max()),
+    )

camber/api/__init__.py

@@ -0,0 +1,6 @@
+"""Read API for the time-series store (capability-map §8)."""
+
+from .read import ReadAPI
+from .server import dispatch, make_server, serve
+
+__all__ = ["ReadAPI", "dispatch", "make_server", "serve"]

camber/api/read.py

@@ -0,0 +1,52 @@
+"""Read API facade over the time-series store (capability-map §8).
+
+A small, transport-agnostic surface that returns JSON-serializable dicts for the
+three things an external tool needs: the sites in the store, the catalog of stored
+series, and point history. The HTTP layer in :mod:`camber.api.server` is a thin
+wrapper over this; tests and in-process callers use the facade directly.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+
+class ReadAPI:
+    """Query facade over a :class:`~camber.store.ParquetStore`."""
+
+    def __init__(self, store):
+        self.store = store
+
+    def about(self) -> dict:
+        """Service info: name, liveness flag, and the sites in the store."""
+        return {"service": "camber read-api", "ok": True,
+                "sites": self.store.sites()}
+
+    def sites(self) -> dict:
+        """List the sites present in the store."""
+        return {"sites": self.store.sites()}
+
+    def points(self, *, site=None, equip=None, role=None) -> dict:
+        """Catalog of stored series, optionally filtered by site/equip/role."""
+        keys = self.store.points(site=site)
+        rows = [{"site": k.site, "equip": k.equip, "role": k.role} for k in keys
+                if (equip is None or k.equip == equip)
+                and (role is None or k.role == role)]
+        return {"points": rows, "count": len(rows)}
+
+    def history(self, *, site=None, equip=None, role=None, start=None, end=None,
+                limit=None) -> dict:
+        """Point history (long form) with ISO timestamps, optionally limited."""
+        long = self.store.read_long(
+            site=site,
+            equips=[equip] if equip else None,
+            roles=[role] if role else None,
+            start=start, end=end)
+        if not long.empty and limit:
+            long = long.head(int(limit))
+        rows = [] if long.empty else [
+            {"ts": pd.Timestamp(ts).isoformat(), "equip": eq, "role": rl,
+             "value": (None if pd.isna(v) else float(v))}
+            for ts, eq, rl, v in zip(long["ts"], long["equip"],
+                                     long["role"], long["value"])]
+        return {"history": rows, "count": len(rows)}

camber/api/server.py

@@ -0,0 +1,101 @@
+"""HTTP server for the read API (stdlib only -- no web-framework dependency).
+
+Routes are factored into a pure :func:`dispatch` function (method, path, query ->
+(status, body)) so the routing is unit-testable without binding a socket; the
+:class:`http.server` handler is a thin wrapper that parses the request, calls
+``dispatch``, and writes JSON. Read-only: only GET is served.
+
+Endpoints:
+  GET /            | /about | /health   -> service info
+  GET /sites                            -> {"sites": [...]}
+  GET /points?site=&equip=&role=        -> {"points": [...], "count": n}
+  GET /history?site=&equip=&role=&start=&end=&limit=  -> {"history": [...], "count": n}
+"""
+
+from __future__ import annotations
+
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from .read import ReadAPI
+
+
+def _q(query: dict, *keys):
+    """Pick present single-valued query params from a parsed query dict."""
+    return {k: query[k][0] for k in keys if query.get(k)}
+
+
+def dispatch(api: ReadAPI, method: str, path: str, query: dict):
+    """Route a request to the read API. Returns ``(status_code, body_dict)``."""
+    if method != "GET":
+        return 405, {"error": "method not allowed", "method": method}
+    if path in ("/", "/about", "/health"):
+        return 200, api.about()
+    if path == "/sites":
+        return 200, api.sites()
+    if path == "/points":
+        return 200, api.points(**_q(query, "site", "equip", "role"))
+    if path == "/history":
+        kw = _q(query, "site", "equip", "role", "start", "end", "limit")
+        return 200, api.history(**kw)
+    return 404, {"error": "not found", "path": path}
+
+
+class ReadAPIHandler(BaseHTTPRequestHandler):
+    """BaseHTTPRequestHandler bound to a ReadAPI via ``server.api``."""
+
+    def do_GET(self):  # noqa: N802 (stdlib naming)
+        """Parse the request, dispatch to the read API, and write the JSON response."""
+        parsed = urlparse(self.path)
+        query = parse_qs(parsed.query)
+        try:
+            status, body = dispatch(self.server.api, "GET", parsed.path, query)
+        except Exception as exc:  # never leak a stack trace over the wire
+            status, body = 500, {"error": "internal error", "detail": str(exc)}
+        payload = json.dumps(body).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, *args):  # keep the test/CLI output quiet
+        """Suppress the default per-request stderr logging."""
+        pass
+
+
+def make_server(store, *, host: str = "127.0.0.1", port: int = 8080):
+    """Create (but don't start) a threading HTTP server bound to ``store``.
+
+    ``port=0`` binds an ephemeral port (read ``server.server_address[1]``). Call
+    ``serve_forever()`` to run, or use this in a thread for tests.
+    """
+    httpd = ThreadingHTTPServer((host, port), ReadAPIHandler)
+    httpd.api = ReadAPI(store)
+    return httpd
+
+
+def serve(store, *, host: str = "127.0.0.1", port: int = 8080):  # pragma: no cover
+    """Run the read API until interrupted (blocking)."""
+    httpd = make_server(store, host=host, port=port)
+    addr = httpd.server_address
+    print(f"camber read-api serving on http://{addr[0]}:{addr[1]}  (Ctrl-C to stop)")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        httpd.shutdown()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    import os
+    import sys
+
+    from ..store import ParquetStore
+
+    # argv wins; otherwise env (CAMBER_STORE / _API_HOST / _API_PORT) — the container
+    # sets HOST=0.0.0.0 to be reachable, while a bare `python -m` stays on localhost.
+    root = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("CAMBER_STORE", "tsdb")
+    host = os.environ.get("CAMBER_API_HOST", "127.0.0.1")
+    port = int(sys.argv[2]) if len(sys.argv) > 2 else int(os.environ.get("CAMBER_API_PORT", "8080"))
+    serve(ParquetStore(root), host=host, port=port)

camber/boilercycle.py

@@ -0,0 +1,63 @@
+"""Boiler short-cycling diagnostic: firing starts per day from boiler status.
+
+An oversized boiler (or one with too-tight staging/aquastat hysteresis) fires in
+short bursts: on, satisfy the loop, off, repeat. Each start is purge-cycle losses,
+thermal stress, and lower seasonal efficiency. Counting off->on transitions in the
+boiler-status trend gives a starts-per-day rate that flags the pattern (PNNL Building
+Re-tuning Ch.8; boiler minimum-cycle-time guidance).
+
+This counts cycles across the whole window (a boiler can cycle at any hour, not just
+occupied ones). Trend resolution bounds the count -- sub-interval cycles are invisible
+-- so starts-per-day is a floor, reported as such; the cycling threshold is
+manufacturer-dependent and injected by the rule.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+
+import pandas as pd
+
+
+@dataclass
+class BoilerCyclingResult:
+    """Boiler firing rate over the trend window."""
+
+    equip: str
+    n_days: float                 # observed span in days
+    starts_per_day: float         # off->on transitions per day (a floor; see module doc)
+    runtime_pct: float            # % of intervals the boiler is firing
+    n_starts: int
+    coverage_start: str
+    coverage_end: str
+
+    def as_dict(self):
+        """Return the result as a plain dict."""
+        return asdict(self)
+
+
+def analyze_boiler_cycling(
+    df: pd.DataFrame,
+    equip: str,
+) -> BoilerCyclingResult | None:
+    """Count boiler firing starts per day from the ``BoilerStatus`` (0/1) trend."""
+    if "BoilerStatus" not in df.columns:
+        return None
+    w = df[["BoilerStatus"]].dropna()
+    if len(w) < 10:
+        return None
+    span_days = (w.index.max() - w.index.min()).total_seconds() / 86400.0
+    span_days = max(span_days, 1.0)
+
+    running = w["BoilerStatus"] > 0.5
+    starts = int((running & ~running.shift(1, fill_value=False)).sum())
+
+    return BoilerCyclingResult(
+        equip=equip,
+        n_days=round(span_days, 1),
+        starts_per_day=round(starts / span_days, 2),
+        runtime_pct=round(100.0 * float(running.mean()), 1),
+        n_starts=starts,
+        coverage_start=str(df.index.min()),
+        coverage_end=str(df.index.max()),
+    )

camber/bps.py

@@ -0,0 +1,170 @@
+"""Building Performance Standards (BPS) compliance: limit checks, margin, penalty.
+
+A growing number of jurisdictions impose **building performance standards** -- a
+cap on a building's annual energy-use intensity (EUI) or greenhouse-gas emissions
+intensity, enforced with an over-the-limit penalty. New York City's Local Law 97
+(NYC Administrative Code Title 28, Article 320) is the motivating example: it sets
+emissions-intensity limits per occupancy group and assesses a civil penalty for
+each metric ton of CO2-equivalent over the limit. Other programs (Washington
+State Clean Buildings, Boston BERDO, the federal/voluntary "national definition
+of a zero-emissions building") follow the same shape: a metric, a limit, and a
+cost for exceeding it.
+
+This module is deliberately **jurisdiction-neutral**: it hard-codes no legal
+limit or penalty rate. The caller supplies the limit and an optional generic
+penalty (dollars per unit over) via :class:`BPSStandard`; this module computes the
+compliance margin, percent of limit, over-amount, and resulting penalty. It also
+provides :func:`emissions_intensity`, which converts a per-fuel energy breakdown
+into an annual emissions intensity using caller-supplied emission factors (e.g.
+EPA eGRID for electricity, EPA GHG factors for combustion fuels) so the result
+can be checked against an emissions-type standard.
+
+stdlib only -- no numpy/pandas needed for these scalar computations.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class BPSStandard:
+    """A building performance standard: a metric, its limit, and an over-penalty.
+
+    ``metric`` is ``"eui"`` (energy-use intensity) or ``"emissions"`` (emissions
+    intensity); both are evaluated as "lower is better" against ``limit`` in the
+    given ``unit``. ``penalty_per_unit_over`` is a generic cost (e.g. dollars) per
+    unit by which the value exceeds the limit -- supply the jurisdiction's rate, or
+    leave at 0 to skip penalty pricing.
+    """
+
+    name: str
+    metric: str                          # "eui" | "emissions"
+    limit: float
+    unit: str = ""
+    penalty_per_unit_over: float = 0.0
+
+    def as_dict(self) -> dict:
+        """Return the standard as a plain dict."""
+        return asdict(self)
+
+
+@dataclass
+class BPSResult:
+    """Compliance of a single value against a :class:`BPSStandard`."""
+
+    standard_name: str
+    metric: str
+    value: float
+    limit: float
+    unit: str
+    compliant: bool
+    margin: float            # limit - value (positive = headroom)
+    pct_of_limit: float      # 100 * value / limit
+    over_amount: float       # max(0, value - limit)
+    penalty: float           # over_amount * penalty_per_unit_over
+    verdict: str             # "compliant" | "over"
+
+    def as_dict(self) -> dict:
+        """Return the result as a plain dict."""
+        return asdict(self)
+
+
+def assess_bps(value: float, standard: BPSStandard) -> BPSResult | None:
+    """Assess a measured ``value`` against a BPS ``standard`` (lower is better).
+
+    Returns ``None`` if the inputs are unusable (non-finite value, or a limit that
+    is non-finite or not positive -- a limit must be a positive cap to be
+    meaningful). Otherwise returns a :class:`BPSResult` with the compliance margin
+    (``limit - value``), the value as a percent of the limit, the over-amount, and
+    the resulting penalty.
+    """
+    v = float(value)
+    lim = float(standard.limit)
+    if not math.isfinite(v) or not math.isfinite(lim) or lim <= 0:
+        return None
+    over = max(0.0, v - lim)
+    compliant = v <= lim
+    penalty = over * float(standard.penalty_per_unit_over)
+    return BPSResult(
+        standard_name=standard.name,
+        metric=standard.metric,
+        value=round(v, 4),
+        limit=round(lim, 4),
+        unit=standard.unit,
+        compliant=compliant,
+        margin=round(lim - v, 4),
+        pct_of_limit=round(100.0 * v / lim, 2),
+        over_amount=round(over, 4),
+        penalty=round(penalty, 2),
+        verdict="compliant" if compliant else "over",
+    )
+
+
+# Site-energy conversion to kBtu per the fuel's native unit (delivered/site energy).
+# Caller can override or extend per project. (Source EUI would additionally apply
+# site-to-source multipliers -- out of scope here; this is site EUI.)
+EUI_FACTORS_KBTU: dict = {
+    "electricity": 3.412,    # per kWh
+    "natural_gas": 100.0,    # per therm
+    "propane": 91.6,         # per gallon
+    "fuel_oil": 138.7,       # per gallon (No. 2)
+    "district_chw": 12.0,    # per ton-hour of chilled water
+}
+
+
+def site_eui(energy_by_fuel: dict, area_sqft: float, *, factors: dict | None = None) -> float:
+    """Site energy-use intensity (kBtu / sqft / yr) from a per-fuel annual energy breakdown.
+
+    ``energy_by_fuel`` maps a fuel key (``"electricity"`` in kWh, ``"natural_gas"`` in
+    therms, ...) to that fuel's annual use; values are converted to kBtu via ``factors``
+    (defaults :data:`EUI_FACTORS_KBTU`, merged with any caller overrides) and summed over
+    the gross floor area. Fuels missing from ``factors`` contribute zero. Returns ``nan``
+    if ``area_sqft`` is not positive. This is *site* EUI (delivered energy), the metric
+    most BPS laws and ENERGY STAR site-EUI checks use.
+    """
+    if not math.isfinite(area_sqft) or area_sqft <= 0:
+        return float("nan")
+    fac = {**EUI_FACTORS_KBTU, **(factors or {})}
+    total_kbtu = sum(float(energy) * float(fac.get(fuel, 0.0))
+                     for fuel, energy in energy_by_fuel.items())
+    return total_kbtu / float(area_sqft)
+
+
+def assess_eui(energy_by_fuel: dict, area_sqft: float, eui_limit: float, *,
+               name: str = "BPS EUI limit", penalty_per_unit_over: float = 0.0,
+               factors: dict | None = None) -> BPSResult | None:
+    """End-to-end: compute site EUI from energy + area, then assess it against a limit.
+
+    A convenience over :func:`site_eui` + :func:`assess_bps`; ``eui_limit`` is the
+    standard's cap in kBtu/sqft/yr (an ENERGY STAR property-type target or a local BPS
+    limit), with an optional ``$/(kBtu/sqft)``-over penalty. Returns ``None`` if the EUI
+    can't be computed (non-positive area).
+    """
+    eui = site_eui(energy_by_fuel, area_sqft, factors=factors)
+    if not math.isfinite(eui):
+        return None
+    return assess_bps(eui, BPSStandard(name=name, metric="eui", limit=eui_limit,
+                                       unit="kBtu/ft2/yr",
+                                       penalty_per_unit_over=penalty_per_unit_over))
+
+
+def emissions_intensity(energy_by_fuel: dict, factors: dict,
+                        area_sqft: float) -> float:
+    """Annual emissions intensity (kgCO2e per sqft) from per-fuel energy.
+
+    ``energy_by_fuel`` maps a fuel key (e.g. ``"electricity"``, ``"natural_gas"``)
+    to that fuel's annual energy in the unit the matching emission factor expects.
+    ``factors`` maps the same keys to a caller-supplied emission factor in kgCO2e
+    per energy unit (e.g. EPA eGRID for grid electricity, EPA GHG factors for
+    combustion fuels). Fuels present in ``energy_by_fuel`` but missing from
+    ``factors`` contribute zero. Returns ``nan`` if ``area_sqft`` is not positive.
+    """
+    if not math.isfinite(area_sqft) or area_sqft <= 0:
+        return float("nan")
+    total = 0.0
+    for fuel, energy in energy_by_fuel.items():
+        factor = factors.get(fuel, 0.0)
+        total += float(energy) * float(factor)
+    return total / float(area_sqft)

camber/carbon.py

@@ -0,0 +1,57 @@
+"""Carbon (greenhouse-gas) accounting from building energy consumption.
+
+Converts energy use by fuel to CO2-equivalent emissions using published emission
+factors (EPA eGRID for grid electricity, EIA for fuels). Electricity factors vary
+widely by grid region and over time, so the electricity default here is a neutral
+placeholder -- pass the region's current eGRID factor for a real number. Fuel
+combustion factors are more stable.
+
+Factors are kg CO2e per unit; include CH4/N2O via their global-warming potentials
+in the factor where a full CO2e is wanted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# kg CO2e per unit. Electricity is grid- and year-specific -- override it.
+DEFAULT_FACTORS: dict = {
+    "electricity_kwh": 0.40,     # placeholder; supply your eGRID subregion value (~0.4-0.9)
+    "natural_gas_therm": 5.30,   # EIA combustion factor, kg CO2e/therm
+    "natural_gas_kwh": 0.181,    # if gas is metered in kWh
+    "fuel_oil_gal": 10.21,       # kg CO2e/gal (No. 2)
+    "propane_gal": 5.72,         # kg CO2e/gal
+    "district_steam_kbtu": 0.066,
+}
+
+
+@dataclass(frozen=True)
+class Emissions:
+    """Emissions result: per-fuel and total CO2e."""
+
+    by_fuel: dict           # fuel -> kg CO2e
+    total_kg: float         # total kg CO2e
+    intensity_kg_sf: float  # kg CO2e / ft2 (NaN if area not given)
+
+    @property
+    def total_tonnes(self) -> float:
+        """Total CO2e in metric tonnes."""
+        return round(self.total_kg / 1000.0, 4)
+
+
+def emissions(consumption_by_fuel: dict, *, factors: dict | None = None,
+              gross_sf: float | None = None) -> Emissions:
+    """Compute CO2e from ``{fuel_key: amount}`` using ``factors`` (kg CO2e/unit).
+
+    Fuel keys must match the factor keys (see :data:`DEFAULT_FACTORS`). Unknown
+    keys raise, so a typo can't silently drop a fuel from the footprint.
+    """
+    f = {**DEFAULT_FACTORS, **(factors or {})}
+    by_fuel = {}
+    for fuel, amount in consumption_by_fuel.items():
+        if fuel not in f:
+            raise KeyError(f"no emission factor for '{fuel}'; supply via factors=")
+        by_fuel[fuel] = round(float(amount) * f[fuel], 4)
+    total = round(sum(by_fuel.values()), 4)
+    intensity = round(total / gross_sf, 6) if gross_sf else float("nan")
+    return Emissions(by_fuel=by_fuel, total_kg=total, intensity_kg_sf=intensity)

camber/charts/__init__.py

@@ -0,0 +1,2 @@
+"""Charts: diagnostic visuals — heating-vs-cooling scatter, reheat boxes, timeseries, zones,
+load carpet (hour x date heatmap), CUSUM trajectory, and the energy-signature change-point plot."""

camber/charts/box_reheat.py

@@ -0,0 +1,69 @@
+"""Per-box reheat visualization: reheat valve, space temp vs setpoints, OAT.
+
+Visual proof for the top reheat offenders. One stacked figure per box:
+  (top)    HW reheat valve %  + box airflow vs setpoint
+  (bottom) space temp with heating/cooling setpoint band + OAT on 2nd axis
+Reheat-at-high-OAT events are highlighted.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+
+def box_reheat_figure(df, equip, *, oat=None, valve_thr=5.0,
+                      cooling_cutoff_f=65.0, occupied_only=True):
+    """Build a 2-panel reheat diagnostic figure for one box. Returns the Figure."""
+    import matplotlib.pyplot as plt
+
+    work = df.copy()
+    if occupied_only:
+        hour = work.index.hour + work.index.minute / 60.0
+        occ = (work.index.dayofweek < 5) & (hour >= 7) & (hour < 18)
+        for m in ("WarmUp", "CoolDown"):
+            if m in work.columns:
+                occ = occ & ~(work[m].fillna(0) > 0.5)
+        work = work[occ]
+
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(13, 7), sharex=True)
+
+    # --- panel 1: reheat valve + airflow ---
+    if "HWValve" in work.columns:
+        ax1.plot(work.index, work["HWValve"], color="#cc3333", lw=0.6,
+                 label="HW reheat valve %")
+    ax1.set_ylabel("Reheat valve (%)", color="#cc3333")
+    ax1.set_ylim(0, 100)
+    if "ActFlow" in work.columns:
+        axf = ax1.twinx()
+        axf.plot(work.index, work["ActFlow"], color="#888888", lw=0.5, alpha=0.7,
+                 label="Airflow")
+        if "ActFlowSP" in work.columns:
+            axf.plot(work.index, work["ActFlowSP"], color="#888888", lw=0.5,
+                     ls="--", alpha=0.7, label="Airflow SP")
+        axf.set_ylabel("Airflow (cfm)", color="#888888")
+    ax1.set_title(f"{equip} — reheat diagnostic (occupied hours)")
+    ax1.legend(loc="upper left", fontsize=8)
+
+    # --- panel 2: space temp + setpoint band + OAT ---
+    if "SpaceTemp" in work.columns:
+        ax2.plot(work.index, work["SpaceTemp"], color="#2a7", lw=0.7,
+                 label="Space temp")
+    if "ActHeatSP" in work.columns and "ActCoolSP" in work.columns:
+        ax2.fill_between(work.index, work["ActHeatSP"], work["ActCoolSP"],
+                         color="#cccc44", alpha=0.15, label="Setpoint band")
+    ax2.set_ylabel("Temp (°F)")
+    if oat is not None:
+        oat_a = oat.reindex(work.index).ffill(limit=4)
+        ax2b = ax2.twinx()
+        ax2b.plot(work.index, oat_a, color="#999", lw=0.5, label="OAT")
+        ax2b.set_ylabel("OAT (°F)", color="#999")
+        # highlight reheat-at-high-OAT
+        if "HWValve" in work.columns:
+            hot = (work["HWValve"] > valve_thr) & (oat_a > cooling_cutoff_f)
+            ax2.scatter(work.index[hot], work["SpaceTemp"][hot] if "SpaceTemp" in work
+                        else [cooling_cutoff_f] * int(hot.sum()),
+                        color="red", s=4, zorder=5, label="reheat @ OAT>65°F")
+    ax2.legend(loc="upper left", fontsize=8)
+    ax2.set_xlabel("Time")
+    fig.tight_layout()
+    return fig