Investment Studio > Objects > Grid > Customizing > Record fields > Types

Every Grid object cell has two fundamental properties: a data type and a value. Loosely speaking, the cell's data type determines the interpretation of the cell's value. The same value can mean different things, and be displayed quite differently, in cells with different data types.

Data type topics:

Lookup or immediate?
Immediate data types
Understanding lookup cells
Lookup record fields
Lookup data types

Lookup or immediate?

Data types, and hence cell types, can be broadly classified as either lookup or immediate:

An immediate cell is self-contained: it knows its own value, and what you see in the Grid display is a representation of that value. If user input is allowed, a new value which you enter into the cell becomes the cell's new value.
A lookup cell is not self-contained: what it contains is a reference to an entry in a table. The table is created and maintained behind the scene by Investment Studio. Multiple lookup cells can (and ofter do) refer to the same table entry.

What you see in the Grid display is a representation of the value in the referenced table entry. If user input is allowed, a new value which you enter into the cell becomes the new value of the referenced table entry. The cell's own content remains unchanged.

Values of all types can be converted into each other.

Immediate data types

Internally, Grid objects only know about three immediate data types, the ones used in expressions: integers, floats (real numbers) and strings (text). All other immediate types are derived from one of these, and essentially amount to a different representation (i.e. a different way to display and edit) of the same kind of data.

Integer types:

Data type Description
Integer A whole number ranging from -2147483648 (-2^31) to 2147483647 (2^31 - 1).

In Grid cells, integer formatting (in particular, the choice of thousands separator) depends on the computer's regional settings.

Color An integer interpreted as a color code.

The three lowest bytes represent an RGB value. The lowest byte is red color intensity: hex 000000FF means pure red. The next byte is green color intensity: hex 0000FF00 means pure green. The next byte is blue color intensity: hex 00FF0000 means pure blue. 0 means black, hex 00FFFFFF means white.

The highest order byte is a palette selector. If it's 0, the closest matching color in the system palette is used. If it's 1, the closest matching color in the currently realized palette is used. If it's 2, the nearest color in the logical palette of the current device context is used.

Unless you have special reasons to do so, use the system palette (highest order byte = 0).

Image An integer interpreted as a bitmap number.

The bitmaps are loaded at startup from the <BMPS> directory. Each bitmap is stored in a separate file named after the bitmap's number.

Example: if an image cell's value is 1, the cell will display the image loaded at startup from file "1.BMP". If there is no such bitmap, the cell will look like an ordinary integer cell.

Bitmap numbers must be equal to or greater than 0. Negative numbers are therefore always displayed as plain integers.

Bitmap files can be created and edited with any image editor, e.g. Windows Paint. A few rules to keep in mind when you do so:

Bitmap numbers, and hence file names, must be contiguous. Bitmap loading starts at "0.BMP" and terminates at the first name gap.

Example: if you have a file called "8.BMP" and a file called "10.BMP", but no file called "9.BMP", no file after "8.BMP" will be loaded, and there will be no bitmap number 10.

Upon loading, all bitmaps are cropped to 16 x 16 bit squares.
In each bitmap, the color of the bottom left pixel determines the transparent color in the entire bitmap (the cell background will show through pixels with this color code).
Boolean An integer interpreted as a logical value.

0 means FALSE, anything else means TRUE.

If present, bitmaps number 0 and 1 are used to represent the two boolean values (see above).

Float types:

Data type Description
Float A floating point number with 15–16 significant digits, ranging from 5.0 x 10^–324 to 1.7 x 10^308 (positive or negative).

In Grid cells, float formatting (in particular, the choice of thousands and decimal separators) depends on the computer's regional settings.

Date A float interpreted as a date.

The integral part is the number of whole days that have passed since December 30, 1899. The fractional part (ignored for display / editing purposes) is the fraction of a day that has elapsed since midnight.

Time A float interpreted as a time.

The integral part (ignored for display / editing purposes) is the number of whole days that have passed since December 30, 1899. The fractional part is the fraction of a day that has elapsed since midnight.

String types:

Data type Description
String A string of characters. No length limitations (apart from available memory).
Currency A three-character currency code.

Currency codes are not arbitrary. Investment Studio uses the currency quote files in the <FOREX> directory for currency conversion, e.g. from individual asset values expressed in EUR to a total portfolio value expressed in USD. The choice of quote file depends on the source and target currency codes. For instance, to convert from EUR to USD, the file "EURtoUSD.CSV" would be used.

