Serialization#
Rateslib is an object oriented library requiring dynamic associations to create pricing and risk functionality. The objective of serialization and deserialization is to convert rateslib’s objects into a form that can be persisted or transported, with a view towards being able to recapture those dynamic associations.
Ultimately this means that data could be stored in a database and retrieved, or it could be transmitted over the web from a server to a client based browser and reconstructed.
Warning
This feature is currently experimental, and in development.
JSON#
Serialization is a general term. The specific form of serialization that rateslib aims to create is JSON serialization, meaning an object can be deconstructed into a JSON string and reconstructed from the same string. JSON has pros and cons associated with its choice. A con being that it is not necessarily the most efficient form of transfer or storage, but pros being that is is human-readable, transparent and provides a defined data structure.
The key method used for this purpose is:
|
Create an object from JSON string. |
Objects in Scope#
Dual#
The automatic differentiation (AD) data types (Dual and Dual2)
are fundamental data types. These must be serializable to propagate the attribute of serialization to other
objects.
In [1]: dual = Dual(3.141, ["x", "y"], [1.0, 0.0])
In [2]: dual.to_json()
Out[2]: '{"Dual":{"real":3.141,"vars":["x","y"],"dual":{"v":1,"dim":[2],"data":[1.0,0.0]}}}'
In [3]: from_json(dual.to_json())
Out[3]: <Dual: 3.141000, (x, y), [1.0, 0.0]>
In [4]: dual2 = Dual2(3.141, ["x", "y"], [1.0, 0.0], [])
In [5]: dual2.to_json()
Out[5]: '{"Dual2":{"real":3.141,"vars":["x","y"],"dual":{"v":1,"dim":[2],"data":[1.0,0.0]},"dual2":{"v":1,"dim":[2,2],"data":[0.0,0.0,0.0,0.0]}}}'
In [6]: from_json(dual2.to_json())
Out[6]: <Dual2: 3.141000, (x, y), [1.0, 0.0], [[...]]>
Calendars#
Calendar serialization is useful for saving and loading custom calendar objects.
# create a `Cal` with two holidays and general weekends
In [7]: cal = Cal([dt(2023, 1, 2), dt(2023, 1, 3)], [5,6])
In [8]: cal.to_json()
Out[8]: '{"Cal":{"holidays":["2023-01-02T00:00:00","2023-01-03T00:00:00"],"week_mask":["Sun","Sat"]}}'
# create an identical calendar to `cal` (in business day terms), by unionising calendars
In [9]: union_cal = UnionCal([Cal([dt(2023, 1, 2)], [5,6]), Cal([dt(2023, 1, 3)], [])])
In [10]: union_cal.to_json()
Out[10]: '{"UnionCal":{"calendars":[{"holidays":["2023-01-02T00:00:00"],"week_mask":["Sun","Sat"]},{"holidays":["2023-01-03T00:00:00"],"week_mask":[]}],"settlement_calendars":null}}'
# these two objects have the same business and settlement days..
In [11]: from_json(cal.to_json()) == from_json(union_cal.to_json())
Out[11]: True
# serializing NamedCal remains consistent to the pre-compiled calendars for the version of rateslib
In [12]: named_cal = NamedCal("tgt")
In [13]: named_cal.to_json()
Out[13]: '{"NamedCal":{"name":"tgt"}}'
PPSplines#
PPSpline serialization is added as a pre-requisite to add Curve serialization.
In [14]: pps = PPSplineF64(k=4, t=[0,0,0,0,4,4,4,4], c=None)
In [15]: pps.csolve(np.array([0, 1, 3, 4]), np.array([0, 0, 2, 2]), 0, 0, False)
In [16]: pps.to_json()
Out[16]: '{"PPSplineF64":{"inner":{"k":4,"t":[0.0,0.0,0.0,0.0,4.0,4.0,4.0,4.0],"c":{"v":1,"dim":[4],"data":[0.0,-1.111111111111111,3.1111111111111107,2.0]},"n":4}}}'
In [17]: from_json(pps.to_json())
Out[17]: <rateslib.rs.PPSplineF64 at 0x11b680500>
FXRates#
In [18]: fxr = FXRates({"gbpusd": 1.2959, "eurusd": 1.0894}, settlement=dt(2024, 7, 16))
In [19]: fxr.to_json()
Out[19]: '{"Py":{"FXRates":{"fx_rates":[{"pair":[{"name":"gbp"},{"name":"usd"}],"rate":{"F64":1.2959},"settlement":"2024-07-16T00:00:00"},{"pair":[{"name":"eur"},{"name":"usd"}],"rate":{"F64":1.0894},"settlement":"2024-07-16T00:00:00"}],"currencies":[{"name":"gbp"},{"name":"usd"},{"name":"eur"}]}}}'
In [20]: fxr.rate("gbpeur")
Out[20]: <Dual: 1.189554, (fx_gbpusd, fx_eurusd), [0.9, -1.1]>
In [21]: from_json(fxr.to_json()).rate("gbpeur")
Out[21]: <Dual: 1.189554, (fx_gbpusd, fx_eurusd), [0.9, -1.1]>