pymbs.config 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

class pymbs.config.Config[source]

Bases: object

The Config object holds all configuration values for PyMBS, except for those related to Logging, which are stored in the pymbs.log module. See the documentation for that module in regards to the Logging settings.

The user is able to customize settings via the config.yaml file, which is located in a subdirectory of the user’s HOME directory, and is described further in the Set up your Modeling Environment section of this documentation.

Many of the settings in the config object may be specifed in environment variables. If a value for a setting is specified simultaneously in the config.yaml file and as an environment variable, the value from the environment variable will be used.

As noted below, some of the properties set in the config object are actually attributes of the Context object in Python’s Decimal module.

For more information on the Decimal Context object, see:

https://docs.python.org/3/library/decimal.html#decimal.Context

Some of the properties set in the config object are actually options in the Pandas library.

For more information, see:

https://pandas.pydata.org/pandas-docs/stable/user_guide/options.html#available-options

property cache

The cache value should never be set directly. This Python dictionary is referenced and modified by private functions throughout the PyMBS code.

The values in this dictionary change quicky when running the model, so viewing it by referencing the config.cache property may not make sense, except in a debugging context.

property emax

Emax is an attribute of the Context object in Python’s Decimal module. The Emax field is an integer specifying the outer limit allowable for the max exponent.

Emax must be in the range [0, MAX_EMAX].

This may set in the config.yaml file, or via the PYMBS_EMAX environment variable.

property emin

Emin is an attribute of the Context object in Python’s Decimal module. The Emin field is an integer specifying the outer limit allowable for the min exponent.

Emin must be in the range [MIN_EMIN, 0].

This may set in the config.yaml file, or via the PYMBS_EMIN environment variable.

property max_rows

This sets the maximum number of rows Pandas should output when printing out various output. For example, this value determines whether the repr() for a dataframe prints out fully or just a truncated or summary repr. ‘None’ value means unlimited.

The Pandas default is 60.

The PyMBS default for this value is 400, which was determined by rounding up from 360, which is the number of monthly periods in a 30-year cash flow.

This may set in the config.yaml file, or via the PYMBS_MAX_ROWS environment variable.

property model

The model value should never be set directly. This value is set by calling the api.load_model(model_json) function, passing the name of the JSON file that holds the model for the deal.

The load_model function deserializes the JSON data into Python data types, for use in all subsequent function calls to compute the outputs of the model.

The model structure may be viewed as a Python dictionary by referencing the config.model property.

property precision

prec[ision] is an attribute of the Context object in Python’s Decimal module.

The precision is an integer in the range [1, MAX_PREC] that sets the precision for arithmetic operations in the context.

This may set in the config.yaml file, or via the PYMBS_PRECISION environment variable.

property project_dir

The project_dir must be set, as it can not be known or discovered in advance.

The project directory is a dicrecotry in the file system that contains one subdirectory for each deal modeled with PyMBS. By convention, each subdirectory is named using the name of the deal being modeled. For more information about the directory structure, see the Set up your environment section of this documentation.

This may set in the config.yaml file, or via the PYMBS_PROJECT_DIR environment variable.

property round_precision

round_precision is the number of decimals to round to, when rounding a decimal value. It is not part of the specification described in the Python Decimal Module, but is a custom value created and used by PyMBS.

This value is used in the custom _round_dec() function, located in the pymbs.utils module.

This may set in the config.yaml file, or via the PYMBS_ROUND_PRECISION environment variable.

property terms_sheet

The terms_sheet value should never be set directly. This value is set by calling the api.load_deal(series_name) function, passing the name of the directory that holds the files for the deal.

The load_deal function deserializes the series_ts.json file and converts all Float values into Decimal values, using Python’s Decimal module.

The Terms Sheet structure may be viewed as a Python dictionary by referencing the config.terms_sheet property.