For this to work, you should always use currency codes consistent with the filenames in the <FOREX> directory. By default, they are based on ISO codes (two-letter country code + one-letter currency code).

Understanding lookup cells

When working with a lookup cell, you must distinguish between the cell value (a reference to an entry in a table) and the referenced value.

The cell value is always an integer.

The referenced value is always one of the immediate data types (which one depends on the cell's type).

All type names starting with the words "Portfolio", "Asset" or "Transaction" denote lookup data types:
"Portfolio" data types are references to entries in Investment Studio's internal table of loaded portfolios.
"Asset" data types are references to entries in Investment Studio's internal table of assets in the selected portfolio.
"Transaction" data types are references to entries in Investment Studio's internal table of transactions in the selected portfolio.

A good way to explore these concepts is to experiment a bit with the simple spreadsheet in the Macros view.

Example: Let's say that you have loaded exactly one portfolio, called "US indices". Investment Studio's internal table of loaded portfolios will then contain only one entry. Entries in this table happen to be numbered 0 and up, so our lone entry will be the 0th one.

Go to the spreadsheet in the Macros view and create an integer cell with value 0:

This is a simple, immediate cell. Now, with the cell selected, choose "Portfolio name" in the list of data types:

A1 is now a lookup cell. The value displayed in the grid is the referenced value, i.e. the name of the 0th entry in Investment Studio's internal table of loaded portfolios.

You can select the other "Portfolio" data types to see the selected portfolio's symbol and currency. When you do so, the cell value remains 0, as you can see in the edit box to the right of the data type selector.

If you use a lookup cell in an expression, you will get its cell value, NOT its referenced value! As far as expressions are concerned, lookup cells are just immediate integer cells.
Example: To continue the previous example, try the trivial expression "=A1":

Cell A1 is displaying the referenced value ("US indices") but the expression in cell B1 ("=A1") is evidently getting A1's cell value, 0.

At first sight, this may seem strange. What good is a lookup cell if expressions (and hence other cells) can't get to its referenced value? The answer is that they can, by using lookup functions.

Example: The function PORTFOLIO_NAME(n) returns the name of entry number n in Investment Studio's internal table of loaded portfolios.

Again continuing the previous example, cell B1 contains the value of lookup cell A1 (= 0), so PORTFOLIO_NAME(B1) will return the name of the portfolio referenced by A1 (the 0th entry in Investment Studio's internal table of loaded portfolios):

PORTFOLIO_NAME(A1) would return the same value: "PORTFOLIO_NAME(A1)" is an expression; in expressions, a lookup cell returns its cell value, so A1 would evaluate to 0 and the expression would again reduce to PORTFOLIO_NAME(0).

Lookup record fields

In the examples above, we used a single lookup cell with an explicit value. This was for illustrative purposes only. We considered the special case of only one loaded portfolio; with only one entry in Investment Studio's internal table of loaded portfolios, it was safe to assume that it would be the 0th entry.

Since all tables referenced by lookup cells are automatically created and managed behind the scene, it is generally not safe to make such assumptions. Table entries may be reshuffled at any time, and their number need not (and usually will not) coincide with the display order of records in any particular view.

In general, it is therefore not safe to use explicit lookup values in your expressions. The normal situation is instead for lookup cells to get their values directly from the Grid object.

To that end, every Grid object's record definition should contain at least one lookup field of the appropriate type (portfolio lookup in the Portfolios view, quote lookup in the Assets and Quotes views, transaction lookup in the Transactions view). When a Grid object is populated with data records, all instances of these fields (i.e. all corresponding cells) are automatically set to appropriate cell values. Expressions in immediate record fields can then access record-specific data by feeding the symbols of these lookup field(s) to lookup functions.

Consider for instance the Grid object in the Portfolios view. It maintains a record for each loaded portfolio. Within each record, all "Portfolio" type cells ("Portfolio name", "Portfolio symbol", "Portfolio currency") always have the same value (i.e. they all point to the same entry in Investment Studio's internal table of loaded portfolios). Each record is guaranteed to correspond to a unique entry in the portfolio table. None of this requires any action on your part; it's all done automatically. All you have to worry about is the record definition.

Example: In the Grid's record field editor, a minimal portfolio record table may look like this:

The first field (highlighted) is a lookup type ("Portfolio name"). In each record instance, the value of the corresponding cell will be a reference to a unique entry in the portfolio table. In other words, it will uniquely identify the record's portfolio. The cell will display the portfolio's name, and since this is an input field (red bakground!) the user will also be able to edit it.

The first field's symbol ("_PORTFOLIO") allows other cells in the same record to use portfolio lookup functions to get more information about the record's portfolio. There is an example of this in the second field (a plain float), where the lookup function PORTFOLIO_NAV is used to get the portfolio's Net Asset Value.

The Grid objects in the other views work quite analogously.

In the Assets and Quotes views, each record corresponds to an entry in Investment Studio's internal table of assets in the selected portfolio; the entry can be accessed from the record cells using any of the "Asset" lookup types.

In the Transactions view, each record corresponds to an entry in Investment Studio's internal table of transactions in the selected portfolio; the entry can be accessed from the record cells using any of the "Transaction" lookup types.

Lookup data types

Portfolio types provide access to Investment Studio's internal table of loaded portfolios:

Portfolio type Portfolio property (displayed in cell)
Portfolio name A string containing a free-format description of the portfolio.

Portfolio names are primarily used for display purposes. The name of the selected portfolio is shown in the main window's title bar and over the portfolio page of Notes objects (in the absence of a name, the portfolio symbol is used instead). Portfolio names are also often used in the header of the portfolio view's Grid object and in Chart or Graph texts.

Portfolio symbol A (usually short) string containing a symbol for the portfolio.

Portfolio symbols can be used to access the properties of specific portfolios in Charts and Graphs. They can also be associated with Browser favorites.

All these uses require each portfolio to have a unique symbol. Since it can be a hassle to change symbols later, when you've used them in many places, choose each symbol with care, then stick with it.

Portfolio currency The currency code for the portfolio's reference currency (used to compute and display the portfolio's value).

Be careful! If one or more asset currencies can't be converted to the portfolio currency (typically because the required conversion file is missing) no quantity depending on the portfolio's value can be computed.

Asset types provide access to Investment Studio's internal table of assets in the selected portfolio:

Asset type Asset property (displayed in cell)
Asset name A string containing a free-format description of the asset.

Asset names are primarily used for display purposes. The name of the selected asset is shown over the asset page of Notes objects (in the absence of a name, the asset symbol is used instead). Asset names are also often used in the headers of asset and quote Grids, and in Chart or Graph texts.

Asset symbol A (usually short) string containing a symbol for the asset.

Asset symbols are crucial for the construction of systems. They can also be used to access the properties of specific assets in Charts and Graphs, and they can be associated with Browser favorites.

All these uses require each asset to have a symbol which is unique within its portfolio. Since it can be a hassle to change symbols later, when you've used them in many places, choose each symbol with care, then stick with it.

Asset currency The currency code for the currency in which the asset is quoted.

Be careful! If one or more asset currencies can't be converted to the portfolio currency (typically because the required conversion file is missing) no quantity depending on the portfolio's value can be computed.

Asset stocks % A float specifying the stock component of the asset's value, expressed as a percentage.

If the asset is a stock or a stock fund, this property should be set to 100. If the asset contains no stock component, this property should be set to 0. It's also possible to have mixed assets (e.g. a "balanced" fund with both fixed income and equity components) with values between 0 and 100.

Modifying this property will cause the asset's cash component percentage to be adjusted so that the sum of all component percentages remains 100.

This property is used to compute the portfolio's overall asset allocation. Note that it's enough for a single asset's allocation to be unspecified for the whole portfolio's allocation to be unknown.

Asset bonds % A float specifying the bond component of the asset's value, expressed as a percentage.

If the asset is a bond or a bond fund, this property should be set to 100. If the asset contains no bond component, this property should be set to 0. It's also possible to have mixed assets (e.g. a "balanced" fund with both fixed income and equity components) with values between 0 and 100.

Modifying this property will cause the asset's cash component percentage to be adjusted so that the sum of all component percentages remains 100.

This property is used to compute the portfolio's overall asset allocation. Note that it's enough for a single asset's allocation to be unspecified for the whole portfolio's allocation to be unknown.

Asset cash % A float specifying the cash component of the asset's value, expressed as a percentage.

If the asset is all cash (including short-term fixed income vehicles like money market funds), this property should be set to 100. If the asset contains no cash component, this property should be set to 0. It's also possible to have mixed assets (e.g. a "balanced" fund with cash, bond and equity components) with values between 0 and 100.

Modifying this property will cause the asset's "other" component percentage to be adjusted so that the sum of all component percentages remains 100.

This property is used to compute the portfolio's overall asset allocation. Note that it's enough for a single asset's allocation to be unspecified for the whole portfolio's allocation to be unknown.

Asset other % A float specifying any residual component (not cash, not bonds, not stocks) of the asset's value, expressed as a percentage.

What goes into the "other" category is largely up to you. Possible candidates are natural resources, gold and real estate.

Modifying this property will cause the asset's cash component percentage to be adjusted so that the sum of all component percentages remains 100.

This property is used to compute the portfolio's overall asset allocation. Note that it's enough for a single asset's allocation to be unspecified for the whole portfolio's allocation to be unknown.

Transaction types provide access to Investment Studio's internal table of transactions in the selected portfolio:

Transaction type Transaction property (displayed in cell)
Transaction number A read-only integer > 0 which uniquely identifies the transaction within the portfolio.

The Grid object in the Transactions view automatically provides a sequential number whenever a new transaction is entered, and it can renumber transactions by display order. Direct user input is not allowed.

Transaction date The date of the transaction.

This property is crucial to the computation of the asset's (and hence of the portfolio's) value.

In order to know what an asset is worth on any given date, it's necessary to know exactly what flowed in and out of it up to that date. So be careful when entering transaction dates: a single mistake here can yield very misleading asset and portfolio values.

Transaction time The time of day of the transaction.

When working with daily data, this property has little importance. By default, it's set to 12:00:00 AM, causing the asset value to reflect the transaction from the start of the transaction date.

Transaction units A float specifying the number of asset units involved in the transaction.

A negative number denotes a flow out of the asset. A positive number denotes a flow into the asset.

An asset unit is the quantity of an asset used to quote the asset's price. For instance, if the asset is a stock, the asset unit is a share of that stock. If the asset is a USD bank account, the asset unit is one USD.

This property is crucial to the computation of the asset's quantity and value, and hence of the portfolio's composition and value.

Transaction value A float specifying the principal value of the transaction (i.e. the value excluding transaction costs).

A negative number denotes a value flow out of the asset. A positive number denotes a value flow into the asset.

This property is crucial to the computation of the asset's (and hence of the portfolio's) investment performance.

