Systematic Trading research and development, with a flavour of Trend Following
Au.Tra.Sy blog – Automated trading System header image 2

Unfair Advantage API: Retrieve Back-Adjusted Contracts function

October 2nd, 2009 · No Comments · Backtest, Development, Futures, Software

Let’s have fun with the CSI UA API!Let's have fun with the CSI UA API

CSI main API document (word doc) is accessible publicly online from their document page along with other docs including the full 300 page manual (great for getting a feel of the app).

Pivotal API function

This post will focus on is the API function to retrieve Back-Adjusted Contracts from the Unfair Advantage database.
As the last post on Continuous Contract options showed, there are multiple choices available and these all translate to parameters to the API function: RetrieveBackAdjustedContract2. This is what I consider to be the meat of the API: it queries the proprietary UA database and applies the concatenation algorithms to produce a continuous contract.

27 Parameters!

Yes… that function’s behaviour is driven by the value of 27 properties or variables. There are actually 14 “Session” properties and another 13 variables passed to the function. The aim of these parameters is to reproduce exactly all the options covered in the previous post… and then some.

My own doc

Because I found the CSI doc not ideal (you have to keep flipping back and forth for a description of all 27 parameters) I decided to re-write my own “cheat-sheet” documentation for the RetrieveBackAdjustedContract2 API function.
The rest of this post is that document – formatted into HTML by M$ Word (so please excuse any formatting mishaps). The document contains 2 parts: the UA session properties and the function variables. Hope this helps.
You can also download the document in the RTF format.
CSI UA API: RetrieveBackAdjustedContract2 function Cheat-Sheet

Stay tuned for the next episode, where I will share a sample code using the function above to extract a list of Futures contracts. This should illustrate how to use all these parameters.

The document:

FUNCTION: RetrieveBackAdjustedContract2


FUNCTION: RetrieveBackAdjustedContract2


IncludeSaturdays:“True” if Saturday data is desired.

IncludeHolidays: If NOT TRUE, than all data records reflect actual trading. If TRUE, then weekdays on which there is no record are recorded with a day of week value of 8 and no price information.

OnHolidaysUsePreviousData: If 1, then the previous days data is copied with the Date and DayOfWeek changed.

OnHolidaysUseCloseOnly: If 1, then the price values are set to the previous close and the volumes are set to zero.

ShowDecimalPoint: controls whether prices are listed as integers or as strings representing the number (see for details – ConversionFactor.)

ConversionFactor: Most CSI data formats present price values as integers, according to the CSI format found in the “WSJ Price/CSI Price” column of the CSI Commodity Data Fact Sheet. Please note the CSI price and the WSJ price, and when dealing with the CSI price values, consult the conversion factor column on the right hand side of each page. A conversion factor of -1, for example, reflects that the final digit is in eighths. A CSI value of 3746 for wheat would be equivalent to 374 and 6/8, or 374-3/4..)

        +6             Move decimal point 6 places left
        +5             Move decimal point 5 places left
        +4             Move decimal point 4 places left
        +3             Move decimal point 3 places left
        +2             Move decimal point 2 places left
        +1             Move decimal point 1 place left
         0             Leave number as it is
        -1             Terminal digit is in eighths
        -2             Terminal 2 digits are in 16ths
        -3             Terminal 2 digits are in 32nds
        -4             Terminal 2 digits are in 64ths
        -5             Terminal 3 digits are in 128ths
        -6             Terminal 3 digits are in 256ths
        -7             Terminal 3 digits are in 32nds & 1/2 32nds.

DetrendMethod: Indicates how and whether to detrend data being retrieved. Detendingtakes two prices, the first close (of the earliest date) in the series and a pivot price. The pivot price may either be the close of the last day for the second-to-the-last contract or the close of the second-to-the-last day on file. All days within the range have an amount added so that afterward the first close in the series matches the pivot price. Here are the valid values.



Detrend By Second Contract


Not Detrended


Detrend by Second Day


FillInCashPrices: Determines whether to retrieve Cash Prices. The “cash” price may be an actual cash price, it may be lagged cash, which would only have been known the day after, or it may simply be the nearest future contract.

ApplyCommodityAdjustments: “True” to have adjustments made for unit of contract specification changes.

UseAlternateBackAdjuster: If 1, then the Alternate Back Adjuster is used for all series, (default is the non-portfolio chart option value in UA). Notice that the standard back adjuster is fundamentally backward looking while the alternate back adjuster is fundamentally forward-looking which is why the Proportional accumulation is different.

RaiseNegBackAdjustSeries: controls whether UA automatically adds the smallest number of thousands of points to bring the back adjuster series into the non-negative domain

