SipEncode

SipEncode( x, i, name, type, origin, useDll )

Encodes a Stochastic Information Packet (SIP) as XML, using the DIST^TM 1.0 Distribution String] standard introduced in:

Sam Savage, Stefan Scholtes and Daniel Zweidler (Feb 2006), "Probability Management - Part 1", OR/MS Today 33:1.

Basically, this takes a 1-D vector of numbers, most commonly an uncertainty sample indexed by Run, and returns an xml text value that encodes the vector of numbers in a compressed textual form. The compression is lossy (except that the «type»="Binary" case is non-lossy when x is 0 or 1 everywhere). A decompressed version can be recovered from the xml text using SipDecode. The decompressed version will be very close to the original, and will preserve the average value.

Parameters

«x»

A vector of numbers indexed by «i», or by Run if «i» is omitted.

«i»

(optional) The index of «x». Defaults to Run.

«name»

(optional) The name of the distribution. Defaults to the name of «x» when «x» is an identifier, otherwise defaults to the name of the variable being evaluated when «x» is a general expression.

«type»

(optional) The precision type, either "Single", "Double", or "Binary" (or "S", "D", or "B"), which determines how precisely the values are encoded in the compression. A "Single" type uses about 1 1/3 characters per number, "Double" uses about 2 2/3 characters per number and preserves the original numbers with greater precision than "Single". "Binary" encodes bernoulli outcomes (true/false), encoding 6 binary values per character.

«origin»

(optional) Documentation included in the xml specifying the source for the data or assessment.

«useDll»

(optional) See "Using an external DLL to compute" below.

Uses

SipEncode is useful when you want to store a vector of numeric data in an external database. An entire 1-D vector can be stored in a single textual database record field in a compressed form. This may save space in the database, relative to storing every number explicitly, and can be extremely convenient to use. When using in this fashion, remember that the compression is lossy. If your data is a Monte Carlo sample, where uncertainties were already assessed, the loss of precision is likely to be insignificant; hence, its use for storing Monte Carlo samples is compelling.

Using an External DLL

This function, and SipDecode, can be used without the use of any external DLL. However, Analytica's built-in compression implementation can be replaced by one implemented in an external DLL. The hook is here to allow researchers within Sam Savage's research group to utilize their own implementation, or to change the implementation or encoding standard should the need arise.

To use an external DLL, you must set a registry setting to point to the DLL file. To do this, run regedit.exe and navigate to the following hive:

HKCU/Software/Lumina Decision Systems/Analytica/4.2 (if using Analytica 32-bit)

HKCU/Software/Lumina Decision Systems/Analytica/4.2x64 (if using Analytica 64-bit)

Then use New String Value to create a value named Sip.dll and specify a complete file path to the DLL file as the value. If you are using Analytica 32-bit, you must use a 32-bit DLL, likewise, if you are using Analytica 64-bit, your DLL must be compiled as 64-bit. The DLL must export a function with the following prototype, which is then called by this function:

void __stdcall CompressDst(double sip[], int sipSize, wchar_t* sipName, DstType, 
                                 wchar_t* dstOrigin, wchar_t* outputStr)

If you have a DLL configured as described here, SipEncode will call the exported function CompressDst to perform the encoding by default. You can force the use of Analytica's built-in implementation by specifying the «useDll» parameter as false. If a DLL is not configured, the specified DLL file not found, or the DLL found does not export a function named CompressDst, the «useDll» parameter is ignored and Analytica's built-in implementation is always used.

See Also

• SipDecode