The investment in an asset is computed as the sum of principal value and fees.
Transaction fees A float specifying the cost of the transaction.

You may think of this property as "the bank's cut" (or the broker's, or the tax man's, depending on the context).

When a transaction involves your paying more than the value of the asset units you acquired, or your being paid less than the value of the asset units you sold, the difference should go into this property as a positive number.

When a transaction involves you getting paid more than the value of the asset units you sold, or your paying less than the value of the asset units you acquired, the difference should go into this property as a negative number.

Example: You purchase 100 shares of stock at 5 USD per share. The number of transaction units is 100, so the transaction value is 5 x 100 = 500 USD. But the actual cost to you is 502.50 USD, so you enter 2.50 USD (positive!) for transaction fees.

Example: The bank pays 10 USD of interest into your USD account. Assuming that you have made the obvious choice of asset currency for your USD bank account, the number of transaction units = the transaction value = 10. Since the bank is paying you 10 USD more than the value of the asset units you sold (in this case, none at all) the fees for this transaction are -10 USD (negative!).

Keeping track of transaction fees is important if you want to get a true picture of your investment's performance, especially when comparing assets with different fee structures. All built-in functions for performance evaluation take transaction fees into account.

The investment in an asset is computed as the sum of principal value and fees.
Transaction flag A string value.

A transaction flag is an arbitrary string field which can be set automatically by trading system rules or manually in the Transactions view, and read using the asset_flag and portfolio_flags functions. Its interpretation is up to you. For instance, it can be used to keep track of state changes in a trading system, or to give the Portfolios or Assets views advance warning about the trading system's intents for tomorrow, before the quotes needed to book actual transactions become available.

Transaction soft A boolean value specifying whether the transaction is "soft".

Soft transactions can be automatically deleted and overwritten upon system execution. Transactions generated by system rules are always soft.

By default, manually entered transactions are not soft, so they won't be modified upon system execution.