AD&Co OAS system version 8 is a powerful tool that enables both traditional and novel valuation methods for MBS and ABS. Integrated with client’s internal databases and applications, it allows for massive portfolio processing accurately, often at a fraction of usual time. The system can be instantly calibrated to swap rates and ATM swaption volatilities, and allows for controlling volatility skew by the term structure model selection (4 models). It can also capture the difference between pricing results obtained under single-factor and two-factor term structure modeling approaches.
The model can employ backward induction (for fixed-rate pass-throughs working with 5.1 or later prepay model and valued under any of single-factor models), which leads to a super-quick option-adjusted valuation on an interest rate grid. More traditional Monte-Carlo or quasi Monte-Carlo methods are available as well and necessary for running CMOs. The OAS library is laboriously integrated with Intex and Chasen systems generating cashflows for complex structured securities. Instruments with user-provided cashflows can be defined as well using function pointers. In general, AD&Co OAS model covers most of MBS and ABS types.
Starting from version 8, user can employ the Credit OAS valuation method that is integrated with AD&Co’s LoanDynamicsTM Model (LDM) and allows for valuing MBS and ABS with losses. Credit OAS simulates random interest rates and home prices, and for every market scenario, lets LDM forecast prepayment, default, delinquency and loss severity rates, and alter cashflow vectors accordingly. Hereinafter, we often refer to LDM as a prepayment model although its output is much richer.
Switching between AD&Co’s LDM, 5.2, 5.1 and 4.3 prepay models is seamless and convenient when valuation results need comparison. In either case, enhanced pool data (loan size, LTV, FICO, geography, etc) can improve accuracy of prepayment forecasts. The flow of this improvement is controlled by user and done exogenously. A caller can pass information on collateral details, obtain calculated corrective scales for refinancing and turnover processes (“speed multiples”) and tune the model accordingly, for each MBS. For the use of LDM, a similar set of data may be required; we will refer to it as “credit data”. In addition to the data fields used for the enhanced prepay modeling credit dataset includes loan statuses (current-delinquent-severely delinquent), documentation, lien position, mortgage insurance.
A comprehensive set of valuation measures is produced including numerous Greeks and sensitivity measures, TRR, user-supplied scenario analysis or automated rate shocks. The settlement date can be up to 12 month forward, and the difference between delivery of a TBA and a specified MBS is fully captured in valuation.
One of most unique features of AD&Co valuation concept is ability to run the same pricing engine using either “physical” prepayment model (traditional OAS method) or risk-neutral prepayment model (prepay risk-adjusted prOAS method). A licensee of the system can obtain risk-neutral calibrator, a complimentary tool that allows for calibrating prepay model to the desired prOAS levels or Duration targets.
Although the OAS system is written on C++, the library is not difficult in integration as it only includes a set of simple calls to C functions; only basic data types are passed. The sequence of programming steps flows in a logical order. Internal C++ objects allocate and free needed memory automatically.
Version 6 is connected to any of prepay models, version 4.3 to 5.1.
Version 7 is connected to any of prepay models, from 4.3 to 5.2. This version integrates prepay model 5.2 family containing new ARM models built for agencies, prime jumbos, and sub-prime ARMs. All these models follow a universal design pattern first developed and tested in version 5.1 for fixed-rate MBS.
Version 8 is connected to any of prepay models, from 4.3 to LDM. This version includes functionality of all previous versions.
1. Get an OASHandle – returns a pointer required for all other functions
2. Describe Market Environment
a. Set Trade Date and Settlement date
b. Tell model where AD&Co monthly data files and license key are located (default c:\adco\ppmodel)
c. Select Yield Curve to be used for OAS (LIBOR or TSY)
d. Select short-rate volatility and mean reversion or supply an ATM swaption volatility matrix for automatic calibration
e. Select interest rate model (Hull-White, Squared Gaussian, Black-Karasinski, 2-factor Gaussian)
f. Select the sampling method and the number of paths (for Monte-Carlo)
g. Provide Treasury and LIBOR Yield Curves (Zero or Par)
h. Set other market indices such as various secondary market’s MBS rates or COFI
i. Describe any shifts that you wish to project
j. Set Home Price Appreciation (HPA) assumptions (for LDM)
3. Set Security Parameters – Describe specific security to analyze, different functions for ARMs, MBS, Intex securities
4. Do you wish to compute refinancing and turnover prepay multiples using available enhanced pool data
5. Set Pricing - Are you quoting OAS, Price, BEEM or Yield
6. Set Prepayment Model
a. Which prepay model are you using (ADCO_LDM, ADCO_52, ADCO, constant CPR, PSA, etc.)
b. Do you wish to “tune” prepayment models or LDM
7. Select which calculations should be run, which valuation method to use
a. Static, Forward, OAS analyses
b. Monte-Carlo or backward induction (when possible)
c. Effective Duration/Convexity, shocked prices
d. Key Rate Durations
e. Spread Duration, Index Duration
f. Vega
g. HPA Duration (short-term, long-term)
h. Prepay model tuning sensitivities
i. User-defined scenario analysis, TRR analyses
8. Run analysis
9. Get Results
10. Free Handle
Exhibits:
1) Sample programs for MBS portfolio, ARMs, iCMOs and cCMOs
2) Sample callback function to view cash flows
3) Sample input dump file created by program
Header files required:
ADIRdefs.h (must be #included before adco_xc_oas.h #included)
adpdefs.h
adco_xc_oas.h (which in turn includes the following five headers)
adco_oas_api_public.h (defines all enumerated types included in the function calls described below)
*icmo.h (for Intex)
*ccmo.h (for Chasen)
*ADCO.h (for Chasen)
*IndexTypes.h (for Chasen)
Calc_RM.h (for exogenous calculations of corrective prepay multipliers using enhanced collateral information)
* Vendor files
Libraries required
Win32-> ad_oas60.dll or ad_oas7.dll or ad_oas8.dll (main oas library) + LIB
adco_IR.dll (interest rate process libraries)
adppsub.dll (mbs/arm prepay library)
adppmdl.dll (5.1, 5.2 or LDM-specific prepay library)
ad_cwrap50.dll (for Intex’s link to 5.0 prepay library)
An OASHandle is a pointer to a C++ object that is allocated for the security you wish to analyze. You can’t access members and methods of the class directly; you will simply need to provide this pointer to most C functions in the library. OASHandle is defined as a void* in adco_xc_oas.h.
Get an ARM or MBS handle to deal with ARM or Fixed Rate MBS for which you have the basic parameters (WAC, WAM, etc.) and want to use the ADCO cashflow engine. Active-passive decomposed (APD) MBS and HEL pass-throughs have specific handles. Active-Passive decomposed ARMs are available in prepay family 5.2 and have “unified” ARM handle.
Get an iCMO handle to deal with securities in your Intex database that will be handled by the Intex cashflow engine.
Get a cCMO handle to deal with securities in your Chasen database that will be handled by the Chasen cashflow engine.
Securities working with LDM have separate handles.
Get a secXCF handle to deal with securities whose cashflows you want to calculate yourself. You supply a callback function that returns the cashflows.
Most of the functions that take a handle as an argument also require an argument describing the type of handle. adco_oas_api_public.h defines the following enumeration:
enum sectype {
secARM=0, /*an ARM for which you will be supplying indicatives; driven by 4.3 ARM prepay model */
secMBS, /*an MBS for which you will be supplying indicatives; driven by 4.3 MBS prepay model */
secItxCMO, /*an Intex security for which you will supply Cusip or Intex Deal/Tranche name */
secXCF, /*a security for which you supply a callback function that will generate cashflows */
secChasenCMO, /*a Chasen security for which you will supply Cusip or DealID, BondID */
secMBSAPD, /*an MBS for which you will be supplying indicatives; driven by 5.1 MBS prepay model or later */
secHELAPD, /*an MBS for which you will be supplying indicatives; driven by 5.1 HEL prepay model or later */
unused1,
secARM_50, /*same as secARM, but links to 5.0 library */
unused2,
secArm_Unified, /*same as secARM, but links to 5.2 Unified model */
secMBSLDM, /*an MBS that uses LDM */
secARMLDM, /*an ARM that uses LDM */
secItxCMOLDM /*an iCMO that uses LDM with Intex */
};
Typical function fn(sectype,oashandle, args…)
For running Adjustable Rate Mortgages using ADCO cashflow engine
OASHandle adco_getARMHandle(void); - for ARM prepay model 4.3
OASHandle adco_getARM_50Handle (void); - for ARM prepay model 5.0 or 5.1 (should produce same results as 4.3)
OASHandle adco_getARM_UnifiedHandle (void); - for ARM prepay model 5.2
OASHandle adco_getARMLDMHandle(void); - from ARMs with LDM model
For running Fixed Rate Mortgages using ADCO cashflow engine
OASHandle adco_getMBSHandle(void); - for MBS prepay model 4.3
OASHandle adco_getMBSAPDHandle(void); - for MBS prepay model 5.1
OASHandle adco_getHELAPDHandle(void); - for HEL prepay model 5.1
OASHandle adco_getMBSLDMHandle(void); - for MBS with LDM model
For running Intex securities
OASHandle adco_getiCMOHandle(void); - for iCMOs with “regular” prepay models
OASHandle adco_getiCMOLDMHandle(void); - for iCMOs with LDM
These functions describe the market environment - some of them have default parameters. All of these functions if called for a given handle do not need to be called again unless you want to provide different parameters. What this means, is you can reuse the same handle for a different security without having to recall these functions. For example, one can avoid recalibrating lattice (when allowed) while moving from one portfolio’s position to another.
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until you run adco_analyze again.
============================================================================================
Set the AD&Co datafile directory. Since the license key is also located in this location, it’s best to call this function immediately after getting the OASHandle so that functions that check for valid license keys don’t fail.
Optional – Default is “c:\adco\ppmodel”.
int adco_set_DavidsonDataLocation(enum sectype sec, OASHandle cp, char * ddl);
============================================================================================
Set the settlement date. Required
int adco_set_settleDT(enum sectype sec, OASHandle cp, int month, int day, int year);
Example:
rv = adco_set_settleDT(secMBS, oh, 12, 15, 2001);
============================================================================================
Set the trade date. Required
int adco_set_tradeDT(enum sectype sec, OASHandle cp, int month, int day, int year);
============================================================================================
Set up the parameters to the interest rate process. Required.
irp: which rate model do you want to use (0 for Black-Karasinski, 1 for Squared Gaussian, 2 for Hull-White, 3 for Two-Factor Gaussian)
howmanypaths: how many paths do you want to use with Monte-Carlo
shortvolatility: volatility of the short rate (will be overridden if adco_set_FitMarketVol is set to true. See below.)
meanreversion: mean reversion (will be overridden if adco_set_FitMarketmrevl is set to true. See below.)
int adco_set_PathInfo(enum sectype sec, OASHandle cp, enum irprocess irp, int howmanypaths, double shortvolatility, double meanreversion);
============================================================================================ Set 14 maturity points (used or skipped) – 1-mo, 3-mo, 6-mo, 12-mo, 2-yr, 3-yr, 4-yr, 5-yr, 7-yr, 10-yr, 15-yr, 20-yr, 25-yr, and 30-yr. Enter the maximum number of readily available, reliable points. Missing points should not be passed as 0. Use the defined constant MISSING (defined as negative 98.0 in adirdefs.h)
Required
All rates are in percent. For 5.46% enter 5.46.
int adco_set_tdTreasuryCurve(enum sectype sec, void *cp, enum enumYC pz, double yc1m, double yc3m, double yc6m, double yc1y, double yc2y, double yc3y, double yc4y, double yc5y, double yc7y, double yc10y, double yc15y, double yc20y, double yc25y, double yc30y) ;
Argument pz means par curve (couponYC) or zero curve (zeroYC).
============================================================================================
Which curve to use for OAS analysis? Optional – Default is Treasury.
int adco_set_CurveForOAS(enum sectype sec,void *cp, enum Market TorL);
============================================================================================
Do you want to use constant (flagVTS=0) or time-dependent (flagVTS = 1) volatility? Optional – Default is 0.
int adco_set_flagVTS(enum sectype sec, void *cp, int flagVTS);
============================================================================================
Do you want to use the short volatility that you set in adco_set_PathInfo (fitMarketVol = 0), or calibrate to the swaption volatilities set in adco_set_SwapVol (fitMarketVol = 1). Optional – Default is 0.
int adco_set_FitMarketVol(enum sectype sec, void *cp, int fitMarketVol);
============================================================================================
Do you want to use the mean reversion that you set in adco_set_PathInfo (fitMarketmrev= 0), or calibrate to the swaption volatilities set in adco_set_SwapVol (fitMarketmrev = 1). Optional – Default is 0.
int adco_set_fitMarketmrev(enum sectype sec, void *cp, int fitMarketmrev);
============================================================================================
Set the swaption vols that the IR process will calibrate to. OptionTerm is 0-13, reflecting the 14 points of the yield curve documented above. Required if FitMarketVol is true.
int adco_set_SwapVol(enum sectype sec, void *cp, int OptionTerm, double VolMat1Y, double VolMat2Y, double VolMat10Y);
============================================================================================
Define 2 (out of possible 3) correlations to the short-rate process to be used by the two-factor Gaussian term structure model. Required if the
two-factor Gaussian term structure model was selected (irp was set to 2 in adco_set_PathInfo call); will not be used by any other model.
One out of 3 arguments should be MISSING. If none of correlations are set to MISSING, then the first two, CorrMat1Y and CorrMat2Y, will be used. Input in decimal. Example: Correlation of 23% would be entered as 0.23.
int adco_set_SwapCorr(enum sectype sec, OASHandle cp, double CorrMat1Y, double CorrMat2Y, double CorrMat10Y);
============================================================================================
How many nodes on the lattice over which to use quasi-random sampling. Optional - Default is to use quasi-random sampling over the entire lattice.
int adco_set_quasiRandomNodes(enum sectype sec, void *cp, int quasiRandomNodes);
============================================================================================
Do you what to employ short-rate fudging, i.e. additional adjustment of sampled paths to eliminate any error in static valuation? Optional – Default is 0 (NO).
int adco_set_fudgePaths(enum sectype sec, OASHandle cp, int fudgePaths);
============================================================================================
Do you what to employ antithetic reflection of Monte-Carlo paths? Optional – Default is 0 (NO).
int adco_set_ANTITHETIC(enum sectype sec, OASHandle cp, int antithetic);
============================================================================================
Define the number of shifts (up to ten) to apply to the base yield curve for scenario analysis. Optional – Default is 0.
int adco_set_shiftcnt(enum sectype sec, OASHandle cp, int sc);
============================================================================================
Set the shifts to different points of the yield curve. This function should be called repeatedly – once for each shift you defined in adco_set_shiftcnt.
int adco_set_shift (enum sectype sec, OASHandle cp, int shiftnumber, int shiftmonths, double bps1m, double bps3m, double bps6m, double bps1y, double bps2y, double bps3y, double bps4y, double bps5y, double bps7y, double bps10y, double bps15y, double bps20y, double bps25y, double bps30y);
============================================================================================ Set the value of an index as of the trade date. Indexes are defined in adco_oas_api_public.h. Since all Treasury and Libor/Swap rates are entered through the yield-curve definition functions, this function is used to set Prime and Cofi rates. The integer values of these rates are defined in adco_oas_api_public.h:
int adco_set_tdIndex(enum sectype sec, OASHandle cp, int IDXname, double idxvalue);
============================================================================================
Set the value of a mortgage current coupon as of the trade date. Optional – default is all 0’s.
Mbstype is from enumerator ad_rateindex_type at the bottom of adpdefs.h
int adco_set_tdMBSCC(enum sectype sec, OASHandle cp, int mbstype, double mbsccvalue);
============================================================================================
Step 2a – Additional settings for Credit OAS
Do you want to run random HPA for Monte-Carlo with LDM? Optional – default is 0 (No).
int adco_set_ldm_randomHPI( OASHandle cp, int randomHPI)
randomHPI is flag (0 or -1).
This set-up effects LDM only. If randomHPI is set to -1, the Monte-Carlo analysis will be done under HPA rates randomized above or below the level determined by interest rates. If randomHPI is set to -1, HPA scenarios will be generated based solely on interest rates. Static and forward runs always use non-random HPAs.
Call the appropriate function for the handle you have. Calling any of these functions after adco_analyze marks results as dirty, i.e. you won't be able to get results until adco_analyze is run again.
int adco_set_cf_type(enum sectype sec, OASHandle cp, enum cftype cft);
This call can modify the default cashflow for both ADCO’s cashflow engine and Intex’s securities – allows you to choose to look at PrinOnly, NetIntOnly, PandNetI, servicing IO, full MSR, Loss, or IOMultiple:
enum cftype {
PandNetI=0,
PrinOnly,
NetIntOnly,
ServicingIO,
FullMSR,
Loss,
IOMultiple
};
PayCap - maximum percentage change at each payment reset. For 25% enter 25.
NegAmLimit - negative amortization limit as max percentage of starting balance. 112% enter 112.
Next_index – index used for next reset, if known, in %. -1 if not known.
Required
int adco_set_arm_type( OASHandle cp, int arm_type, int arm_subtype, int payfreq, int nextpay, int arm_index, int FirstIA, int IAFreq, int NextIA, int PAFreq, int NextPA, int wam, int origioper, int origterm, int origballoon, int gross_delay, int lookback, int flagTBA);
flagTBA - denotes TBA (0 - not TBA, 1 - TBA)
payfreq, IAfreq, PAfreq – frequencies of payments, interest adjustments, and pay adjustments; 1 for monthly payments, 3 for quarterly, 12 for annual…
FirstIA – months to 1st interest reset (from origination)
nextpay, NextIA, NextPA – months to next (upcoming) payment, interest reset, and payment reset, respectively.
arm_index – use the #defines in adco_oas_api_public.h starting with IDX_1MO_TREAS
origioper – number of months from origination where borrower only makes interest payments
origballoon – number of months from origination to balloon, if any (setting to 0, negative, or 360 means absence of balloon provision).
lookback – in days
For prepay model 5.1 and early:
arm_subtype – 0 for “traditional” arms (1-1 arm, cofi), 1 - for hybrid
arm_type – if arm_subtype is 0, follows armtype enumeration in adpdefs.h. If arm_subtype is 1, arm_type follows hybridtype enumeration in adpdefs.h.
For prepay model 5.2 (unified ARM) and later:
arm_type is defined by issuer, prime/subprime, first reset, and periodic reset. A 4-digit is defined as:
#define ADCO_PRIME 1
#define ADCO_SUBPRIME 2
Using ADCO_AUTO_RESET_MAP in lieu of actual resets, lets the system select ARM model automatically.
For the complete list of ARM types, refer to the following table.
Table 1. ARM types
Comment: arm_type and arm_subtype are ignored by the LDM.
Additional optional ARM setups for prepay model 5.2 (moving-average index, prepay penalty, original GWAC, amortization type)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
int adco_set_arm_index_ma(OASHandle cp, int index_ma);
index_ma – length of moving average. Optional, default is 0.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
int adco_set_prepay_penalty_months( OASHandle cp, int num_months);
num_months – length of prepay penalty. Optional, default is 0.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
int adco_set_wac_at_origination( OASHandle cp, double orig_wac);
orig_wac – wac at origination; if not set, default is ARM index at origination plus gross margin. Optional
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
int adco_set_arm_amtype(enum sectype sec, void *cp, amtype _amt);
amtype can be selected from the enumerator in adco_oas_api_public.h:
enum amtype {
LevelPI,
LevelP,
CBond,
MinPmt};
In particular, MinPmt should be used for Option ARMs. Optional – default is LevelPI
============================================================================================
For Fixed Rate Mortgages using ADCO cashflow engine – requires OASHandle for MBS, MBSAPD, HELAPD, or MBSLDM
Required for secMBS, secMBAPD, secHELAPD, or MBSLDM
int adco_set_mbsindicative(OASHandle cp, double nCoupon, double servicing_in_bp, double guaranty_in_bp, int mbs_type, int wam, int origioper, int origterm, int origballoon, int gross_delay, int payfreq, int nextpay, enum amtype amt, int flagTBA);
mbstype – use loantype enumeration in adpdefs.h. A list of MBS models is found in Table 2. Comment: mbs_type is ignored by the LDM.
Table 2. MBS types and codes
amt – amortization type; One can choose between LevelPI (level amortization) or LevelP (level principal).
flagTBA - denotes TBA (0 - not TBA, 1 - TBA)
origballoon – balloon period from origination, in months. 0 if not balloon.
origioper – loan’s IO period from origination, in months. 0 if not an IO.
Gross_delay – in days.
wam – current WAM, in months
origterm – WAM at origination, in months
nCoupon – net coupon in %.
servicing, guarantee – spreads in bps.
payfreq – payment frequency in months between payments; 1 for monthly payments, 3 for quarterly, 12 for annual…
nextpay – months till next payment.
For INTEX securities - requires OASHandle for iCMO or iCMOLDM
Passing iCMO name, Deal/Bond Ids, Intex data location. Required
int adco_set_icmo(OASHandle cp, char *CDULoc, char *CDILoc, char *Cusip, char *DealID, char *BondID,
long collmode, long callflag, ICMO *icmoptr);
CDULoc, CDILoc - Intex data location
Cusip - bond’s Cusip
DealID, BondID - Intex’s combination of Deal ID and Bond ID. If Null, Cusip is regarded; if not Null, they take superiority over Cusip, which will be ignored
Collmode - collateral aggregation mode, from the following list defined in iCMO.h:
#define ICMODEAL_SEASONED_POOLS 1 /* deal with individual pools */
#define ICMODEAL_SEASONED_CLUSTERS 2 /* deal with clustered collat */
#define ICMODEAL_SEASONED_WAVG 3 /* deal with one wavg collateral */
#define ICMODEAL_SEASONED_EXPLODE 4 /* expand any Mega/Giant pools */
Callflag: - whether to regard the cleanup call or not.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
For callers making their own icmo_deal call, this function allow them to get access to the OAS function that sets tuning parameters, which are otherwise unavailable through the Intex API. Optional.
Use Intex’s enhanced dataset for prepay modeling. Optional for iCMO, ignored by iCMOLDM.
int adco_set_use_enhanced_data(enum sectype sec, void *cp, int in_use_data);
If in_use_data is not 0, AOLS, FICO, LTV, geographical data, etc. in Intex’s dataset will be employed for enhanced prepay modeling.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Passing user-defined default and loss severity assumptions. Optional for iCMO, ignored by iCMOLDM.
int adco_set_default_loss(enum sectype sec, void *cp, enum adco_default_model default_model, double * default_rate_in_percent, int default_months, double * severity_in_percent, int severity_months);
default_model – use adco_default_model enumeration in adco_oas_api_public.h:
enum adco_default_model
{
ADCO_NOT_SET = 0, /*default*/
ADCO_CDR = 1,
ADCO_SDA = 2,
ADCO_MODEL = 3
};
Default_rate_in_percent – array of doubles to use as monthly default rate. Index 0 corresponds to trade date. MUST have at least default_months elements
Default_months – number of elements in default_rate_in_percent array.
Severity_in_percent – array of doubles to use as monthly severity, in percent. MUST have at least severity_months elements.
Severity_months – number of elements in severity_in_percent array.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Passing user-defined delinquency and recovery assumptions. Optional for iCMO, ignored by iCMOLDM.
int adco_set_delinquency(enum sectype sec, void *cp, double * delinq_array, int del_months, double * del_recovery, int recov_months);
delinq_array – array of doubles to use as monthly delinquency rate. Index 0 corresponds to trade date. MUST have at least del_months elements
del_months – number of elements in delinq_array.
del_revovery – array of doubles to use as monthly severity, in percent. MUST have at least recov_months elements.
recov_months – number of elements in del_recovery array.
============================================================================================ For Chasen securities – requires OASHandle for cCMO
Required for seccCMO:
int adco_set_ccmo(OASHandle cp, char *input_path,
char *Cusip, char *ISIN, char *DealID, char *BondID, int aggregation, int call_flag, CMO_STRUCT *ccmoptr);
input_path is path to Chasen datafile directory
aggregation – 0 for not detailed, 1 for detailed. Default 0.
Call_flag – 1 for run to call. 0 for do not call. Default 0.
Set ccmoptr to NULL to load deal from datafiles
For External Cashflow Securities – User must calculate cashflows
Required for XCF securities
int adco_set_xcfindicative(OASHandle cp, int gross_delay, xcfGenFn cashflowfn, void *usrptr);
cashflowfn – A pointer to a function of the form:
double xcfGenFn(FLOWS *,void *, indexFcstFn, void *)
We will call your cashflow function for each path. You can call our index forecasting function (indexFcstFn) to request paths for any rate you need to calculate the cashflow.
usrptr- Can point to any data you may need in your cashflow function. We pass it back to you each time we call your cashflow function.
Step 3a – Compute Speed Multipliers based on enhanced collateral information
For every MBS or CMO, one can take advantage of enhanced collateral information (AKA agency disclosed data) and improve accuracy of prepayment forecasts. Functions take underpin this enhanced service within 5.1 prepayment modeling are extracted into a separate library, CalcRM.dll. Before setting refinancing and turnover tuning scales (“multiples”) one should compute them based on collateral details.
After calls to CalcRM(), GetRefi(), and GetTO() are made, obtained multipliers should be combined with any other tunings (physical or risk neutral) and set via calls to adco_set_FixedTuning() and adco_set_ARMTuning() – see step 5 further.
Starting in Version 7.2, Risk Multipliers of agency passthroughs/cmos through Intex can be calculated automatically based on enhanced data in Intex’s mbspools database. User MUST license Intex’s mbspools database to take advantage of this, and this is only for agency deals. User must load the deal in SEASONED_POOLS or SEASONED_EXPLODE to take advantage of this. If enhanced Intex data is used, do not calculate tunings based on enhanced data using calcrm.dll. Functions dealing with this functionality are as follows.
Set whether to use Intex’s enhanced agency data. Optional for iCMO, ignored by iCMOLDM.
int adco_set_use_enhanced_data(enum sectype sec, void *cp, int in_use_data);
Set in_use_date to 1 to load and use enhanced agency data from Intex’s mbspools database or in general any data in their
POOL_INFO->pi_loanattrp->loanattr_addl_attributes linked list and states in POOL_INFO->pi_loanattrp->loanattr_geop linked list.
After running the deal, user can query us to return the weighted-average risk multipliers used on the collateral:
Returns 0 if risk multipliers were calculated, -1 if not. It may return 0 if run in SEASONED_WAVG mode (in which case if we loaded the deal, enhanced data was not actually used). We will fill in_refi, in_to, in_co, and in_cure with our weighted average risk multipliers.
============================================================================================
Step 3b – Set up loans’ credit data for the use by LDM
For MBSLDM and ARMLDM securities, the following calls are used to supply data (both mandatory and optional) for its use by the LDM. Calls marked as required are also used by iCMOLDM securities to supply default values for mandatory fields having missing values in Intex dataset. Categorical fields declared as double (such as occupancy, geography, etc.) can be entered using “portfolio style”, in percentages.
Setting loan size. Required.
int adco_set_ldm_loansize(OASHandle cp, double in_orig_bal, double in_cur_bal);
in_percent_c - percent of current loans
in_perc_30, etc. - percent of loans in certain delinquency status
in_perc_foreclosed - percent of loans being foreclosed
in_perc_REO - realestate owned (REO) loans
============================================================================================
Setting mortgage insurance data. Optional
int adco_set_ldm_mortgage_insurance(OASHandle cp, int in_flag_orig, int in_flag_cur, double in_percent_covered);
in_flag_orig - did loan have MI at orogination? 0 or 1
in_flag_cur - does loan have MI now? 0 or 1
in_percent_covered - if Yes, how much is covered?
============================================================================================
Setting property type. Optional
int adco_set_ldm_property_type(OASHandle cp, double in_sfr, double in_condo, double in_mh, double in_co_op, double in_pud, int in_numunits);
in_sfr - percent of single-family loans
in_condo - percent of condo loans
in_mh - percent of manufactured housing loans
in_co_op - percent of coop loans
in_pud - percent of PUD loans (planned urban development)
in_numunits - number of units (1 through 4)
============================================================================================
Setting loan purpose. Optional
in_purchase - percent of loans used to purchase homes
in_refi_cashout - percent of loans used to cashout refinance
in_refi_rate - percent of loans used to rate refinance
in_construction - percent of loans used to construct homes
============================================================================================
Setting loan occupancy. Optional
Int adco_set_ldm_occupancy(OASHandle cp, double in_owner, double in_second_home, double in_investor);
in_owner - percent of owner occupied homes
in_second_home - percent of second homes
in_investor - percent of investor homes
============================================================================================
Setting documentation information. Optional
Int adco_set_ldm_documentation(OASHandle cp, double in_full, double in_limited, double in_none);
in_full - percent of fully documented loans
in_limited - percent of loans having limited documentation
in_none - percent of loans having no documentation
============================================================================================
Setting geographical distribution. Optional
int adco_set_ldm_geography(OASHandle cp, double* in_states, int array_size, long in_zipcode, long in_msa, long in_cbsa, long in_cbsa_sub);
in_states - array of percentages per each of the US states in order
array_size - number of states, typically 55 = 51 states including DC alphabetically and PR (52), GU (53), VI (54), US (55)
If in_states pointer is NULL, the same function allows setting up data for a particular ZIP, MSA or CBSA.
Define Price, OAS, BEEM, or Yield and use that quote to produce all other results. Price and yield should be in % (99.5 not 0.995, 7.5 not 0.075) and OAS goes in as basis points.
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until adco_analyze is run again.
============================================================================================
Define prepay model to perform all analysis. See the enum ppmodel in the adco_oas_api_public.h header file for the choices.
enum ppmodel {
ADCO_PPMODEL,
CPR,
PSA,
ABS, /* Intex only - use ICMOSPDT_VABS */
MHP, /* Intex only - use ICMOSPDT_VMHP */
HEP, /* Intex only - use ICMOSPDT_VHEP */
PPC, /* Intex only - use ICMOSPDT_VPPC */
ADCO_NONE, /* Don't search for equivalent prepay */
CPR_Vector,
PSA_Vector,
SMM_Vector
};
The prepayspeed should be entered as a % not a decimal. So, 6% CPR is 6 not 0.06, 100% PSA is 100 not 1.0, and the ADCO model default scale tuning is 1.0
Optional – Default is ADCO_PPMODEL with speed of 1.0
Some analyses return an equivalent prepayment speed, which is the speed (using a different prepay model) that would produce the same average life on the security studied. For example, assuming the prepay model has been set to ADCO_PPMODEL and the equivalent prepay model has been set to CPR, the analysis will give the single CPR that produces the same average life as the vector of speeds produced by the ADCO prepay model.
Optional – Default is CPR for secARM and similar and PSA for secMBS, seciCMO and similar
int adco_set_prepay_equiv(enum sectype sec, OASHandle cp, enum ppmodel prepaymodel);
============================================================================================
An important part of working with ADCo prepay models is programmatic tuning. Tunings can be performed on the entire modeling family (such as all fixed-rate MBS) or on a single model (such as whole loan 30-yr fixed). Such tuning sets are multiplicative.
Models 5.1 and later can be tuned “backwards and forward” or “forward only”. In the former case, prepayment parameters change from the pool’s origination and affect the past burnout process. In the latter case, the burnout occurs with an un-tuned model; tunings apply to forward time only. An example of forward-only tunings is risk-neutral tunings that stem from future prepay risk consideration. An example of forward and backward tunings is tunings demanded by enhanced data. The same-named tunings are multiplicative.
All tunings of newer models apply to older models as well – to the extent concerning common tuning factors. For example, refinancing tuning set-up by a 5.2 ARM tuning function will affect refinancing of 5.1, 5.0, and 4.3 ARM models. However, the cashout tuning set-up in the 5.2 ARM model won’t get propagated to the 4.3 model because it does not exist there. It is generally enough to tune the newer models only.
Set tunings for all ARM models
Optional default all 1.0
int adco_set_ARMTuning(enum sectype sec, OASHandle cp, double age_burnout, double base_level, double lag, double ramp_age, double rate_level);
int adco_set_Arm52Tuning(enum sectype sec, void *cp, int tuning_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
int adco_set_Arm52ModelTuning_Extra(enum sectype sec, void *cp, int arm_type, int tuning_type, double post_reset_scale, double dummy1, double dummy2, double dummy3);
New tail tuning for arm_unified handles. 3 placeholder arguments.
tuning_type allows to distinguish between “backward and forward” tuning (0) and “forward only” tuning (1).
============================================================================================
Set tunings for one ARM model (defined by model_type)
Optional default all 1.0
int adco_set_ARMModelTuning (enum sectype sec, void *cp, int model_type, double age_burnout, double base_level, double lag, double ramp_age, double rate_level);
int adco_set_Arm52ModelTuning(enum sectype sec, OASHandle cp, int arm_type, int tuning_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
int adco_set_Arm52Tuning_Extra(enum sectype sec, void *cp, int tuning_type, double post_reset_scale, double dummy1, double dummy2, double dummy3);
Tail tuning for specific 5.2 arm_types.
model_type should match an ARM model numeration found in adco_oas_api_public.h
tuning_type allows to distinguish between “backward and forward” tuning (0) and “forward only” tuning (1).
============================================================================================
Set tunings for all fixed-rate models
Optional default all 1.0
int adco_set_FixedTuning(enum sectype sec, OASHandle cp, double burnout, double curve_shape, double lag, double slide, double turnover, double refi, int ptseff);
int adco_set_Fixed51Tuning(enum sectype sec, OASHandle cp, int tuning_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
tuning_type allows to distinguish between “backward and forward” tuning (0) and “forward only” tuning (1).
============================================================================================
Set tunings for one fixed-rate model (defined by model_type)
Optional default all 1.0
int adco_set_FixedModelTuning(enum sectype sec, void *cp, int model_type, double burnout, double curve_shape, double lag, double slide, double turnover, double refi);
int adco_set_Fixed51ModelTuning(enum sectype sec, OASHandle cp, int model_type, int tuning_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
model_type should match an MBS model numeration found in adco_oas_api_public.h
tuning_type allows to distinguish between “backward and forward” tuning (0) and “forward only” tuning (1).
sato_resid_tuning - tuning for “SATO residual” factor (1.1 = make effect 10% stronger)
sato_tuning - tuning for the SATO factor (1.1 = make effect 10% stronger)
delinquency_scale - tuning for MDR vector (1.1 = make all MDRs 10% higher)
severity scale - tuning for the loss severity scale (1.1 = make severity 10% stronger)
FICO_slide - tuning for FICO (e.g. -60 = subtract 60 from stated FICOs)
LTV_slide - tuning for LTV (e.g. 6.0 = add 6 to stated LTVs)
int adco_set_tunings_HPI(OASHandle cp, double user_drift, double user_diffusion0);
user_drift - tuning for the long-term HPA rate (-2.0 = subtract 2% from the model’s long-term equilibrium)
user_diffusion0 - tuning for the short-term HPA rate (-2.0 = subtract 2% from the model’s “initial diffusion” rate)
Step 6 - Select which calculations and pricing methods should be run
All calculations except calcoas are turned off by default 0=don't run, -1=run
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until adco_analyze is run again
============================================================================================
int adco_set_CalculateBasic(enum sectype sec, OASHandle cp, int cstatic, int forward, int scenario, int pathnum);
-Calculating static produces single vector results assuming constant rates and the use of the equivalent prepay speed from the current curve scenario
-Calculating forward produces single vector results assuming forward rates and prepay speeds from whatever model you’ve selected
-Calculating scenario produces single vector results assuming rates evolve as described by shifts you’ve input
============================================================================================
int adco_set_CalculateStaticDur(enum sectype sec, OASHandle cp, int calcspreaddur, int calcindexdur);
-Spread duration the % price change for a 1 bp change in yield
-Index duration is the % price change for a 1 bp change in inidices
============================================================================================
int adco_set_CalculateOASBasic(enum sectype sec, OASHandle cp, int calcoas, int calceffdurconvex, int calcppdur);
-Effective duration is the % price change for a 100 bp change in rates (+/- 50bps from current levels)
-Prepayment duration is the % price change for a 10% change in prepayment speed (+/- 5% from current levels)
============================================================================================
int adco_set_CalculateOASAdvanced(enum sectype sec, OASHandle cp, int calcoasdur, int calckeyrates, int calcmtgesprddur, int calcavgmoddur, int calcvega);
-OAS duration is the % price change for a 1bp change in OAS (calculated using +/- 5bps and divided by 10)
============================================================================================
int adco_set_use_backward_induction(enum sectype sec, OASHandle cp, int a)
-Setting a to –1 will use backward induction when possible (single-factor models, secMBSAPD, secHELAPD, secArm_Unified); doesn’t alter valuation of other instruments
-Setting a to 0 (default) will use Monte-Carlo or quasi-Monte-Carlo
============================================================================================
int adco_set_CalculateShockedPx(enum sectype sec, OASHandle cp, int calcshockedpx);
-Produces shocked prices; The number of shocks is calcshockedpx, shock sizes are defined by adco_set_px_shift_array function (step 6b)
============================================================================================
int adco_set_CalculateSwap(enum sectype sec, OASHandle cp, int cswap);
============================================================================================
int adco_set_CalculateARMTuningDurations(enum sectype sec, OASHandle cp, int age_burnout, int base_level, int lag, int ramp_age, int rate_level);
-Tuning durations are the % price change for a 10% change in the tuning factor (+/- 5% from current levels)
============================================================================================
int adco_set_CalculateFixedTuningDurations(enum sectype sec, OASHandle cp, int burnout, int curve_shape, int lag, int slide, int turnover, int refi);
-Tuning durations are the % price change for a 10% change in the tuning factor (+/- 5% from current levels)
============================================================================================
int adco_set_CalculateKeyRatesQuick(enum sectype sec, void *cp, int calckeyratesQ);
-Uses grouped shocks for key-rate duration/convexity analysis if calckeyratesQ = 1.
============================================================================================
int adco_set_CalculateKeyRatesStatic(enum sectype sec, void *cp, int calckeyratesC);
-Measures key-rate duration/convexity off static cashflow if calckeyratesC = 1.
============================================================================================
int adco_set_CalculateKeyRatesOld7(enum sectype sec, void *cp, int calckeyrates7);
-Measures “old-style” key-rate duration/convexity if calckeyratesC = 1. The key rates are defined by 7 old OAS model yield curve points.
============================================================================================
int adco_set_CalculateTRR(enum sectype sec, OASHandle cp, int calctrr, int trrhorizon, int trrreinvyldcurvemat, int reinvspread);
-Sets total rate of return analysis given horizon (trrhorizon) and reinvestment assumptions. Computing TRR also produces horizon price.
============================================================================================
Step 6a – Setting up Credit OAS-specific tasks (MBSLDM, ARMLDM and iCMOLDM securities)
The Credit OAS method is engaged automatically for MBSLDM, ARMLDM and iCMOLDM securities when any of the tasks require running the OAS computational engine. User can compute exposures (“durations”) to HPA short-term or long-term rates as well as few critical tunings affecting the LDM. In all set-up call, calc is the flag, shift is the step for computing.
============================================================================================
int adco_set_CalculateHpi_drift_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to the long-term HPA rate. Optional, shift default is 0.5%.
============================================================================================
int adco_set_CalculateHpi_diffusion0_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to the short-term HPA rate. Optional, shift default is 0.5%.
============================================================================================
int adco_set_CalculateFICO_slide_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to FICO. Optional.
============================================================================================
int adco_set_CalculateLTV_slide_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to LTV. Optional.
============================================================================================
int adco_set_CalculateMDR_scale_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to the monthly default rate (MDR) scale. Optional.
============================================================================================
int adco_set_CalculateSeverity_scale_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to the loss severity scale. Optional.
============================================================================================
Step 6b – Modify the default behavior of some of the calculations
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until adco_analyze is run again
All of these functions are optional and are needed only, for example, to modify the size of a shift used in one of the duration calculations
============================================================================================
int adco_set_effdur_shift(enum sectype sec, void *cp, double shift);
Sets up shift to compute Effective Duration and Convexity. Optional, default is 50 basis points.
============================================================================================
int adco_set_px_shift(enum sectype sec, void *cp, double *shift);
Sets up to 8 shocks (in basis points, pointed by shift pointer) for automated shocked prices computation. Optional.
============================================================================================
int adco_set_px_shift_array(enum sectype sec, void *cp, double *shift, int num);
Sets unlimited number of user-defined shocks (in basis points, pointed by shift pointer); num is the shock number. This shift array will be employed if adco_set_CalculateShockedPx function is called (see above). Optional.
============================================================================================
int adco_set_oasdur_shift(enum sectype sec, void *cp, double shift);
Sets up shift to compute OAS (spread) duration. Optional, default is 5 basis points.
============================================================================================
int adco_set_spreaddur_shift(enum sectype sec, void *cp, double shift);
Sets up shift to compute current coupon spread duration. Optional default is 1 basis point.
============================================================================================
int adco_set_indexdur_shift(enum sectype sec, void *cp, double shift);
Sets up shift to compute ARM index (spread) duration. Optional, default is 1 basis point.
============================================================================================
int adco_set_ppdur_shift(enum sectype sec, void *cp, double shift);
Set up shift to compute prepay scale duration. Optional, default is 5 (% of base value).
============================================================================================
int adco_set_vega_shift(enum sectype sec, void *cp, double shift);
Set up shift to compute Vega. Optional, default is 1 (relative % of the base volatility level, i.e. if base=20, then shift to 19.8 and 20.2).
============================================================================================
int adco_set_DurCvxflag(enum sectype sec, OASHandle cp, enum DurCvxBasis a);
The last argument controls how effective duration, convexity and shocked prices are computed. Setting it between 0 and 4 informs the OAS system to interpolate shocked prices and the Greeks off the pricing grid already computed in the course of backward induction, at no additional cost of computational time. If so, shift argument is interpreted as a shock in the short rate (a is 0), one-year rate (a is 1), two-year rate (a is 2), ten-year rate (a is 3), or mortgage rate (a is 4). Once shift denotes change in one selected rates, other rates are taken off the same grid, i.e. follow the internal law of the term structure model employed. Setting a to –1 (default) results in parallel shock of the entire curve performed at the cost of computational time. Optional, default is -1. It changes behavior only when backward induction is employed.
============================================================================================
Step 6c – Exporting cashflow vectors
The AD&Co OAS system allows callers to develop own callback routines that store or export cashflows generated in the course of processing. AD&Co itself has developed a small library, xlflows.dll that performs these functions.
Call this function if you've set up a callback function conforming to AD&Co’s API which will allows reading or copying cashflows and rates:
int adco_set_user_cf(enum sectype sec, OASHandle cp, void (*user_cf_function)(int a, int b, FLOWS *c, void *ptr));
user_cf_function is a callback function pointer – either a pointer to your own function or to ours
a is the “task locator”, e.g. 1 for static analysis, 2 for forward analysis, 5 for the OAS run, etc. For definitions and logic, look at adco_cfcallback in xlflows.c.
b is the path number.
FLOWS is structure defined in adco_oas_api_public.h:
typedef struct flows {
/* added for defaults */
double cbal[MAXMONTHS]; /* current balance */
double dbal[MAXMONTHS]; /* delinquent balance */
double sbal[MAXMONTHS]; /* seriously delinquent balance */
double mdrrt[MAXMONTHS]; /* MDR rate */
double severintyrt[MAXMONTHS];/* severity rate */
double plossflow[MAXMONTHS]; /* principal loss per period */
double ilossflow[MAXMONTHS]; /* interest loss per period */
double plossDflow[MAXMONTHS];/* cum non-advanced delinquent principal */
double plossSflow[MAXMONTHS];/* cum non-advanced seriously delinquent principal */
} FLOWS;
MAXMONTHS is defined in ADIRdefs.h:
#define MAXMONTHS 372
ptr is only used if you create your own cashflow callback function. It exists in case you want to access some of your own data in your cashflow callback function. To use it, call adco_set_user_ptr(). We will always pass this pointer to the callback function (or NULL if you did not set).
=============================================================================================
int adco_set_user_ptr (enum sectype sec, void *cp, void *ptr);
ptr is a pointer to your own data structure, casted to (void *). As mentioned above, if you set this we will pass this pointer to your cashflow callback function.
Examples of user_cf_function can be found in xlflows.dll. These functions can be customized and even replaced by other developers.
void adco_cfcallback(int WhereAmI, int WhereAmIPath, FLOWS flow); /* regular format */
void adco_cfcallback_ldm(int WhereAmI, int WhereAmIPath, FLOWS flow); /* extended format showing LDM-specific results */
============================================================================================
Utilities placed in xlflows.dll that can be used to get an address of function or data and pass file name, initial balance and print header:
int adco_AddressOf(void *struc); /* for structure */
int adco_AddressCF(); /* returns address of the regular cashflow function, adco_cfcallback */
int adco_AddressCF_LDM(); /* returns address of the extended cashflow function, adco_cfcallback_ldm */
int adco_set_xl_cf(char *fn, char *pid, double bal, int headers );
fn – file name for export
pid – id of position (cusip)
bal – balance
headers – print column headers (1) or don’t (0)
============================================================================================
Below is an example of code that sets the function pointer:
double bal = 1000000;
char *filename[200] = “c:\adco\oas\flows_100.txt”;
int fnptr = adco_AddressCF();
adco_set_user_cf(sectype, OASHandle, fnptr);
adco_set_xl_cf(filename, "123123123", balance, 1);
The 2nd line returns a pointer to adco_cfcallback function and the 3rd line passes it to the OAS library. This function will be called each time a cashflow vector is generated. The output will be found in flows_100.txt file, which will have the standard format with headers; all cashflow components will be shown off a $1M face amount.
Call this function to cause adco_analyze to dump inputs to a file for debugging, use for input in our spreadsheet application to verify results. Pass in full path (including file name) and adco_analyze will create or append a text file containing all inputs that have been set (by default or user function calls).
Optional – default is NULL
int adco_set_dumpfile(enum sectype sec, OASHandle cp, char *filepath);
Pass NULL or empty string to turn off input dumping
Pass “stdout” to have dumping directed to stdout
If you run portfolio batch, deleting and initializing OAS handles for each position is possible but may be not optimal. One can create and re-use OAS handles. For example, the following call,
icmo = adco_getiCMOLDMHandle();
returns an OAS handle to an Intex CMO. After this iCMO is processed, we can re-use icmo variable for other LDM-linked CMOs. Of course, we must write a programming block that fills in necessary data for each CMO. We will delete the handle only at the end of portfolio batch:
Developer can optimize portfolio processing by re-using interest rate grid (calibrated to market data) when moving from one instrument to another. Some operations, such as computing key rate durations, change the grid and it can’t be re-used. In many other cases, the grid requires only initial construction. For example, computing prepay model tuning duration or spread will not alter the interest rates. If one needs to compute effective duration and convexity, it will allow re-using the grid only if the Greeks are taken directly off the valuation grid, i.e. argument a is set to 0 to 4 when adco_set_DurCvxflag is called. If the Greeks are computed in a traditional, explicit parallel-shock, style, then the grid is rebuilt each time and becomes not re-usable.
The OAS library can decide itself whether the rate grid is re-usable by analyzing the full set of tasks.
int adco_can_reUseIR(enum sectype sec, OASHandle cp);
Returns –1 if the grid is re-usable, 0 otherwise.
int adco_set_reUseIR(enum sectype sec, OASHandle cp, int a);
Set a to –1 if you plan to re-use the grid.
A typical use of these two functions is shown in the following programming flow.
for (k=1; k<=N; k++){ /* Beginning of Portfolio Loop */
……………………………….
/* End of Portfolio Loop, just before moving to the next position */
If (adco_can_reUseIR(sectype, oasHandle) != 0)
dataStatus = adco_set_reUseIR(sectype, oasHandle, -1);
}
Step 7c – Optimizing Portfolio Flow: Monte-Carlo seed control
For some purposes user may be interested in running each portfolio’s position using different set of paths. For example, computing losses in a large cohort of loans can be done quicker by using few paths per loan, different for each loan. This path “shuffling” will create enough variability from the portfolio stand-point. On the other hand, valuation of an asset against its hedge requires using the same set of paths.
This can be accomplished using the following functions:
Getting random initial seed.
int adco_get_init_seed(OASHandle cp, long *_init_seed);
init_seed – current seed
Setting initial seed.
int adco_set_init_seed(enum sectype sec, OASHandle cp, long seed);
seed – initial seed that will overwrite standard seed (-1) or previously reset seed
A typical use of these two functions is shown in the following programming flow.
for (k=1; k<=N; k++){ /* Beginning of Portfolio Loop */
……………………………….
/* End of Portfolio Loop, just before moving to the next position */
If flag same_init_seed is not 0, the loop inside the brackets won’t be performed. If it is 0, the program will get the random seed currently used by the engine and “set” it. This operation overwrites the initial seed (typically -1) normally used by the OAS engine.
Another application of random seed is setting a test for computing Monte-Carlo accuracy. For this test, we run many Monte-Carlo pricing runs and apply the coding sample above before moving to the next run. This ensures that runs are performed using different initial seeds, and the results’ dispersion points to the valuation accuracy.
Only get the results you need and only what you asked for before calling adco_analyze
If a function gets multiple results but you don't need all, you can pass in NULL for any result you don't want
int adco_get_errmsg(enum sectype sec, OASHandle cp, char *errmsg); -Getting error message
============================================================================================
int adco_get_forwardResults(enum sectype sec, OASHandle cp, double *fwd_crv_yld,double *fwd_crv_wal, double *fwd_crv_sprd,
double *fwd_crv_equiv); -Results of forward-curve analysis
============================================================================================
int adco_get_currentResults(enum sectype sec, OASHandle cp, double *curr_crv_yld,double *curr_crv_wal, double *curr_crv_sprd,
double *curr_crv_equiv,double *curr_crv_wal_sprd); -Results of current-curve analysis
============================================================================================
int adco_get_scenarioResults(enum sectype sec, OASHandle cp, double *scenario_crv_yld,double *scenario_crv_wal,
double *scenario_crv_equiv); -Scenario analysis results
============================================================================================
int adco_get_staticResults(enum sectype sec, OASHandle cp, double *static_yld,double *static_sprd);
-Results of “static” (equivalent speed) run
============================================================================================
int adco_get_spread_duration(enum sectype sec, OASHandle cp, double *spreaddur, double *upprice, double *downprice);
-CC spread duration and shocked prices
============================================================================================
int adco_get_swap(enum sectype sec, OASHandle cp, double *rprice, double *pprice, double *diffprice);
============================================================================================
int adco_get_index_duration(enum sectype sec, OASHandle cp, double *indexdur, double *upprice, double *downprice);
-ARM index duration and shocked prices
============================================================================================
int adco_get_price(enum sectype sec, OASHandle cp, double *price, double *accrued_int); -Computed price and accrued interest
============================================================================================
int adco_get_oas(enum sectype sec, OASHandle cp, double *oas); -Computed OAS
============================================================================================
int adco_get_mod_duration(enum sectype sec, OASHandle cp, double *mod_duration); -Modified duration
============================================================================================
int adco_get_oas_duration(enum sectype sec, OASHandle cp, double *oas_duration, double *upprice, double *downprice);
-OAS duration and shocked prices
============================================================================================
int adco_get_effective_duration(enum sectype sec, OASHandle cp, double *eff_duration, double *eff_convexity, double *upprice, double *downprice); -Effective duration, convexity and shocked prices
============================================================================================
int adco_get_arm_tuning_durations(enum sectype sec, OASHandle cp, double *ramp_age_factor_dur, double *age_burnout_factor_dur,
double *base_level_factor_dur, double *rate_level_factor_dur, double *lag_factor_dur); -5 ARM prepay tuning durations
============================================================================================
int adco_get_fixed_tuning_durations(enum sectype sec, OASHandle cp, double *curve_shape_factor_dur, double *slide_factor_dur,
double *burnout_factor_dur, double *lag_factor_dur, double *turnover_factor_dur, double *refi_factor_dur); -6 MBS prepay tuning duration
============================================================================================
int adco_get_pp_duration(enum sectype sec, OASHandle cp, double *pp_duration, double *upprice, double *downprice);
-Duration to overall prepay scale and shocked prices
============================================================================================
int adco_get_vega(enum sectype sec, OASHandle cp, double *vega, double *upprice, double *downprice);
-Computed Vega and shocked prices
============================================================================================
int adco_get_kr_duration(enum sectype sec, OASHandle cp, double *yc1m, double *yc3m, double *yc6m, double *yc1y, double *yc2y,
double *yc3y, double *yc4y, double *yc5y, double *yc7y, double *yc10y, double *yc15y, double *yc20y, double *yc25y, double *yc30y);
-Full set of 14 key-rate durations
============================================================================================
int adco_get_kr_convexity(enum sectype sec, OASHandle cp, double *yc1m, double *yc3m, double *yc6m, double *yc1y, double *yc2y,
double *yc3y, double *yc4y, double *yc5y, double *yc7y, double *yc10y, double *yc15y, double *yc20y, double *yc25y, double *yc30y);
-Full set of 14 key-rate convexities
============================================================================================
int adco_get_kr_durationQuick(enum sectype sec, OASHandle cp, double *yc1M1Y, double *yc2Y3Y, double *yc4Y5Y, double *yc7Y10Y,
double *yc15Y30Y); -5 grouped key-rate durations
============================================================================================
int adco_get_kr_durationStatic(enum sectype sec, OASHandle cp, double *yc1M1Y, double *yc2Y3Y, double *yc4Y5Y, double *yc7Y10Y,
double *yc15Y30Y); -5 grouped static key-rate durations
============================================================================================
int adco_get_kr_convexityQuick(enum sectype sec, OASHandle cp, double *yc1M1Y, double *yc2Y3Y, double *yc4Y5Y, double *yc7Y10Y,
double *yc15Y30Y); -5 grouped key-rate convexities
============================================================================================
int adco_get_kr_durationOld7(enum sectype sec, void *cp, double *yc3m, double *yc6m, double *yc1y, double *yc2y, double *yc5y, double *yc10y, double *yc30y); -7 “old-style” key-rate durations
============================================================================================
int adco_get_kr_convexityOld7(enum sectype sec, void *cp, double *yc3m, double *yc6m, double *yc1y, double *yc2y, double *yc5y, double *yc10y, double *yc30y); -7 “old-style” key-rate convexities
============================================================================================
int adco_get_pxshocks(enum sectype sec, OASHandle cp, double *pxshocks); -Prices of automated parallel shocks
============================================================================================
int adco_get_trr(enum sectype sec, OASHandle cp, double *trr, double *hrzn_price, double *hrzn_wal, double *hrzn_yld, double *hrzn_flow);
-Results of Total Return Analysis
============================================================================================
int adco_get_rmseP(OASHandle cp, double *_rmseP); -Sampling accuracy of pricing (Root-Mean-Squared-Error of Price)
============================================================================================
int adco_get_rmseOAS(OASHandle cp, double *_rmseOAS); -Sampling accuracy of pricing (Root-Mean-Squared-Error of OAS)
============================================================================================
int adco_get_stdevPV *OASHandle cp, double *stdevPV); -Standard deviation of path-wise PVs
============================================================================================
int adco_get_pvalue(OASHandle cp, double *_pvalue); -Present Value
============================================================================================
int adco_get_settleDTFactor(OASHandle cp, double *_settleDTFactor); -Expected amortization factor between Trade Date and Settlement
Date
============================================================================================
int adco_get_1moSMM(OASHandle cp, double *_SMM); -Next-month SMM forecast for all rate scenarios (for PTs and ARMs)
============================================================================================
int adco_get_VMR(OASHandle cp, double *_svol, double *_mrev); -Calibrated (or entered) short-rate volatility and mean reversion
============================================================================================
int adco_get_cum_loss_default(enum sectype sec, void *cp, double * cum_loss, double * cum_default);
-Cumulative loss and default rate
============================================================================================
Special Credit OAS outputs (all LDM instruments)
int adco_get_ldm_cumloss_default(OASHandle cp, double * cumloss_static, double * cumloss_random, double * cumdefault_static,
double * cumdefault_random); - Cumulative loss and default rates, both static and averaged
============================================================================================
int adco_get_hpi_drift_durcvx(OASHandle cp, double * hpi_drift_dur, double * hpi_drift_cvx);
-Duration and convexity to the long-term HPA rate
int adco_get_hpi_diffusion0_durcvx(OASHandle cp, double * hpi_ diffusion0_dur, double * hpi_ diffusion0_cvx);
-Duration and convexity to the short-term HPA rate
============================================================================================
int adco_get_FICO_slide_durcvx(OASHandle cp, double * FICO_slide_dur, double * FICO_slide_cvx);
int adco_get_LTV_slide_durcvx(OASHandle cp, double * LTV_slide_dur, double * LTV_slide_cvx);
int adco_get_MDR_scale_durcvx(OASHandle cp, double * MDR_scale_dur, double * MDR_scale_cvx);
int adco_get_Severity_scale_durcvx(OASHandle cp, double * Severity_scale_dur, double * Severity_scale_cvx);
-Duration and convexity to LDM’s key tunings
============================================================================================
Intex Fields – For Intex CMOs only
int adco_get_itxDeal(OASHandle cp, char *dealstr); -Deal ID (given cusip)
============================================================================================
int adco_get_itxBond(OASHandle cp, char *bondstr); -Bond ID (given cusip)
============================================================================================
int adco_get_itxTrancheType(OASHandle cp, char *typestr); -Tranche type
============================================================================================
int adco_getitxBalanceAndFactor(OASHandle cp, double * bal, double *fact); -Bond’s balance and factor
============================================================================================
Int adco_get_itx_LatestCDU(OASHandle cp, long *cdudate); -CDU date
============================================================================================
int adco_get_itxBalanceAndFactor_Collateral(OASHandle cp, double *balance_Collateral, double *factor_Collateral);
-Collateral balance and factor
============================================================================================
int adco_get_itxSupportInfo(OASHandle cp, double *support_orig, double *support_cur);
-Bond’s original and current supports (%)
============================================================================================
int adco_get_itxMisc(OASHandle cp, int *deal_age, char *rating ); -Deal’s average age and bond’s original rating
============================================================================================
int adco_get_itxCurrentRatings(OASHandle cp, char *curr_rating); -Bond’s current rating
============================================================================================
int adco_get_itxDelInfo(OASHandle cp, double *writedown, double *collatloss, double *delinquency);
-Accumulated bond’s writedown, collateral loss, and delinquency composition: [0] = current, [1] = 30-day,….[8] = ROE, [9] = bankrupt
============================================================================================
int adco_get_itxPercentLSKnown(OASHandle cp, double *calculated_ls_known);
-Percentage of loans having known loan sizes
============================================================================================
Chasen Fields – For Chasen CMOs only
int adco_get_chasenDeal(OASHandle cp, char * dealstr); -Sets dealstr to name of loaded deal
============================================================================================
int adco_get_chasenBond(OASHandle cp, char * bondstr); -Sets bondstr to name of loaded bond
============================================================================================
int adco_get_chasenBalanceAndFactor(OASHandle cp, double * bal, double * fact);
-Sets balance, factor as of date from which Chasen loaded deal
API INTEGRATION CODING FOR DEVELOPERS
Valuation Solutions
OAS Model
API Documentation for Vendors and Developers
AD&Co OAS system version 8 is a powerful tool that enables both traditional and novel valuation methods for MBS and ABS. Integrated with client’s internal databases and applications, it allows for massive portfolio processing accurately, often at a fraction of usual time. The system can be instantly calibrated to swap rates and ATM swaption volatilities, and allows for controlling volatility skew by the term structure model selection (4 models). It can also capture the difference between pricing results obtained under single-factor and two-factor term structure modeling approaches.
The model can employ backward induction (for fixed-rate pass-throughs working with 5.1 or later prepay model and valued under any of single-factor models), which leads to a super-quick option-adjusted valuation on an interest rate grid. More traditional Monte-Carlo or quasi Monte-Carlo methods are available as well and necessary for running CMOs. The OAS library is laboriously integrated with Intex and Chasen systems generating cashflows for complex structured securities. Instruments with user-provided cashflows can be defined as well using function pointers. In general, AD&Co OAS model covers most of MBS and ABS types.
Starting from version 8, user can employ the Credit OAS valuation method that is integrated with AD&Co’s LoanDynamicsTM Model (LDM) and allows for valuing MBS and ABS with losses. Credit OAS simulates random interest rates and home prices, and for every market scenario, lets LDM forecast prepayment, default, delinquency and loss severity rates, and alter cashflow vectors accordingly. Hereinafter, we often refer to LDM as a prepayment model although its output is much richer.
Switching between AD&Co’s LDM, 5.2, 5.1 and 4.3 prepay models is seamless and convenient when valuation results need comparison. In either case, enhanced pool data (loan size, LTV, FICO, geography, etc) can improve accuracy of prepayment forecasts. The flow of this improvement is controlled by user and done exogenously. A caller can pass information on collateral details, obtain calculated corrective scales for refinancing and turnover processes (“speed multiples”) and tune the model accordingly, for each MBS. For the use of LDM, a similar set of data may be required; we will refer to it as “credit data”. In addition to the data fields used for the enhanced prepay modeling credit dataset includes loan statuses (current-delinquent-severely delinquent), documentation, lien position, mortgage insurance.
A comprehensive set of valuation measures is produced including numerous Greeks and sensitivity measures, TRR, user-supplied scenario analysis or automated rate shocks. The settlement date can be up to 12 month forward, and the difference between delivery of a TBA and a specified MBS is fully captured in valuation.
One of most unique features of AD&Co valuation concept is ability to run the same pricing engine using either “physical” prepayment model (traditional OAS method) or risk-neutral prepayment model (prepay risk-adjusted prOAS method). A licensee of the system can obtain risk-neutral calibrator, a complimentary tool that allows for calibrating prepay model to the desired prOAS levels or Duration targets.
Although the OAS system is written on C++, the library is not difficult in integration as it only includes a set of simple calls to C functions; only basic data types are passed. The sequence of programming steps flows in a logical order. Internal C++ objects allocate and free needed memory automatically.
Version 6 is connected to any of prepay models, version 4.3 to 5.1.
Version 7 is connected to any of prepay models, from 4.3 to 5.2. This version integrates prepay model 5.2 family containing new ARM models built for agencies, prime jumbos, and sub-prime ARMs. All these models follow a universal design pattern first developed and tested in version 5.1 for fixed-rate MBS.
Version 8 is connected to any of prepay models, from 4.3 to LDM. This version includes functionality of all previous versions.
Table of Contents
Overview: Steps to Run the AD&CO OAS Library
More Detailed Documentation
Step 1 - Get an OASHandle
Step 2 - Describe Market Environment
Step 3 - Set Security Parameters
Step 4 - Set Pricing
Step 5 - Set Prepayment Model and Tunings
Step 6 - Select Calculations and Pricing Methods
Step 7 - Run Analysis
Step 8 - Get Results
Step 9 - Free Handle
Overview – Steps to run ADCO OAS Library
1. Get an OASHandle – returns a pointer required for all other functions
2. Describe Market Environment
3. Set Security Parameters – Describe specific security to analyze, different functions for ARMs, MBS, Intex securities
4. Do you wish to compute refinancing and turnover prepay multiples using available enhanced pool data
5. Set Pricing - Are you quoting OAS, Price, BEEM or Yield
6. Set Prepayment Model
7. Select which calculations should be run, which valuation method to use
8. Run analysis
9. Get Results
10. Free Handle
Exhibits:
1) Sample programs for MBS portfolio, ARMs, iCMOs and cCMOs
2) Sample callback function to view cash flows
3) Sample input dump file created by program
Header files required:
ADIRdefs.h (must be #included before adco_xc_oas.h #included)
adpdefs.h
adco_xc_oas.h (which in turn includes the following five headers)
adco_oas_api_public.h (defines all enumerated types included in the function calls described below)
*icmo.h (for Intex)
*ccmo.h (for Chasen)
*ADCO.h (for Chasen)
*IndexTypes.h (for Chasen)
Calc_RM.h (for exogenous calculations of corrective prepay multipliers using enhanced collateral information)
* Vendor files
Libraries required
Win32-> ad_oas60.dll or ad_oas7.dll or ad_oas8.dll (main oas library) + LIB
adco_IR.dll (interest rate process libraries)
adppsub.dll (mbs/arm prepay library)
adppmdl.dll (5.1, 5.2 or LDM-specific prepay library)
ad_cwrap50.dll (for Intex’s link to 5.0 prepay library)
*cmosub32.dll (Intex CMO subroutines)
adppitxs.dll (mbs/arm prepay library for Intex)
adabsitx.dll (abs prepay library for Intex)
*cmont.dll (Chasen CMO subroutines)
calcRM.dll (speed multiplier computation library) + LIB
xlflows.dll (for cashflow export, can be re-design by users)
* Vendor library
Step 1 - Get an OASHandle
An OASHandle is a pointer to a C++ object that is allocated for the security you wish to analyze. You can’t access members and methods of the class directly; you will simply need to provide this pointer to most C functions in the library. OASHandle is defined as a void* in adco_xc_oas.h.
Get an ARM or MBS handle to deal with ARM or Fixed Rate MBS for which you have the basic parameters (WAC, WAM, etc.) and want to use the ADCO cashflow engine. Active-passive decomposed (APD) MBS and HEL pass-throughs have specific handles. Active-Passive decomposed ARMs are available in prepay family 5.2 and have “unified” ARM handle.
Get an iCMO handle to deal with securities in your Intex database that will be handled by the Intex cashflow engine.
Get a cCMO handle to deal with securities in your Chasen database that will be handled by the Chasen cashflow engine.
Securities working with LDM have separate handles.
Get a secXCF handle to deal with securities whose cashflows you want to calculate yourself. You supply a callback function that returns the cashflows.
Most of the functions that take a handle as an argument also require an argument describing the type of handle. adco_oas_api_public.h defines the following enumeration:
enum sectype {
secARM=0, /*an ARM for which you will be supplying indicatives; driven by 4.3 ARM prepay model */
secMBS, /*an MBS for which you will be supplying indicatives; driven by 4.3 MBS prepay model */
secItxCMO, /*an Intex security for which you will supply Cusip or Intex Deal/Tranche name */
secXCF, /*a security for which you supply a callback function that will generate cashflows */
secChasenCMO, /*a Chasen security for which you will supply Cusip or DealID, BondID */
secMBSAPD, /*an MBS for which you will be supplying indicatives; driven by 5.1 MBS prepay model or later */
secHELAPD, /*an MBS for which you will be supplying indicatives; driven by 5.1 HEL prepay model or later */
unused1,
secARM_50, /*same as secARM, but links to 5.0 library */
unused2,
secArm_Unified, /*same as secARM, but links to 5.2 Unified model */
secMBSLDM, /*an MBS that uses LDM */
secARMLDM, /*an ARM that uses LDM */
secItxCMOLDM /*an iCMO that uses LDM with Intex */
};
Typical function fn(sectype,oashandle, args…)
For running Adjustable Rate Mortgages using ADCO cashflow engine
OASHandle adco_getARMHandle(void); - for ARM prepay model 4.3
OASHandle adco_getARM_50Handle (void); - for ARM prepay model 5.0 or 5.1 (should produce same results as 4.3)
OASHandle adco_getARM_UnifiedHandle (void); - for ARM prepay model 5.2
OASHandle adco_getARMLDMHandle(void); - from ARMs with LDM model
For running Fixed Rate Mortgages using ADCO cashflow engine
OASHandle adco_getMBSHandle(void); - for MBS prepay model 4.3
OASHandle adco_getMBSAPDHandle(void); - for MBS prepay model 5.1
OASHandle adco_getHELAPDHandle(void); - for HEL prepay model 5.1
OASHandle adco_getMBSLDMHandle(void); - for MBS with LDM model
For running Intex securities
OASHandle adco_getiCMOHandle(void); - for iCMOs with “regular” prepay models
OASHandle adco_getiCMOLDMHandle(void); - for iCMOs with LDM
For running Chasen securities
OASHandle adco_getcCMOHandle(void);
For running external cashflow securities
OASHandle adco_getXCFHandle(void);
back to top
Step 2 - Describe Environment
These functions describe the market environment - some of them have default parameters. All of these functions if called for a given handle do not need to be called again unless you want to provide different parameters. What this means, is you can reuse the same handle for a different security without having to recall these functions. For example, one can avoid recalibrating lattice (when allowed) while moving from one portfolio’s position to another.
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until you run adco_analyze again.
============================================================================================
Set the AD&Co datafile directory. Since the license key is also located in this location, it’s best to call this function immediately after getting the OASHandle so that functions that check for valid license keys don’t fail.
Optional – Default is “c:\adco\ppmodel”.
int adco_set_DavidsonDataLocation(enum sectype sec, OASHandle cp, char * ddl);
============================================================================================
Set the settlement date. Required
int adco_set_settleDT(enum sectype sec, OASHandle cp, int month, int day, int year);
Example:
rv = adco_set_settleDT(secMBS, oh, 12, 15, 2001);
============================================================================================
Set the trade date. Required
int adco_set_tradeDT(enum sectype sec, OASHandle cp, int month, int day, int year);
============================================================================================
Set up the parameters to the interest rate process. Required.
irp: which rate model do you want to use (0 for Black-Karasinski, 1 for Squared Gaussian, 2 for Hull-White, 3 for Two-Factor Gaussian)
howmanypaths: how many paths do you want to use with Monte-Carlo
shortvolatility: volatility of the short rate (will be overridden if adco_set_FitMarketVol is set to true. See below.)
meanreversion: mean reversion (will be overridden if adco_set_FitMarketmrevl is set to true. See below.)
int adco_set_PathInfo(enum sectype sec, OASHandle cp, enum irprocess irp, int howmanypaths, double shortvolatility, double meanreversion);
============================================================================================
Set 14 maturity points (used or skipped) – 1-mo, 3-mo, 6-mo, 12-mo, 2-yr, 3-yr, 4-yr, 5-yr, 7-yr, 10-yr, 15-yr, 20-yr, 25-yr, and 30-yr. Enter the maximum number of readily available, reliable points. Missing points should not be passed as 0. Use the defined constant MISSING (defined as negative 98.0 in adirdefs.h)
Required
All rates are in percent. For 5.46% enter 5.46.
int adco_set_tdTreasuryCurve(enum sectype sec, void *cp, enum enumYC pz, double yc1m, double yc3m, double yc6m, double yc1y, double yc2y, double yc3y, double yc4y, double yc5y, double yc7y, double yc10y, double yc15y, double yc20y, double yc25y, double yc30y) ;
Required
int adco_set_tdLIBORCurve(enum sectype sec, void *cp, enum enumYC pz, double yc1m, double yc3m, double yc6m, double yc1y, double yc2y, double yc3y, double yc4y, double yc5y, double yc7y, double yc10y, double yc15y, double yc20y, double yc25y, double yc30y) ;
Argument pz means par curve (couponYC) or zero curve (zeroYC).
============================================================================================
Which curve to use for OAS analysis? Optional – Default is Treasury.
int adco_set_CurveForOAS(enum sectype sec,void *cp, enum Market TorL);
============================================================================================
Do you want to use constant (flagVTS=0) or time-dependent (flagVTS = 1) volatility? Optional – Default is 0.
int adco_set_flagVTS(enum sectype sec, void *cp, int flagVTS);
============================================================================================
Do you want to use the short volatility that you set in adco_set_PathInfo (fitMarketVol = 0), or calibrate to the swaption volatilities set in
adco_set_SwapVol (fitMarketVol = 1). Optional – Default is 0.
int adco_set_FitMarketVol(enum sectype sec, void *cp, int fitMarketVol);
============================================================================================
Do you want to use the mean reversion that you set in adco_set_PathInfo (fitMarketmrev= 0), or calibrate to the swaption volatilities set in
adco_set_SwapVol (fitMarketmrev = 1). Optional – Default is 0.
int adco_set_fitMarketmrev(enum sectype sec, void *cp, int fitMarketmrev);
============================================================================================
Set the swaption vols that the IR process will calibrate to. OptionTerm is 0-13, reflecting the 14 points of the yield curve documented above.
Required if FitMarketVol is true.
int adco_set_SwapVol(enum sectype sec, void *cp, int OptionTerm, double VolMat1Y, double VolMat2Y, double VolMat10Y);
============================================================================================
Define 2 (out of possible 3) correlations to the short-rate process to be used by the two-factor Gaussian term structure model. Required if the
two-factor Gaussian term structure model was selected (irp was set to 2 in adco_set_PathInfo call); will not be used by any other model.
One out of 3 arguments should be MISSING. If none of correlations are set to MISSING, then the first two, CorrMat1Y and CorrMat2Y, will be used. Input in decimal. Example: Correlation of 23% would be entered as 0.23.
int adco_set_SwapCorr(enum sectype sec, OASHandle cp, double CorrMat1Y, double CorrMat2Y, double CorrMat10Y);
============================================================================================
How many nodes on the lattice over which to use quasi-random sampling. Optional - Default is to use quasi-random sampling over the entire lattice.
int adco_set_quasiRandomNodes(enum sectype sec, void *cp, int quasiRandomNodes);
============================================================================================
Do you what to employ short-rate fudging, i.e. additional adjustment of sampled paths to eliminate any error in static valuation? Optional – Default is 0 (NO).
int adco_set_fudgePaths(enum sectype sec, OASHandle cp, int fudgePaths);
============================================================================================
Do you what to employ antithetic reflection of Monte-Carlo paths? Optional – Default is 0 (NO).
int adco_set_ANTITHETIC(enum sectype sec, OASHandle cp, int antithetic);
============================================================================================
Define the number of shifts (up to ten) to apply to the base yield curve for scenario analysis. Optional – Default is 0.
int adco_set_shiftcnt(enum sectype sec, OASHandle cp, int sc);
============================================================================================
Set the shifts to different points of the yield curve. This function should be called repeatedly – once for each shift you defined in adco_set_shiftcnt.
int adco_set_shift (enum sectype sec, OASHandle cp, int shiftnumber, int shiftmonths, double bps1m, double bps3m, double bps6m, double bps1y, double bps2y, double bps3y, double bps4y, double bps5y, double bps7y, double bps10y, double bps15y, double bps20y, double bps25y, double bps30y);
============================================================================================
Set the value of an index as of the trade date. Indexes are defined in adco_oas_api_public.h. Since all Treasury and Libor/Swap rates are entered through the yield-curve definition functions, this function is used to set Prime and Cofi rates. The integer values of these rates are defined in adco_oas_api_public.h:
#define IDX_COFI11 28
#define IDX_PRIME 29
#define IDX_COFINA 30
Optional –Default is all 0’s.
All rates are in percent. For 5.46% enter 5.46.
int adco_set_tdIndex(enum sectype sec, OASHandle cp, int IDXname, double idxvalue);
============================================================================================
Set the value of a mortgage current coupon as of the trade date. Optional – default is all 0’s.
Mbstype is from enumerator ad_rateindex_type at the bottom of adpdefs.h
int adco_set_tdMBSCC(enum sectype sec, OASHandle cp, int mbstype, double mbsccvalue);
============================================================================================
Step 2a – Additional settings for Credit OAS
Do you want to run random HPA for Monte-Carlo with LDM? Optional – default is 0 (No).
int adco_set_ldm_randomHPI( OASHandle cp, int randomHPI)
randomHPI is flag (0 or -1).
This set-up effects LDM only. If randomHPI is set to -1, the Monte-Carlo analysis will be done under HPA rates randomized above or below the level determined by interest rates. If randomHPI is set to -1, HPA scenarios will be generated based solely on interest rates. Static and forward runs always use non-random HPAs.
back to top
============================================================================================
Step 3 - Set Security Parameters
Call the appropriate function for the handle you have. Calling any of these functions after adco_analyze marks results as dirty, i.e. you won't be able to get results until adco_analyze is run again.
int adco_set_cf_type(enum sectype sec, OASHandle cp, enum cftype cft);
This call can modify the default cashflow for both ADCO’s cashflow engine and Intex’s securities – allows you to choose to look at PrinOnly, NetIntOnly, PandNetI, servicing IO, full MSR, Loss, or IOMultiple:
enum cftype {
PandNetI=0,
PrinOnly,
NetIntOnly,
ServicingIO,
FullMSR,
Loss,
IOMultiple
};
Optional – Default is PandNetI
============================================================================================
For Adjustable rate mortgages using ADCO cashflow engine – requires OASHandle for ARM, ARM_50, ARM_Unified, or ARMLDM
All rates are in percent unless otherwise specified. For 5.46% enter 5.46.
Required
int adco_set_arm_rates( OASHandle cp, double gCoupon, double nCoupon, double servicing_in_bp, double guaranty_in_bp, double nMargin_in_bp,
double PeriodicCap_in_bp,double PeriodicFloor_in_bp, double nLifeCap, double nLifeFloor, double PayCap, double NegAmLimit, double FirstCollar_in_bp, double next_index);
PayCap - maximum percentage change at each payment reset. For 25% enter 25.
NegAmLimit - negative amortization limit as max percentage of starting balance. 112% enter 112.
Next_index – index used for next reset, if known, in %. -1 if not known.
Required
int adco_set_arm_type( OASHandle cp, int arm_type, int arm_subtype, int payfreq, int nextpay, int arm_index, int FirstIA, int IAFreq, int NextIA, int PAFreq, int NextPA, int wam, int origioper, int origterm, int origballoon, int gross_delay, int lookback, int flagTBA);
flagTBA - denotes TBA (0 - not TBA, 1 - TBA)
payfreq, IAfreq, PAfreq – frequencies of payments, interest adjustments, and pay adjustments; 1 for monthly payments, 3 for quarterly, 12 for annual…
FirstIA – months to 1st interest reset (from origination)
nextpay, NextIA, NextPA – months to next (upcoming) payment, interest reset, and payment reset, respectively.
arm_index – use the #defines in adco_oas_api_public.h starting with IDX_1MO_TREAS
origioper – number of months from origination where borrower only makes interest payments
origballoon – number of months from origination to balloon, if any (setting to 0, negative, or 360 means absence of balloon provision).
lookback – in days
For prepay model 5.1 and early:
arm_subtype – 0 for “traditional” arms (1-1 arm, cofi), 1 - for hybrid
arm_type – if arm_subtype is 0, follows armtype enumeration in adpdefs.h. If arm_subtype is 1, arm_type follows hybridtype enumeration in adpdefs.h.
For prepay model 5.2 (unified ARM) and later:
arm_type is defined by issuer, prime/subprime, first reset, and periodic reset. A 4-digit is defined as:
ISSUER * 1000 + PRIME/SUBPRIME * 100 + FIRST_RESET * 10 + PERIODIC_RESET
The components of this code are defined at the bottom of adco_oas_api_public.h:
#define ADCO_AUTO_RESET_MAP 0
#define ADCO_1MONTH_RESET 1
#define ADCO_6MONTH_RESET 2
#define ADCO_1YEAR_RESET 3
#define ADCO_3YEAR_RESET 4
#define ADCO_5YEAR_RESET 5
#define ADCO_7YEAR_RESET 6
#define ADCO_10YEAR_RESET 7
#define ADCO_ISSUER_FNMA 1
#define ADCO_ISSUER_FHLMC 2
#define ADCO_ISSUER_GNMA 3
#define ADCO_ISSUER_NONAGENCY_OTHER 4
#define ADCO_PRIME 1
#define ADCO_SUBPRIME 2
Using ADCO_AUTO_RESET_MAP in lieu of actual resets, lets the system select ARM model automatically.
For the complete list of ARM types, refer to the following table.
Table 1. ARM types
Comment: arm_type and arm_subtype are ignored by the LDM.
Additional optional ARM setups for prepay model 5.2 (moving-average index, prepay penalty, original GWAC, amortization type)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
int adco_set_arm_index_ma(OASHandle cp, int index_ma);
index_ma – length of moving average. Optional, default is 0.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
int adco_set_prepay_penalty_months( OASHandle cp, int num_months);
num_months – length of prepay penalty. Optional, default is 0.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
int adco_set_wac_at_origination( OASHandle cp, double orig_wac);
orig_wac – wac at origination; if not set, default is ARM index at origination plus gross margin. Optional
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
int adco_set_arm_amtype(enum sectype sec, void *cp, amtype _amt);
amtype can be selected from the enumerator in adco_oas_api_public.h:
enum amtype {
LevelPI,
LevelP,
CBond,
MinPmt};
In particular, MinPmt should be used for Option ARMs. Optional – default is LevelPI
============================================================================================
For Fixed Rate Mortgages using ADCO cashflow engine – requires OASHandle for MBS, MBSAPD, HELAPD, or MBSLDM
Required for secMBS, secMBAPD, secHELAPD, or MBSLDM
int adco_set_mbsindicative(OASHandle cp, double nCoupon, double servicing_in_bp, double guaranty_in_bp, int mbs_type, int wam, int origioper, int origterm, int origballoon, int gross_delay, int payfreq, int nextpay, enum amtype amt, int flagTBA);
mbstype – use loantype enumeration in adpdefs.h. A list of MBS models is found in Table 2.
Comment: mbs_type is ignored by the LDM.
Table 2. MBS types and codes
amt – amortization type; One can choose between LevelPI (level amortization) or LevelP (level principal).
flagTBA - denotes TBA (0 - not TBA, 1 - TBA)
origballoon – balloon period from origination, in months. 0 if not balloon.
origioper – loan’s IO period from origination, in months. 0 if not an IO.
Gross_delay – in days.
wam – current WAM, in months
origterm – WAM at origination, in months
nCoupon – net coupon in %.
servicing, guarantee – spreads in bps.
payfreq – payment frequency in months between payments; 1 for monthly payments, 3 for quarterly, 12 for annual…
nextpay – months till next payment.
============================================================================================
For INTEX securities - requires OASHandle for iCMO or iCMOLDM
Passing iCMO name, Deal/Bond Ids, Intex data location. Required
int adco_set_icmo(OASHandle cp, char *CDULoc, char *CDILoc, char *Cusip, char *DealID, char *BondID,
long collmode, long callflag, ICMO *icmoptr);
CDULoc, CDILoc - Intex data location
Cusip - bond’s Cusip
DealID, BondID - Intex’s combination of Deal ID and Bond ID. If Null, Cusip is regarded; if not Null, they take superiority over Cusip, which will be ignored
Collmode - collateral aggregation mode, from the following list defined in iCMO.h:
#define ICMODEAL_SEASONED_POOLS 1 /* deal with individual pools */
#define ICMODEAL_SEASONED_CLUSTERS 2 /* deal with clustered collat */
#define ICMODEAL_SEASONED_WAVG 3 /* deal with one wavg collateral */
#define ICMODEAL_SEASONED_EXPLODE 4 /* expand any Mega/Giant pools */
Callflag: - whether to regard the cleanup call or not.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
For callers making their own icmo_deal call, this function allow them to get access to the OAS function that sets tuning parameters, which are otherwise unavailable through the Intex API. Optional.
void* adco_get_aditx_tuneback(void);
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Use Intex’s enhanced dataset for prepay modeling. Optional for iCMO, ignored by iCMOLDM.
int adco_set_use_enhanced_data(enum sectype sec, void *cp, int in_use_data);
If in_use_data is not 0, AOLS, FICO, LTV, geographical data, etc. in Intex’s dataset will be employed for enhanced prepay modeling.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Passing user-defined default and loss severity assumptions. Optional for iCMO, ignored by iCMOLDM.
int adco_set_default_loss(enum sectype sec, void *cp, enum adco_default_model default_model, double * default_rate_in_percent, int default_months, double * severity_in_percent, int severity_months);
default_model – use adco_default_model enumeration in adco_oas_api_public.h:
enum adco_default_model
{
ADCO_NOT_SET = 0, /*default*/
ADCO_CDR = 1,
ADCO_SDA = 2,
ADCO_MODEL = 3
};
Default_rate_in_percent – array of doubles to use as monthly default rate. Index 0 corresponds to trade date. MUST have at least default_months elements
Default_months – number of elements in default_rate_in_percent array.
Severity_in_percent – array of doubles to use as monthly severity, in percent. MUST have at least severity_months elements.
Severity_months – number of elements in severity_in_percent array.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Passing user-defined delinquency and recovery assumptions. Optional for iCMO, ignored by iCMOLDM.
int adco_set_delinquency(enum sectype sec, void *cp, double * delinq_array, int del_months, double * del_recovery, int recov_months);
delinq_array – array of doubles to use as monthly delinquency rate. Index 0 corresponds to trade date. MUST have at least del_months elements
del_months – number of elements in delinq_array.
del_revovery – array of doubles to use as monthly severity, in percent. MUST have at least recov_months elements.
recov_months – number of elements in del_recovery array.
============================================================================================
For Chasen securities – requires OASHandle for cCMO
Required for seccCMO:
int adco_set_ccmo(OASHandle cp, char *input_path,
char *Cusip, char *ISIN, char *DealID, char *BondID, int aggregation, int call_flag, CMO_STRUCT *ccmoptr);
input_path is path to Chasen datafile directory
aggregation – 0 for not detailed, 1 for detailed. Default 0.
Call_flag – 1 for run to call. 0 for do not call. Default 0.
Set ccmoptr to NULL to load deal from datafiles
============================================================================================
For External Cashflow Securities – User must calculate cashflows
Required for XCF securities
int adco_set_xcfindicative(OASHandle cp, int gross_delay, xcfGenFn cashflowfn, void *usrptr);
cashflowfn – A pointer to a function of the form:
double xcfGenFn(FLOWS *,void *, indexFcstFn, void *)
We will call your cashflow function for each path. You can call our index forecasting function (indexFcstFn) to request paths for any rate you need to calculate the cashflow.
usrptr- Can point to any data you may need in your cashflow function. We pass it back to you each time we call your cashflow function.
============================================================================================
For Custom Rate Swap analysis
Required to run swap analysis
int adco_set_SwapInfo(enum sectype sec, OASHandle cp, double r_rate,double r_margin,double r_percap,double r_perfloor,double r_lifecap, double r_lifefloor,double p_rate,double p_margin, double p_percap,double p_perfloor,double p_lifecap,double p_lifefloor,
int r_iafreq, int r_nxtia,int r_index,int p_iafreq,int p_nxtia,int p_index,int swap_remterm);
============================================================================================
Step 3a – Compute Speed Multipliers based on enhanced collateral information
For every MBS or CMO, one can take advantage of enhanced collateral information (AKA agency disclosed data) and improve accuracy of prepayment forecasts. Functions take underpin this enhanced service within 5.1 prepayment modeling are extracted into a separate library, CalcRM.dll. Before setting refinancing and turnover tuning scales (“multiples”) one should compute them based on collateral details.
============================================================================================
Required to get and use computed tunings
void UnSetAll(void);
-Clears pre-existing inputs
============================================================================================
Each call is optional
void SetLoanType(int loantype); /* see Calc_RM.h for the loan type enumeration, e.g. 0 for FNMA30YR, 1 for FNMA15YR, etc. */
void SetLoanSize(double loansize); /* loansize in thousand */
void SetLTV(double ltv); /* ltv in % */
void SetCreditScore(double fico); /* fico in conventional units, e.g. 720 */
void SetPropertyType(double* proptype); /* proptype points to 3 doubles: % of single-family; % of multi-family; % unknown */
void SetLoanPurpose(double* loanpurp); /* loanpurp points to 3 doubles: % purchase, % refinance, %unknown */
void SetOccupancy(double* occ); /* occ points to 4 doubles: % owner, % second home, % investor, % unknown */
void SetStates(double* geo); /* geo points to 53 doubles: % for each U.S. state sorted alphabetically (DC included), % other, % unknown */
-Above calls are used to pass the enhanced data
Required to get and use computed tunings
short CalcRM(void); /* returns an error code */
double GetRefi(void); /* returns refinancing tuning */
double GetTO(void); /* returns turnover tuning */
- Above calls are used to compute and get refinancing and turnover multipliers (tunings).
============================================================================================
After calls to CalcRM(), GetRefi(), and GetTO() are made, obtained multipliers should be combined with any other tunings (physical or risk neutral) and set via calls to adco_set_FixedTuning() and adco_set_ARMTuning() – see step 5 further.
============================================================================================
Starting in Version 7.2, Risk Multipliers of agency passthroughs/cmos through Intex can be calculated automatically based on enhanced data in Intex’s mbspools database. User MUST license Intex’s mbspools database to take advantage of this, and this is only for agency deals. User must load the deal in SEASONED_POOLS or SEASONED_EXPLODE to take advantage of this. If enhanced Intex data is used, do not calculate tunings based on enhanced data using calcrm.dll. Functions dealing with this functionality are as follows.
Set whether to use Intex’s enhanced agency data. Optional for iCMO, ignored by iCMOLDM.
int adco_set_use_enhanced_data(enum sectype sec, void *cp, int in_use_data);
Set in_use_date to 1 to load and use enhanced agency data from Intex’s mbspools database or in general any data in their
POOL_INFO->pi_loanattrp->loanattr_addl_attributes linked list and states in POOL_INFO->pi_loanattrp->loanattr_geop linked list.
After running the deal, user can query us to return the weighted-average risk multipliers used on the collateral:
int adco_get_calculated_risk_multipliers(enum sectype sec, void *cp, double * in_refi, double * in_to, double * in_co, double * in_cure);
Returns 0 if risk multipliers were calculated, -1 if not. It may return 0 if run in SEASONED_WAVG mode (in which case if we loaded the deal, enhanced data was not actually used). We will fill in_refi, in_to, in_co, and in_cure with our weighted average risk multipliers.
============================================================================================
Step 3b – Set up loans’ credit data for the use by LDM
For MBSLDM and ARMLDM securities, the following calls are used to supply data (both mandatory and optional) for its use by the LDM. Calls marked as required are also used by iCMOLDM securities to supply default values for mandatory fields having missing values in Intex dataset. Categorical fields declared as double (such as occupancy, geography, etc.) can be entered using “portfolio style”, in percentages.
Setting loan size. Required.
int adco_set_ldm_loansize(OASHandle cp, double in_orig_bal, double in_cur_bal);
in_orig_bal - loan’s original balance ($)
in_cur_bal - loan’s current balance ($)
============================================================================================
Setting LTVs. Required
int adco_set_ldm_ltv (OASHandle cp, double in_orig_ltv, double in_cur_ltv, double in_orig_cum_ltv, double in_cur_cum_ltv);
in_orig_ltv - loan’s original LTV (%)
in_cur_ltv - loan’s current LTV (%)
in_orig_cum_ltv - loan’s original cumulative (combined) LTV (%)
in_cur_cum_ltv - loan’s current cumulative (combined) LTV (%)
============================================================================================
Setting lien position. Required
int adco_set_ldm_lien_position(OASHandle cp, int in_lien_position);
in_lien_position - lien position (1 or 2)
============================================================================================
Setting FICO. Required
int adco_set_ldm_fico(OASHandle cp, double in_fico);
in_fico - FICO at origination
============================================================================================
Setting loan statuses. Required
Int adco_set_ldm_current_status(OASHandle cp, double in_perc_c, double in_perc_30, double in_perc_60, double in_perc_90,
double in_perc_120, double in_perc_150, double in_perc_180, double in_perc_foreclosed, double in_perc_REO);
in_percent_c - percent of current loans
in_perc_30, etc. - percent of loans in certain delinquency status
in_perc_foreclosed - percent of loans being foreclosed
in_perc_REO - realestate owned (REO) loans
============================================================================================
Setting mortgage insurance data. Optional
int adco_set_ldm_mortgage_insurance(OASHandle cp, int in_flag_orig, int in_flag_cur, double in_percent_covered);
in_flag_orig - did loan have MI at orogination? 0 or 1
in_flag_cur - does loan have MI now? 0 or 1
in_percent_covered - if Yes, how much is covered?
============================================================================================
Setting property type. Optional
int adco_set_ldm_property_type(OASHandle cp, double in_sfr, double in_condo, double in_mh, double in_co_op, double in_pud, int in_numunits);
in_sfr - percent of single-family loans
in_condo - percent of condo loans
in_mh - percent of manufactured housing loans
in_co_op - percent of coop loans
in_pud - percent of PUD loans (planned urban development)
in_numunits - number of units (1 through 4)
============================================================================================
Setting loan purpose. Optional
Int adco_set_ldm_purpose(OASHandle cp, double in_purchase, double in_refi_cashout, double in_refi_rate, double in_construction);
in_purchase - percent of loans used to purchase homes
in_refi_cashout - percent of loans used to cashout refinance
in_refi_rate - percent of loans used to rate refinance
in_construction - percent of loans used to construct homes
============================================================================================
Setting loan occupancy. Optional
Int adco_set_ldm_occupancy(OASHandle cp, double in_owner, double in_second_home, double in_investor);
in_owner - percent of owner occupied homes
in_second_home - percent of second homes
in_investor - percent of investor homes
============================================================================================
Setting documentation information. Optional
Int adco_set_ldm_documentation(OASHandle cp, double in_full, double in_limited, double in_none);
in_full - percent of fully documented loans
in_limited - percent of loans having limited documentation
in_none - percent of loans having no documentation
============================================================================================
Setting geographical distribution. Optional
int adco_set_ldm_geography(OASHandle cp, double* in_states, int array_size, long in_zipcode, long in_msa, long in_cbsa, long in_cbsa_sub);
in_states - array of percentages per each of the US states in order
array_size - number of states, typically 55 = 51 states including DC alphabetically and PR (52), GU (53), VI (54), US (55)
If in_states pointer is NULL, the same function allows setting up data for a particular ZIP, MSA or CBSA.
back to top
Step 4 - Set Pricing
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until adco_analyze is run again
============================================================================================
Define Price, OAS, BEEM, or Yield and use that quote to produce all other results. Price and yield should be in % (99.5 not 0.995, 7.5 not 0.075) and OAS goes in as basis points.
Required
int adco_set_quote(enum sectype sec, OASHandle cp, enum qteTypes quotetype, double quotevalue);
back to top
Step 5 - Set Prepayment Model and Tunings
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until adco_analyze is run again.
============================================================================================
Define prepay model to perform all analysis. See the enum ppmodel in the adco_oas_api_public.h header file for the choices.
enum ppmodel {
ADCO_PPMODEL,
CPR,
PSA,
ABS, /* Intex only - use ICMOSPDT_VABS */
MHP, /* Intex only - use ICMOSPDT_VMHP */
HEP, /* Intex only - use ICMOSPDT_VHEP */
PPC, /* Intex only - use ICMOSPDT_VPPC */
ADCO_NONE, /* Don't search for equivalent prepay */
CPR_Vector,
PSA_Vector,
SMM_Vector
};
The prepayspeed should be entered as a % not a decimal. So, 6% CPR is 6 not 0.06, 100% PSA is 100 not 1.0, and the ADCO model default scale tuning is 1.0
Optional – Default is ADCO_PPMODEL with speed of 1.0
int adco_set_prepay(enum sectype sec, OASHandle cp, enum ppmodel prepaymodel, double prepayspeed);
============================================================================================
Some analyses return an equivalent prepayment speed, which is the speed (using a different prepay model) that would produce the same average life on the security studied. For example, assuming the prepay model has been set to ADCO_PPMODEL and the equivalent prepay model has been set to CPR, the analysis will give the single CPR that produces the same average life as the vector of speeds produced by the ADCO prepay model.
Optional – Default is CPR for secARM and similar and PSA for secMBS, seciCMO and similar
int adco_set_prepay_equiv(enum sectype sec, OASHandle cp, enum ppmodel prepaymodel);
============================================================================================
An important part of working with ADCo prepay models is programmatic tuning. Tunings can be performed on the entire modeling family (such as all fixed-rate MBS) or on a single model (such as whole loan 30-yr fixed). Such tuning sets are multiplicative.
Models 5.1 and later can be tuned “backwards and forward” or “forward only”. In the former case, prepayment parameters change from the pool’s origination and affect the past burnout process. In the latter case, the burnout occurs with an un-tuned model; tunings apply to forward time only. An example of forward-only tunings is risk-neutral tunings that stem from future prepay risk consideration. An example of forward and backward tunings is tunings demanded by enhanced data. The same-named tunings are multiplicative.
All tunings of newer models apply to older models as well – to the extent concerning common tuning factors. For example, refinancing tuning set-up by a 5.2 ARM tuning function will affect refinancing of 5.1, 5.0, and 4.3 ARM models. However, the cashout tuning set-up in the 5.2 ARM model won’t get propagated to the 4.3 model because it does not exist there. It is generally enough to tune the newer models only.
Set tunings for all ARM models
Optional default all 1.0
int adco_set_ARMTuning(enum sectype sec, OASHandle cp, double age_burnout, double base_level, double lag, double ramp_age, double rate_level);
int adco_set_Arm52Tuning(enum sectype sec, void *cp, int tuning_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
int adco_set_Arm52ModelTuning_Extra(enum sectype sec, void *cp, int arm_type, int tuning_type, double post_reset_scale, double dummy1, double dummy2, double dummy3);
New tail tuning for arm_unified handles. 3 placeholder arguments.
tuning_type allows to distinguish between “backward and forward” tuning (0) and “forward only” tuning (1).
============================================================================================
Set tunings for one ARM model (defined by model_type)
Optional default all 1.0
int adco_set_ARMModelTuning (enum sectype sec, void *cp, int model_type, double age_burnout, double base_level, double lag, double ramp_age, double rate_level);
int adco_set_HybridModelTuning(enum sectype sec, OASHandle cp, int model_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
int adco_set_Arm52ModelTuning(enum sectype sec, OASHandle cp, int arm_type, int tuning_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
int adco_set_Arm52Tuning_Extra(enum sectype sec, void *cp, int tuning_type, double post_reset_scale, double dummy1, double dummy2, double dummy3);
Tail tuning for specific 5.2 arm_types.
model_type should match an ARM model numeration found in adco_oas_api_public.h
tuning_type allows to distinguish between “backward and forward” tuning (0) and “forward only” tuning (1).
============================================================================================
Set tunings for all fixed-rate models
Optional default all 1.0
int adco_set_FixedTuning(enum sectype sec, OASHandle cp, double burnout, double curve_shape, double lag, double slide, double turnover, double refi, int ptseff);
int adco_set_Fixed51Tuning(enum sectype sec, OASHandle cp, int tuning_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
tuning_type allows to distinguish between “backward and forward” tuning (0) and “forward only” tuning (1).
============================================================================================
Set tunings for one fixed-rate model (defined by model_type)
Optional default all 1.0
int adco_set_FixedModelTuning(enum sectype sec, void *cp, int model_type, double burnout, double curve_shape, double lag, double slide, double turnover, double refi);
int adco_set_Fixed51ModelTuning(enum sectype sec, OASHandle cp, int model_type, int tuning_type, double refi, double turnover, double cashout, double cure, double aging, double sato, double cato, double lag, double slide, double burnout);
model_type should match an MBS model numeration found in adco_oas_api_public.h
tuning_type allows to distinguish between “backward and forward” tuning (0) and “forward only” tuning (1).
============================================================================================
Set some tunings for LDM and HPA models.
int adco_set_tunings_LDM(OASHandle cp, double sato_resid_tuning, double sato_tuning, double delinquency_scale, double severity_scale, double FICO_slide, double LTV_slide);
sato_resid_tuning - tuning for “SATO residual” factor (1.1 = make effect 10% stronger)
sato_tuning - tuning for the SATO factor (1.1 = make effect 10% stronger)
delinquency_scale - tuning for MDR vector (1.1 = make all MDRs 10% higher)
severity scale - tuning for the loss severity scale (1.1 = make severity 10% stronger)
FICO_slide - tuning for FICO (e.g. -60 = subtract 60 from stated FICOs)
LTV_slide - tuning for LTV (e.g. 6.0 = add 6 to stated LTVs)
int adco_set_tunings_HPI(OASHandle cp, double user_drift, double user_diffusion0);
user_drift - tuning for the long-term HPA rate (-2.0 = subtract 2% from the model’s long-term equilibrium)
user_diffusion0 - tuning for the short-term HPA rate (-2.0 = subtract 2% from the model’s “initial diffusion” rate)
back to top
============================================================================================
Step 6 - Select which calculations and pricing methods should be run
All calculations except calcoas are turned off by default 0=don't run, -1=run
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until adco_analyze is run again
============================================================================================
int adco_set_CalculateBasic(enum sectype sec, OASHandle cp, int cstatic, int forward, int scenario, int pathnum);
-Calculating static produces single vector results assuming constant rates and the use of the equivalent prepay speed from the current curve scenario
-Calculating forward produces single vector results assuming forward rates and prepay speeds from whatever model you’ve selected
-Calculating scenario produces single vector results assuming rates evolve as described by shifts you’ve input
============================================================================================
int adco_set_CalculateStaticDur(enum sectype sec, OASHandle cp, int calcspreaddur, int calcindexdur);
-Spread duration the % price change for a 1 bp change in yield
-Index duration is the % price change for a 1 bp change in inidices
============================================================================================
int adco_set_CalculateOASBasic(enum sectype sec, OASHandle cp, int calcoas, int calceffdurconvex, int calcppdur);
-Effective duration is the % price change for a 100 bp change in rates (+/- 50bps from current levels)
-Prepayment duration is the % price change for a 10% change in prepayment speed (+/- 5% from current levels)
============================================================================================
int adco_set_CalculateOASAdvanced(enum sectype sec, OASHandle cp, int calcoasdur, int calckeyrates, int calcmtgesprddur, int calcavgmoddur, int calcvega);
-OAS duration is the % price change for a 1bp change in OAS (calculated using +/- 5bps and divided by 10)
============================================================================================
int adco_set_use_backward_induction(enum sectype sec, OASHandle cp, int a)
-Setting a to –1 will use backward induction when possible (single-factor models, secMBSAPD, secHELAPD, secArm_Unified); doesn’t alter valuation of other instruments
-Setting a to 0 (default) will use Monte-Carlo or quasi-Monte-Carlo
============================================================================================
int adco_set_CalculateShockedPx(enum sectype sec, OASHandle cp, int calcshockedpx);
-Produces shocked prices; The number of shocks is calcshockedpx, shock sizes are defined by adco_set_px_shift_array function (step 6b)
============================================================================================
int adco_set_CalculateSwap(enum sectype sec, OASHandle cp, int cswap);
============================================================================================
int adco_set_CalculateARMTuningDurations(enum sectype sec, OASHandle cp, int age_burnout, int base_level, int lag, int ramp_age, int rate_level);
-Tuning durations are the % price change for a 10% change in the tuning factor (+/- 5% from current levels)
============================================================================================
int adco_set_CalculateFixedTuningDurations(enum sectype sec, OASHandle cp, int burnout, int curve_shape, int lag, int slide, int turnover, int refi);
-Tuning durations are the % price change for a 10% change in the tuning factor (+/- 5% from current levels)
============================================================================================
int adco_set_CalculateKeyRatesQuick(enum sectype sec, void *cp, int calckeyratesQ);
-Uses grouped shocks for key-rate duration/convexity analysis if calckeyratesQ = 1.
============================================================================================
int adco_set_CalculateKeyRatesStatic(enum sectype sec, void *cp, int calckeyratesC);
-Measures key-rate duration/convexity off static cashflow if calckeyratesC = 1.
============================================================================================
int adco_set_CalculateKeyRatesOld7(enum sectype sec, void *cp, int calckeyrates7);
-Measures “old-style” key-rate duration/convexity if calckeyratesC = 1. The key rates are defined by 7 old OAS model yield curve points.
============================================================================================
int adco_set_CalculateTRR(enum sectype sec, OASHandle cp, int calctrr, int trrhorizon, int trrreinvyldcurvemat, int reinvspread);
-Sets total rate of return analysis given horizon (trrhorizon) and reinvestment assumptions. Computing TRR also produces horizon price.
============================================================================================
Step 6a – Setting up Credit OAS-specific tasks (MBSLDM, ARMLDM and iCMOLDM securities)
The Credit OAS method is engaged automatically for MBSLDM, ARMLDM and iCMOLDM securities when any of the tasks require running the OAS computational engine. User can compute exposures (“durations”) to HPA short-term or long-term rates as well as few critical tunings affecting the LDM. In all set-up call, calc is the flag, shift is the step for computing.
============================================================================================
int adco_set_CalculateHpi_drift_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to the long-term HPA rate. Optional, shift default is 0.5%.
============================================================================================
int adco_set_CalculateHpi_diffusion0_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to the short-term HPA rate. Optional, shift default is 0.5%.
============================================================================================
int adco_set_CalculateFICO_slide_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to FICO. Optional.
============================================================================================
int adco_set_CalculateLTV_slide_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to LTV. Optional.
============================================================================================
int adco_set_CalculateMDR_scale_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to the monthly default rate (MDR) scale. Optional.
============================================================================================
int adco_set_CalculateSeverity_scale_durcvx(OASHandle cp, int calc, double shift);
Compute duration and convexity to the loss severity scale. Optional.
============================================================================================
Step 6b – Modify the default behavior of some of the calculations
Calling any of these functions after adco_analyze, marks results as dirty i.e. you won't be able to get results until adco_analyze is run again
All of these functions are optional and are needed only, for example, to modify the size of a shift used in one of the duration calculations
============================================================================================
int adco_set_effdur_shift(enum sectype sec, void *cp, double shift);
Sets up shift to compute Effective Duration and Convexity. Optional, default is 50 basis points.
============================================================================================
int adco_set_px_shift(enum sectype sec, void *cp, double *shift);
Sets up to 8 shocks (in basis points, pointed by shift pointer) for automated shocked prices computation. Optional.
============================================================================================
int adco_set_px_shift_array(enum sectype sec, void *cp, double *shift, int num);
Sets unlimited number of user-defined shocks (in basis points, pointed by shift pointer); num is the shock number. This shift array will be employed if adco_set_CalculateShockedPx function is called (see above). Optional.
============================================================================================
int adco_set_oasdur_shift(enum sectype sec, void *cp, double shift);
Sets up shift to compute OAS (spread) duration. Optional, default is 5 basis points.
============================================================================================
int adco_set_spreaddur_shift(enum sectype sec, void *cp, double shift);
Sets up shift to compute current coupon spread duration. Optional default is 1 basis point.
============================================================================================
int adco_set_indexdur_shift(enum sectype sec, void *cp, double shift);
Sets up shift to compute ARM index (spread) duration. Optional, default is 1 basis point.
============================================================================================
int adco_set_ppdur_shift(enum sectype sec, void *cp, double shift);
Set up shift to compute prepay scale duration. Optional, default is 5 (% of base value).
============================================================================================
int adco_set_vega_shift(enum sectype sec, void *cp, double shift);
Set up shift to compute Vega. Optional, default is 1 (relative % of the base volatility level, i.e. if base=20, then shift to 19.8 and 20.2).
============================================================================================
int adco_set_DurCvxflag(enum sectype sec, OASHandle cp, enum DurCvxBasis a);
The last argument controls how effective duration, convexity and shocked prices are computed. Setting it between 0 and 4 informs the OAS system to interpolate shocked prices and the Greeks off the pricing grid already computed in the course of backward induction, at no additional cost of computational time. If so, shift argument is interpreted as a shock in the short rate (a is 0), one-year rate (a is 1), two-year rate (a is 2), ten-year rate (a is 3), or mortgage rate (a is 4). Once shift denotes change in one selected rates, other rates are taken off the same grid, i.e. follow the internal law of the term structure model employed. Setting a to –1 (default) results in parallel shock of the entire curve performed at the cost of computational time. Optional, default is -1. It changes behavior only when backward induction is employed.
============================================================================================
Step 6c – Exporting cashflow vectors
The AD&Co OAS system allows callers to develop own callback routines that store or export cashflows generated in the course of processing. AD&Co itself has developed a small library, xlflows.dll that performs these functions.
Call this function if you've set up a callback function conforming to AD&Co’s API which will allows reading or copying cashflows and rates:
int adco_set_user_cf(enum sectype sec, OASHandle cp, void (*user_cf_function)(int a, int b, FLOWS *c, void *ptr));
user_cf_function is a callback function pointer – either a pointer to your own function or to ours
a is the “task locator”, e.g. 1 for static analysis, 2 for forward analysis, 5 for the OAS run, etc. For definitions and logic, look at adco_cfcallback in xlflows.c.
b is the path number.
FLOWS is structure defined in adco_oas_api_public.h:
typedef struct flows {
double bal[MAXMONTHS];
double flow[MAXMONTHS]; /* net flow */
double pflow[MAXMONTHS]; /* scheduled principal */
double iflow[MAXMONTHS]; /* interest */
double sflow[MAXMONTHS]; /* servicing */
double ppflow[MAXMONTHS]; /* prepayments */
double mflow[MAXMONTHS]; /* misc; used for SMMs */
double shortrt[MAXMONTHS];
double oneyrrt[MAXMONTHS];
double twoyrrt[MAXMONTHS];
double tenyrrt[MAXMONTHS];
double hpi_growth[MAXMONTHS];
double hpi_level[MAXMONTHS];
adcoDATE baldate[MAXMONTHS];
adcoDATE cfdate[MAXMONTHS];
/* added for defaults */
double cbal[MAXMONTHS]; /* current balance */
double dbal[MAXMONTHS]; /* delinquent balance */
double sbal[MAXMONTHS]; /* seriously delinquent balance */
double mdrrt[MAXMONTHS]; /* MDR rate */
double severintyrt[MAXMONTHS];/* severity rate */
double plossflow[MAXMONTHS]; /* principal loss per period */
double ilossflow[MAXMONTHS]; /* interest loss per period */
double plossDflow[MAXMONTHS];/* cum non-advanced delinquent principal */
double plossSflow[MAXMONTHS];/* cum non-advanced seriously delinquent principal */
} FLOWS;
MAXMONTHS is defined in ADIRdefs.h:
#define MAXMONTHS 372
ptr is only used if you create your own cashflow callback function. It exists in case you want to access some of your own data in your cashflow callback function. To use it, call adco_set_user_ptr(). We will always pass this pointer to the callback function (or NULL if you did not set).
=============================================================================================
int adco_set_user_ptr (enum sectype sec, void *cp, void *ptr);
ptr is a pointer to your own data structure, casted to (void *). As mentioned above, if you set this we will pass this pointer to your cashflow callback function.
Examples of user_cf_function can be found in xlflows.dll. These functions can be customized and even replaced by other developers.
void adco_cfcallback(int WhereAmI, int WhereAmIPath, FLOWS flow); /* regular format */
void adco_cfcallback_ldm(int WhereAmI, int WhereAmIPath, FLOWS flow); /* extended format showing LDM-specific results */
============================================================================================
Utilities placed in xlflows.dll that can be used to get an address of function or data and pass file name, initial balance and print header:
int adco_AddressOf(void *struc); /* for structure */
int adco_AddressCF(); /* returns address of the regular cashflow function, adco_cfcallback */
int adco_AddressCF_LDM(); /* returns address of the extended cashflow function, adco_cfcallback_ldm */
int adco_set_xl_cf(char *fn, char *pid, double bal, int headers );
fn – file name for export
pid – id of position (cusip)
bal – balance
headers – print column headers (1) or don’t (0)
============================================================================================
Below is an example of code that sets the function pointer:
The 2nd line returns a pointer to adco_cfcallback function and the 3rd line passes it to the OAS library. This function will be called each time a cashflow vector is generated. The output will be found in flows_100.txt file, which will have the standard format with headers; all cashflow components will be shown off a $1M face amount.
back to top
Step 7 - Run Analysis
Main call to run the analysis:
int adco_analyze(enum sectype sec, OASHandle cp);
Utility functions to call before adco_analyze
Call this function to cause adco_analyze to dump inputs to a file for debugging, use for input in our spreadsheet application to verify results. Pass in full path (including file name) and adco_analyze will create or append a text file containing all inputs that have been set (by default or user function calls).
Optional – default is NULL
int adco_set_dumpfile(enum sectype sec, OASHandle cp, char *filepath);
Pass NULL or empty string to turn off input dumping
Pass “stdout” to have dumping directed to stdout
Step 7a – Optimizing Portfolio Flow: re-using OAS Handle
If you run portfolio batch, deleting and initializing OAS handles for each position is possible but may be not optimal. One can create and re-use OAS handles. For example, the following call,
returns an OAS handle to an Intex CMO. After this iCMO is processed, we can re-use icmo variable for other LDM-linked CMOs. Of course, we must write a programming block that fills in necessary data for each CMO. We will delete the handle only at the end of portfolio batch:
Step 7b – Optimizing Portfolio Flow: re-using interest rate grid
Developer can optimize portfolio processing by re-using interest rate grid (calibrated to market data) when moving from one instrument to another. Some operations, such as computing key rate durations, change the grid and it can’t be re-used. In many other cases, the grid requires only initial construction. For example, computing prepay model tuning duration or spread will not alter the interest rates. If one needs to compute effective duration and convexity, it will allow re-using the grid only if the Greeks are taken directly off the valuation grid, i.e. argument a is set to 0 to 4 when adco_set_DurCvxflag is called. If the Greeks are computed in a traditional, explicit parallel-shock, style, then the grid is rebuilt each time and becomes not re-usable.
The OAS library can decide itself whether the rate grid is re-usable by analyzing the full set of tasks.
int adco_can_reUseIR(enum sectype sec, OASHandle cp);
Returns –1 if the grid is re-usable, 0 otherwise.
int adco_set_reUseIR(enum sectype sec, OASHandle cp, int a);
Set a to –1 if you plan to re-use the grid.
A typical use of these two functions is shown in the following programming flow.
Step 7c – Optimizing Portfolio Flow: Monte-Carlo seed control
For some purposes user may be interested in running each portfolio’s position using different set of paths. For example, computing losses in a large cohort of loans can be done quicker by using few paths per loan, different for each loan. This path “shuffling” will create enough variability from the portfolio stand-point. On the other hand, valuation of an asset against its hedge requires using the same set of paths.
This can be accomplished using the following functions:
Getting random initial seed.
int adco_get_init_seed(OASHandle cp, long *_init_seed);
init_seed – current seed
Setting initial seed.
int adco_set_init_seed(enum sectype sec, OASHandle cp, long seed);
seed – initial seed that will overwrite standard seed (-1) or previously reset seed
A typical use of these two functions is shown in the following programming flow.
If flag same_init_seed is not 0, the loop inside the brackets won’t be performed. If it is 0, the program will get the random seed currently used by the engine and “set” it. This operation overwrites the initial seed (typically -1) normally used by the OAS engine.
Another application of random seed is setting a test for computing Monte-Carlo accuracy. For this test, we run many Monte-Carlo pricing runs and apply the coding sample above before moving to the next run. This ensures that runs are performed using different initial seeds, and the results’ dispersion points to the valuation accuracy.
back to top
Step 8 - Getting Results
Only get the results you need and only what you asked for before calling adco_analyze
If a function gets multiple results but you don't need all, you can pass in NULL for any result you don't want
int adco_get_errmsg(enum sectype sec, OASHandle cp, char *errmsg); -Getting error message
============================================================================================
int adco_get_forwardResults(enum sectype sec, OASHandle cp, double *fwd_crv_yld,double *fwd_crv_wal, double *fwd_crv_sprd,
double *fwd_crv_equiv); -Results of forward-curve analysis
============================================================================================
int adco_get_currentResults(enum sectype sec, OASHandle cp, double *curr_crv_yld,double *curr_crv_wal, double *curr_crv_sprd,
double *curr_crv_equiv,double *curr_crv_wal_sprd); -Results of current-curve analysis
============================================================================================
int adco_get_scenarioResults(enum sectype sec, OASHandle cp, double *scenario_crv_yld,double *scenario_crv_wal,
double *scenario_crv_equiv); -Scenario analysis results
============================================================================================
int adco_get_staticResults(enum sectype sec, OASHandle cp, double *static_yld,double *static_sprd);
-Results of “static” (equivalent speed) run
============================================================================================
int adco_get_spread_duration(enum sectype sec, OASHandle cp, double *spreaddur, double *upprice, double *downprice);
-CC spread duration and shocked prices
============================================================================================
int adco_get_swap(enum sectype sec, OASHandle cp, double *rprice, double *pprice, double *diffprice);
============================================================================================
int adco_get_index_duration(enum sectype sec, OASHandle cp, double *indexdur, double *upprice, double *downprice);
-ARM index duration and shocked prices
============================================================================================
int adco_get_price(enum sectype sec, OASHandle cp, double *price, double *accrued_int); -Computed price and accrued interest
============================================================================================
int adco_get_oas(enum sectype sec, OASHandle cp, double *oas); -Computed OAS
============================================================================================
int adco_get_mod_duration(enum sectype sec, OASHandle cp, double *mod_duration); -Modified duration
============================================================================================
int adco_get_oas_duration(enum sectype sec, OASHandle cp, double *oas_duration, double *upprice, double *downprice);
-OAS duration and shocked prices
============================================================================================
int adco_get_effective_duration(enum sectype sec, OASHandle cp, double *eff_duration, double *eff_convexity, double *upprice, double *downprice); -Effective duration, convexity and shocked prices
============================================================================================
int adco_get_arm_tuning_durations(enum sectype sec, OASHandle cp, double *ramp_age_factor_dur, double *age_burnout_factor_dur,
double *base_level_factor_dur, double *rate_level_factor_dur, double *lag_factor_dur); -5 ARM prepay tuning durations
============================================================================================
int adco_get_fixed_tuning_durations(enum sectype sec, OASHandle cp, double *curve_shape_factor_dur, double *slide_factor_dur,
double *burnout_factor_dur, double *lag_factor_dur, double *turnover_factor_dur, double *refi_factor_dur); -6 MBS prepay tuning duration
============================================================================================
int adco_get_pp_duration(enum sectype sec, OASHandle cp, double *pp_duration, double *upprice, double *downprice);
-Duration to overall prepay scale and shocked prices
============================================================================================
int adco_get_vega(enum sectype sec, OASHandle cp, double *vega, double *upprice, double *downprice);
-Computed Vega and shocked prices
============================================================================================
int adco_get_kr_duration(enum sectype sec, OASHandle cp, double *yc1m, double *yc3m, double *yc6m, double *yc1y, double *yc2y,
double *yc3y, double *yc4y, double *yc5y, double *yc7y, double *yc10y, double *yc15y, double *yc20y, double *yc25y, double *yc30y);
-Full set of 14 key-rate durations
============================================================================================
int adco_get_kr_convexity(enum sectype sec, OASHandle cp, double *yc1m, double *yc3m, double *yc6m, double *yc1y, double *yc2y,
double *yc3y, double *yc4y, double *yc5y, double *yc7y, double *yc10y, double *yc15y, double *yc20y, double *yc25y, double *yc30y);
-Full set of 14 key-rate convexities
============================================================================================
int adco_get_kr_durationQuick(enum sectype sec, OASHandle cp, double *yc1M1Y, double *yc2Y3Y, double *yc4Y5Y, double *yc7Y10Y,
double *yc15Y30Y); -5 grouped key-rate durations
============================================================================================
int adco_get_kr_durationStatic(enum sectype sec, OASHandle cp, double *yc1M1Y, double *yc2Y3Y, double *yc4Y5Y, double *yc7Y10Y,
double *yc15Y30Y); -5 grouped static key-rate durations
============================================================================================
int adco_get_kr_convexityQuick(enum sectype sec, OASHandle cp, double *yc1M1Y, double *yc2Y3Y, double *yc4Y5Y, double *yc7Y10Y,
double *yc15Y30Y); -5 grouped key-rate convexities
============================================================================================
int adco_get_kr_durationOld7(enum sectype sec, void *cp, double *yc3m, double *yc6m, double *yc1y, double *yc2y, double *yc5y, double *yc10y, double *yc30y); -7 “old-style” key-rate durations
============================================================================================
int adco_get_kr_convexityOld7(enum sectype sec, void *cp, double *yc3m, double *yc6m, double *yc1y, double *yc2y, double *yc5y, double *yc10y, double *yc30y); -7 “old-style” key-rate convexities
============================================================================================
int adco_get_pxshocks(enum sectype sec, OASHandle cp, double *pxshocks); -Prices of automated parallel shocks
============================================================================================
int adco_get_trr(enum sectype sec, OASHandle cp, double *trr, double *hrzn_price, double *hrzn_wal, double *hrzn_yld, double *hrzn_flow);
-Results of Total Return Analysis
============================================================================================
int adco_get_rmseP(OASHandle cp, double *_rmseP); -Sampling accuracy of pricing (Root-Mean-Squared-Error of Price)
============================================================================================
int adco_get_rmseOAS(OASHandle cp, double *_rmseOAS); -Sampling accuracy of pricing (Root-Mean-Squared-Error of OAS)
============================================================================================
int adco_get_stdevPV *OASHandle cp, double *stdevPV); -Standard deviation of path-wise PVs
============================================================================================
int adco_get_pvalue(OASHandle cp, double *_pvalue); -Present Value
============================================================================================
int adco_get_settleDTFactor(OASHandle cp, double *_settleDTFactor); -Expected amortization factor between Trade Date and Settlement
Date
============================================================================================
int adco_get_1moSMM(OASHandle cp, double *_SMM); -Next-month SMM forecast for all rate scenarios (for PTs and ARMs)
============================================================================================
int adco_get_VMR(OASHandle cp, double *_svol, double *_mrev); -Calibrated (or entered) short-rate volatility and mean reversion
============================================================================================
int adco_get_cum_loss_default(enum sectype sec, void *cp, double * cum_loss, double * cum_default);
-Cumulative loss and default rate
============================================================================================
Special Credit OAS outputs (all LDM instruments)
int adco_get_ldm_cumloss_default(OASHandle cp, double * cumloss_static, double * cumloss_random, double * cumdefault_static,
double * cumdefault_random); - Cumulative loss and default rates, both static and averaged
============================================================================================
int adco_get_hpi_drift_durcvx(OASHandle cp, double * hpi_drift_dur, double * hpi_drift_cvx);
-Duration and convexity to the long-term HPA rate
int adco_get_hpi_diffusion0_durcvx(OASHandle cp, double * hpi_ diffusion0_dur, double * hpi_ diffusion0_cvx);
-Duration and convexity to the short-term HPA rate
============================================================================================
int adco_get_FICO_slide_durcvx(OASHandle cp, double * FICO_slide_dur, double * FICO_slide_cvx);
int adco_get_LTV_slide_durcvx(OASHandle cp, double * LTV_slide_dur, double * LTV_slide_cvx);
int adco_get_MDR_scale_durcvx(OASHandle cp, double * MDR_scale_dur, double * MDR_scale_cvx);
int adco_get_Severity_scale_durcvx(OASHandle cp, double * Severity_scale_dur, double * Severity_scale_cvx);
-Duration and convexity to LDM’s key tunings
============================================================================================
Intex Fields – For Intex CMOs only
int adco_get_itxDeal(OASHandle cp, char *dealstr); -Deal ID (given cusip)
============================================================================================
int adco_get_itxBond(OASHandle cp, char *bondstr); -Bond ID (given cusip)
============================================================================================
int adco_get_itxTrancheType(OASHandle cp, char *typestr); -Tranche type
============================================================================================
int adco_getitxBalanceAndFactor(OASHandle cp, double * bal, double *fact); -Bond’s balance and factor
============================================================================================
Int adco_get_itx_LatestCDU(OASHandle cp, long *cdudate); -CDU date
============================================================================================
int adco_get_itxBalanceAndFactor_Collateral(OASHandle cp, double *balance_Collateral, double *factor_Collateral);
-Collateral balance and factor
============================================================================================
int adco_get_itxSupportInfo(OASHandle cp, double *support_orig, double *support_cur);
-Bond’s original and current supports (%)
============================================================================================
int adco_get_itxMisc(OASHandle cp, int *deal_age, char *rating ); -Deal’s average age and bond’s original rating
============================================================================================
int adco_get_itxCurrentRatings(OASHandle cp, char *curr_rating); -Bond’s current rating
============================================================================================
int adco_get_itxDelInfo(OASHandle cp, double *writedown, double *collatloss, double *delinquency);
-Accumulated bond’s writedown, collateral loss, and delinquency composition: [0] = current, [1] = 30-day,….[8] = ROE, [9] = bankrupt
============================================================================================
int adco_get_itxPercentLSKnown(OASHandle cp, double *calculated_ls_known);
-Percentage of loans having known loan sizes
============================================================================================
Chasen Fields – For Chasen CMOs only
int adco_get_chasenDeal(OASHandle cp, char * dealstr); -Sets dealstr to name of loaded deal
============================================================================================
int adco_get_chasenBond(OASHandle cp, char * bondstr); -Sets bondstr to name of loaded bond
============================================================================================
int adco_get_chasenBalanceAndFactor(OASHandle cp, double * bal, double * fact);
-Sets balance, factor as of date from which Chasen loaded deal
back to top
Step 9 - Free Handle
Call this function when you are through with the handle to make sure all memory is freed up. Do not use the handle after calling this function!
int adco_free_OASHandle(enum sectype sec, OASHandle cp);
============================================================================================
Testing applications
Calling samples for the OAS library are presented in mbsoas6.test.c (MBS), armoas7test.c (ARMs), icmooastest.cpp (iCMOs).
For instruments with user-defined cashflow engines, see xcfoas5test.c.
For processing and exporting cashflow vectors, see xlflows.c.