# SipDecode

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Release: 4.6  •  5.0  •  5.1  •  5.2  •  5.3  •  5.4  •  6.0  •  6.1  •  6.2  •  6.3

## SipDecode(xml, resultIndex, localIndexName, useDll)

Decodes an xml-encoded Stochastic Information Packet (SIP), which is a compressed textual encoding of a vector of numbers, usually denoting a stochastic sampling of an uncertainty quantity. SIPs are introduced and described in the following article:

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

The xml text must adhere to the DISTTM 1.0 Distribution String] encoding standard. The xml encoding will usually be created originally by the SipEncode function.

## Parameters

«xml»
The DISTTM 1.0 Distribution String xml text.
«resultIndex»
(Optional) An existing index that to be used to index the result. Defaults to Run.
«localIndexName»
(Optional) A name to be used for a local index when you desire the function to create a local index to index the result.
«useDll»
(optional) boolean value, see below.

It is an error to specify both «resultIndex» and «localIndexName» -- you must specify at most one. If both are omitted, the result is indexed by Run.

If the «resultIndex» is longer than the encoded sample, the final entries are padded with Null values. If the «resultIndex» is shorter than the encoded sample, the sample is truncated at the index length.

If you specify a «localIndexName» (textual identifier) but not a «resultIndex», the function will create a local index with a length matching the number of data in the encoded xml, having the indicated name.

## Examples

The following produces an encoding of a normal distribution. In this example, SampleSize = 100:

SipEncode(Normal(0, 1)) →
'<dist name="Ch1" avg="-2.664535259100376e-017" min="-2.575829303549574e+000" max="2.575829303549574e+000" count="100" type="Double">eqqts1hPiUJhL6ozR2tXJdZicgBniT1JH8qGnCSjXNSSFW3NlznFgJVwT8Y5PYqha7Z0IBmhKK87UnztaJV/PUpZobudJbzBQqd4c3dcVMRpoHvKjAiO91l1sb8AAILUZn0vSaRLgGt1MkXibMGNepO6Y1JLwTSnLC5V959cEOJ5jkRMh+tI6IVTfhNd7mJCPyhgHIGdcxCbELaYkH92Rl8GWpiEEU53MhZbt1ONbtlw8jcGUlFqq00gpxlv5WRhQPFlb1EOmRgA</dist>'

Here the same sample is encoded with less precision:

SipEncode(Normal(0, 1), type: "Single") →
'<dist name="Ch1" avg="4.440892098500626e-018" min="-2.575829303549574e+000" max="2.575829303549574e+000" count="100" type="Single">bmhcrXW8WmyEWLFHiW1rjE6kfzdqgHmGZZXWp51VmSSqckt6VJ8sNHiKTyg7glNRfkpzYEIfh2+NgZvFSACXdz8vGUV7Z2G2PTJZfFuhY11kX2ZiOVJARFeSkHaTTWkQcHSFjgAA</dist>'

Boolean (Bernoulli) data can be encoded without any loss of precision:

 SipEncode(Bernoulli(0.6), type: "Binary") →
'<dist name="Ch2" count="100" type="Binary">iDsLu1tvq2id47/4cAAA</dist>'

Here we demonstrate the loss of finite precision:

Index I := 1..5
Variable A := Table(I)(7.2, 1.3, 9.8, 0.3, 5.0)
Variable B := SipEncode(A, I, type: "Single")
B →
'<dist name="A" avg="4.72e+000" min="3.000e-001" max="9.8e+000" count="5" type="Single">qBjnAHIA</dist>'
SipDecode(B, I) → Array(I, [7.207, 1.301, 9.8, 0.3, 4.992])

For comparison, a type = "Double" encoding of the same 5 numbers matches the original data to 5 digits or precision in this example.

## Using an External DLL

This function, and SipEncode, 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/6.2

If used with ADE, replace the above hive path with the "HKLM/.../ADE/6.2" hive.

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 ExpandDst(wchar_t* xmlInput, double** sampleValues, int* size)

If you have a DLL configured as described here, SipDecode will call the exported function ExpandDst to perform the decoding 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 ExpandDst, the «useDll» parameter is ignored and Analytica's built-in implementation is always used. When the DLL function is used, errors involving mal-formed xml are not reported, and the result returned may contain arbitrary (garbage) values.

## History

Introduced in Analytica 4.2.3.

## See Also

Comments

You are not allowed to post comments.