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.

## Interest Threshold Parameters

**Synonyms:**
- `postrin-interest-percentage`
- `postrin-interest-pc`
- `postrin-interest-threshold`
- `postrin-interest-th` (abbreviation for `-threshold`)
- `interest-threshold`
- `postrin-interest`
- `negtrin-interest-percentage`
- `negtrin-interest-pc`
- `negtrin-interest-threshold`
- `negtrin-interest-th` (abbreviation for `-threshold`)
- `negtrin-interest`

**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
- Parameters with the `-percentage` or `-pc` suffix are interpreted as percentages (0-100)
- Parameters with the `-threshold` or `-th` suffix are interpreted as absolute threshold values
- The `-threshold` suffix can be abbreviated as `-th`
- If multiple synonyms are specified, the lattermost (last encountered)
  synonym takes precedence
- Separate thresholds can be specified for postrin and negtrin using the
  respective prefixes

**Example:**
```
+idev|my-device|pcloudIntensity(postrin-interest-percentage=50|negtrin-interest-threshold=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

**Synonyms:**
- `postrin-distraction-threshold`
- `distraction-threshold`
- `postrin-distraction`
- `negtrin-distraction-threshold`
- `negtrin-distraction`

**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 value is a numeric threshold that determines when stencils are
  constructed and delivered with DISTRACTION importance
- If multiple synonyms are specified, the lattermost (last encountered)
  synonym takes precedence
- Separate thresholds can be specified for postrin and negtrin using the
  respective prefixes

**Example:**
```
+idev|my-device|pcloudIntensity(negtrin-distraction-threshold=60|postrin-distraction-threshold=40)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
```

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

## Stupefying Threshold Parameters (Postrin)

**Synonyms:**
- `postrin-stupefaction-threshold`
- `postrin-stupefaction`
- `stupefaction-threshold`
- `postrin-stupefying`
- `stupefaction`
- `stupefying`

**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 value is a numeric threshold that determines when stencils are
  constructed and delivered with STUPEFYING importance
- These parameters apply only to postrin data (positive intrinsic
  stimuli)
- If multiple synonyms are specified, the lattermost (last encountered)
  synonym takes precedence

**Example:**
```
+idev|my-device|pcloudIntensity(postrin-stupefying=80)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
```

This example sets the stupefying threshold to 80 for postrins.

## Intolerable Threshold Parameters (Negtrin)

**Synonyms:**
- `negtrin-intolerable-threshold`
- `negtrin-intolerable`
- `intolerable-threshold`
- `intolerable`

**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 value is a numeric threshold that determines when stencils are
  constructed and delivered with INTOLERABLE importance
- These parameters apply only to negtrin data (negative intrinsic
  stimuli)
- If multiple synonyms are specified, the lattermost (last encountered)
  synonym takes precedence

**Example:**
```
+idev|my-device|pcloudIntensity(negtrin-intolerable=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.