NumDaysConfirmation: selects how many consecutive volume and/or open interest roll signals are required before the algorithm rolls. For the Standard Back Adjuster which views the market backward in time from the most recent to the most distant, this argument is ignored and has an effective value of 1. For the Nth Nearest Future and the Alternate Back Adjuster, a value of at least 1 is required.

CloseOutOfRangeAdjustmentMethod: When a series settles outside of the daily range some software required the data to be “adjusted”. The following are allowed:

typedef enum




} CloseOutOfRangeAdjustmentMethodType;

RoundToTick: controls whether UA rounds values to the nearest tick

UseTradeableTick: if RoundToTick is TRUE, determines whether the settlement price should be rounded as per the exchange or the same way as the other prices.

AggregateVolAs, AggregateOiAs, and AggregateCashAs: When making weekly, monthly, quarterly, or annual Documents, how are these fields to be treated:






AggregateDateAsLastRecord: TRUE if weekly, monthly, quarterly, and annual Documents should end on the date of the last data available. For a weekly file generated after the close on Tuesday, the records would be Friday, Friday, …, Friday, Tuesday. If not TRUE, all records are on the same day of the week.

AggregateDayOfWeekAs: If AggregateDateAsLastRecord is not TRUE, then what day of the week should the aggregate data be assigned to:









MarketNumber: integer assigned by CSI to identify a contract underlying.

rollLogicType: Identifies the logic to be used in deciding when to ignore a near contract:

RollOnOpenInterest (-1)

RollOnVolume (-2)

RollOnOpenInterestAndVolume (-4)

RollOnOpenInterestOrVolume (-3)

RollOnDayRelativeToStartOfMonth (-5)

RollOnDayRelativeToEndOfMonth (-6)

rollWhen: time delay between when the day’s prices are published and when the day’s volume and open interest are published is handled. (There is almost always a one-day delay.)



Nth Nearest Rolls

Alt Back Adjust

Std Back Adjust





















DayOfMonthToRoll and MonthsPriorToRoll: used when the rollLogicType is a date roll to determine when the roll takes place.

accumulationMethod: Determines whether to adjust backward or forward.






(Deprecated)A multiplicative ratio factor is applied rather than an additive factor. Because of the backward viewing perspective, the standard back adjuster brings the data to the current day contract level whereas because of the forward viewing perspective, the alternate back adjuster brings the data to the earliest contract level. Prices cannot fall into negative territory in the past with this option.



Adds adjustments to bring historical data to the current day contract level. This option can result in negative price readings into the past.



Subtracts adjustments to bring historical data to the earliest contract level. Because of the effects of inflation, by using this option, prices are less likely to move negative into the future.

rollDeltaType: identifies which contract values are used to measure the carrying charges for which the data is being adjusted.






Simulates rolling by an on-the-open spread order.



Simulates rolling by an on-the-close spread order.



Simulates an exit order on the close and an enter order on the next open.



Mathematically equivalent to OpenToOpen.



Mathematically equivalent to CloseToClose, except that the Alternate back adjuster requires one fewer days of existence for an explicit CloseToClose.

ValidMonths: Selects which delivery months to consider. The ValidMonths argument must be a string of 12 characters, one character for each month. Each character determines whether contracts deliverable in that month are included. A contract is included if there is a ‘V’ (for valid) in that position. A value of ‘I’ for invalid causes exclusion.

GenerateForward: If the UseAlternateBackAdjuster is zero then GenerateFoward will have no effect. TRUE or 1 to begin with the earliest data and step day-by-day to the current day. FLASE or 0 to begin with the current contract and prepend earlier data.

RollAtLeastNDaysBeforeExpiration: definition a bit shaky…

causes a roll to happen if necessary to avoid getting too close to expiration.

If you are not generating forward (zero), then the standard back adjuster is applied. If the RollAtLeastNDaysBeforeExpiration is greater than zero, then the rollLogicType is overridden so that rolls happen based only on expiration. (Like a roll relative to month end.).

StartDate and EndDate: These two long integers allow the user to limit the retrieval to a date range. Use the values -1, -1 or 0 ,0 if you want the full history available. Can significantly improve performance, but for forward generated Nth Nearest Future and Back-Adjusted contracts can result in different contract choices.

ProportionalAdjustment: If the ProportionalAdjustment parameter is non-zero, then the Backward or Forward adjustments are applied by a multiplicative ratio factor rather than an additive factor. When the standard back adjuster is applied, only Backward adjustments can be applied proportionally.

Note: You can receive a 10% discount on CSI data subscriptions (use coupon code LIBERTY)

Related Posts with Thumbnails

Tags: ····

No Comments so far ↓

There are no comments yet...Kick things off by filling out the form below.

Leave a Comment