pymbs.api module¶
PyMBS is a Python library for use in modeling Mortgage-Backed Securities.
Copyright (C) 2019 Brian Farrell
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
Contact: brian.farrell@me.com
- pymbs.api.disperse_cf(model: dict, group_id: Optional[Union[int, str]] = 'ALL_GROUPS') NoReturn [source]¶
Make all payments of Interest and Principal, based on the rules enumerated in the model.
- Args:
- model: The structured cash flow model containing the payment rules
waterfall for the group(s)
- group_id: The number of the Group for which to load the tranches.
By default, this value is set to ‘ALL_GROUPS’, which will load the tranches for all of the groups in the deal. As per convention, the Residual tranches will appear in Group ‘0’.
- pymbs.api.load_assumed_collat(group_id: Optional[Union[int, str]] = 'ALL_GROUPS') DataFrame [source]¶
Load the Assumed Collateral replines from the Terms Sheet.
This assumes that the Terms Sheet has already been loaded, using the
load_deal()
function.This will only load Assumed Collateral. PyMBS does not yet have the ability to handle Known Collateral or Securitzed Collateral. It can however handle multiple Assumed replines per group.
- pymbs.api.load_deal(series_id: str) dict [source]¶
Load the Terms Sheet for the REMIC Series name provided.
The Terms Sheet is essential for modeling the deal. If this function is not called at the start, most of the other functions will fail.
Within the project_dir, specified in the user’s configuration file, it is expected that there will be one subdirectory for each REMIC Series name. Inside the Series directory, it is expected that the Terms Sheet will be a file named
series_ts.json
, where ‘series’ refers to the actual Series name.- Args:
series_id: The REMIC Series id. Note that this value is passed as a string, so it need not be strictly an integer value, i.e. ‘T-074’. The value must be the same as the name of the deal directory, which is a subdirectory of the project_directory.
- Returns:
A dictionary object, representing the Terms Sheet. All numerical values related to the model and represented as Strings in the Terms Sheet will be converted to a Python Decimal type in the dictionary that is returned.
If the Terms Sheet file is not located, returns Exit Code 66.
- Example:
Given: REMIC Series Name is
'2618'
Path:
/project_dir/2618/2618_ts.json
- pymbs.api.load_model() dict [source]¶
Load the structured cash flow model from the Terms Sheet, supplemented by the model file.
The Terms sheet does NOT include the pay rule waterfall or specific benchmark interest rate information used by the model. These are provided in a separate JSON file.
Within the project_dir, specified in the user’s configuration file, it is expected that there will be one subdirectory for each REMIC Series name. Inside the Series directory, it is expected that the Model File named as provided as argument to this function will exist.
- Args:
model_json: The name of the model file inside the Series directory.
- Returns:
A dictionary object, representing the structured cash flow model.
If the Model file is not located, returns Exit Code 66.
- Example:
Given:
model_json = 2618_model.json
Path:
/project_dir/2618/2618_model.json
- pymbs.api.load_tranches(group_id: Optional[Union[int, str]] = 'ALL_GROUPS') DataFrame [source]¶
Load the tranches for the deal, or for the group specified, into a Pandas Dataframe for easy display in the Jupyter Notebook.
- Args:
- group_id: The number of the Group for which to load the tranches.
By default, this value is set to ‘ALL_GROUPS’, which will load the tranches for all of the groups in the deal. As per convention, the Residual tranches will appear in Group ‘0’.
- Returns:
A Pandas Dataframe showing Tranche details for each tranche queried.
- pymbs.api.run_collat_cf(group_id: Optional[Union[int, str]] = 'ALL_GROUPS', repline_num: Optional[int] = - 1) dict [source]¶
Run cash flows from Assumed Collateral replines specified in the Terms Sheet. A Pandas DataFrame is created for each cash flow prepayment scenario, as specified in the Prepayment Scenarios JSON file.
The Terms sheet does NOT include the pay rule waterfall or specific benchmark interest rate information used by the model. These are provided in a separate JSON file.
Within the project_dir, specified in the user’s configuration file, it is expected that there will be one subdirectory for each REMIC Series name. Inside the Series directory, it is expected that the Model File named as provided as argument to this function will exist.
- Args:
- group_id: The number of the Group for which to run the cash flows.
By default, this value is set to ‘ALL_GROUPS’, which will run cash flows for all of the groups in the deal at the Prepayment Scenarios specified for each group.
- repline_num: Optionally, the user may specify running the cash flows
for a specific repline in a specific group, if the group has more than one assumed repline. As with
group_id
, therepline_num
is set to -1 by default, which will run cash flows for ALL replines associated with a group. When run together, the cash flows for each repline will be aggregated into one final cash flow which is the one that is returned for the group.
- Returns:
A dictionary object, containing a Pandas Dataframe for the cash flow calculated at each Prepayment Scenario.
- Example:
Path:
/project_dir/2618/2618_pps.json
TODO: Run collateral cash flows for known collateral.
TODO: Run collateral cash flows for securitzed collateral.