salmanoff/docs/design/intrin-thresholds.md

Intrinsic Threshold Parameters

Overview

This document describes quale-iface-api-params that control threshold values for constructing stencils and delivering them to SMO via postrinInd/negtrinInd with different importance levels. These parameters allow the stimbuff API library to determine when to construct a stencil for postrin or negtrin data and present it to SMO with appropriate importance classifications.

Unit Suffix Rules

All intrinsic threshold params must include an explicit unit suffix. These suffix families are not synonyms with each other; they select different units:

• -percentage/-pc
• -threshold/-thresh/-thr

Parameters with the -percentage or -pc suffix take a percentage in the range 0-100.

Parameters with the -threshold, -thresh, or -thr suffix take an absolute number. The interpretation of that number, and the underlying unit, is defined by the API library itself.

Users must specify only one unit-suffixed parameter per targeted intrinsic classification. If multiple unit-suffixed variants targeting the same classification are supplied anyway, the lattermost supplied parameter takes precedence.

Shorthand params without a unit suffix are not permitted anymore. The following forms are invalid because they all omit units:

• [<pos|neg>trin-]<interest|distraction|stupef<action|ying>|intolerable>

For stupefying and intolerable thresholds specifically, the postrin- or negtrin- prefix may be omitted when the intended intrinsic is already implied by the classification itself. Even in those cases, a unit suffix is still mandatory.

Interest Threshold Parameters

Parameter forms:

• postrin-interest-<percentage|pc|threshold|thresh|thr>
• negtrin-interest-<percentage|pc|threshold|thresh|thr>

Description: These parameters denote the value at which the stimbuff API library should construct a stencil for the postrin or negtrin that it delivers for this DAPSpec's qualeIfaceApi's stimfeat, and present it to SMO via postrinInd/negtrinInd with the "importance" argument set to "INTERESTING".

Specification:

• The parameter is specified as part of the quale-iface-api-params in the DAP specification
• The unit suffix rules from the top of this document apply here too
• Separate thresholds can be specified for postrin and negtrin using the respective prefixes

Example:

+idev|my-device|pcloudIntensity(postrin-interest-percentage=50|negtrin-interest-thr=30)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39

This example sets the interest threshold to 50% for postrins (percentage-based) and 30 for negtrins (absolute threshold value).

Distraction Threshold Parameters

Parameter forms:

• postrin-distraction-<percentage|pc|threshold|thresh|thr>
• negtrin-distraction-<percentage|pc|threshold|thresh|thr>

Description: These parameters denote the value at which the stimbuff API library ought to construct a stencil and deliver it to SMO via negtrinInd/postrinInd with the importance argument set to "DISTRACTION".

Specification:

• The parameter is specified as part of the quale-iface-api-params in the DAP specification
• The unit suffix rules from the top of this document apply here too
• Separate thresholds can be specified for postrin and negtrin using the respective prefixes

Example:

+idev|my-device|pcloudIntensity(negtrin-distraction-thr=60|postrin-distraction-thr=40)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39

This example sets the distraction threshold to 60 for negtrins and 40 for postrins.

Stupefying Threshold Parameters (Postrin)

Parameter forms:

• [postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>
• [postrin-]stupefying-<percentage|pc|threshold|thresh|thr>

Description: These parameters denote the value at which the stimbuff API library ought to construct a stencil and deliver it to SMO via postrinInd with the importance argument set to "STUPEFYING".

Specification:

• The parameter is specified as part of the quale-iface-api-params in the DAP specification
• The unit suffix rules from the top of this document apply here too
• These parameters apply only to postrin data (positive intrinsic stimuli)

Example:

+idev|my-device|pcloudIntensity(stupefying-thr=80)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39

This example sets the stupefying threshold to 80 for postrins.

Intolerable Threshold Parameters (Negtrin)

Parameter forms:

• [negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>

Description: These parameters denote the value at which the stimbuff API library ought to construct a stencil and deliver it to SMO via negtrinInd with the importance argument set to "INTOLERABLE".

Specification:

• The parameter is specified as part of the quale-iface-api-params in the DAP specification
• The unit suffix rules from the top of this document apply here too
• These parameters apply only to negtrin data (negative intrinsic stimuli)

Example:

+idev|my-device|pcloudIntensity(intolerable-thr=90)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39

This example sets the intolerable threshold to 90 for negtrins.

Notes

The way that SMO handles these importance levels is not yet fully worked out. For postrins, the distinction between "interesting" vs "stupefying" is somewhat reasonably intuitively clear, but how that meaning is given in code has not been worked out yet. Similarly, for negtrins, the distinctions between "interesting" vs "distracting" vs "intolerable" are not entirely clear in terms of how their handling will impose meaningful differences that will give meaning to their distinctions.

These parameters provide the mechanism for the stimbuff API library to classify and deliver intrinsic stimuli with appropriate importance levels, but the downstream processing and behavioral implications of these classifications within SMO remain to be fully defined.