Edit a record¶
This guide shows how to stage edits on a WorkingRecord, check them, and commit them as a child revision. The examples use record, rev, store and ws from Your first record.
You make a WorkingRecord over a committed Record, and a read of it returns that record with the edits applied. Each edit runs in its own transaction, so a refused edit stages nothing.
Set attribute values¶
Name the attribute, then the value, then a keyword per coordinate. Pass a scalar for one value at each label named, a list for one value per label in order, or a mapping keyed by label:
import pandas as pd
from datarecord import WorkingRecord
w = WorkingRecord(record)
w.set("p_nom", 120.0, entity=["wind1", "gas1"])
w.set("p_nom", [120.0, 60.0], entity=["wind1", "gas1"])
w.set("p_nom", {"wind1": 120.0, "gas1": 60.0})
print(w.attributes["p_nom"].df())
Each set replaces the rows it names, so the last one stands. Pass a series to set values along the coordinate its index is named after. Pass a property as a keyword to set values at the labels that match it when you call set:
series = pd.Series([0.2, 0.6, 0.4], index=pd.Index([0, 1, 2], name="snapshot"))
w.set("p_max_pu", series, entity="wind1")
w.set("p_max_pu", 0.95, ctype="Generator", carrier="gas")
print(w.attributes["p_max_pu"].df())
entity snapshot attribute breakpoint value
0 wind1 2 p_max_pu NaN 0.40
1 gas1 <NA> p_max_pu NaN 0.95
2 wind1 1 p_max_pu NaN 0.60
3 wind1 0 p_max_pu NaN 0.20
wind1 has its series, and gas1, the one gas generator, has one row with snapshot NULL. A coordinate you pass no keyword for is NULL, which means every label, those added later included. To set only the labels there are now, name them or their category. set also takes a long frame from pandas, polars, Arrow or DuckDB with a column per coordinate and a value column.
Set a property¶
Name a property by its subject, subject.name:
wind1 now has the carrier gas. A plain name is an attribute, so w.set("carrier", ...) raises a KeyError that suggests entity.carrier.
Roll back the staged edits¶
rollback discards every staged edit:
The properties are as committed again.
Add and remove labels¶
add takes a dim, its labels, and a keyword per property. A multi-dim takes tuples as mappings from coordinate to label. Add a label before you set a value at it or use it in a property or a tuple:
w.add("carrier", ["solar"])
w.add("entity", ["pv1"], ctype="Generator", carrier="solar")
w.add("connection", [{"entity": "pv1", "bus": "south"}])
w.set("p_nom", 40.0, entity="pv1")
w.remove("bus", ["north"])
print(w.dims["connection"].df())
remove takes out every tuple with north in its bus field, with its values. It refuses a label that is still a property's value:
ValueError: `remove('carrier', ...)` is refused: `entity.carrier` names them at [('gas1', 'gas')]; `set` those to another label or None first
The message lists where entity.carrier still has the value gas. Layers describes what else a removal removes.
Check the staged edits¶
A read of the WorkingRecord returns its edits applied, and edits contains only what you staged:
['bus', 'carrier', 'connection', 'entity'] ['p_nom']
entity attribute breakpoint value
0 pv1 p_nom NaN 40.0
edits has the four axes you changed, each restated whole, and the one p_nom row of pv1. A relation you took before an edit returns the edit too:
rel = w.attributes["p_nom"]
w.set("p_nom", 45.0, entity="pv1")
print(rel.filter("entity = 'pv1'").df())
rel returns the 45.0 that you staged after taking it.
Commit the edits¶
store.commit(w) writes the edits as a child of the revision w was made over. Close the WorkingRecord once you no longer read it:
child = store.commit(w)
w.close()
print(child.parent == rev.id)
print(child.record.dims["bus"].df())
The child's bus axis has south alone.
To write a WorkingRecord whole, as a standalone directory with no parent, pass it to ws.write. A with block closes it on exit:
import os
with WorkingRecord(child.record) as w:
w.set("p_nom", 30.0, entity="pv1")
flat = ws.write(w, os.path.join(tempfile.mkdtemp(), "flat"))
print(flat.attributes["p_nom"].df())
entity attribute breakpoint value
0 wind1 p_nom NaN 100.0
1 gas1 p_nom NaN 50.0
2 pv1 p_nom NaN 30.0
The directory contains the values of every layer, with the edit applied.