118 lines
6.4 KiB
Markdown
118 lines
6.4 KiB
Markdown
# Protocol Bicorder
|
|
|
|
The Protocol Bicorder is a diagnostic tool for the study of protocols. It allows a human or machine user to evaluate protocol characteristics along a series of gradients between opposing terms.
|
|
|
|
The name is a tribute to the [tricorder](https://en.wikipedia.org/wiki/Tricorder), a fictional device in the Star Trek universe that the characters can use to obtain all manner of empirical data about their surroundings. Apparently there was a bicorder in [a 2009 Star Trek comic](https://memory-beta.fandom.com/wiki/Bicorder). The name was [also used](https://hackaday.io/project/11851-bicorder) for a sensing device created by Alex Haim at the 2016 Bay Area Maker Faire.
|
|
|
|
## Using the bicorder
|
|
|
|
These instructions can guide humans or machines in utilizing the bicorder. The bicorder, foundationally, consists of a JSON file that may or may not have values filled out. A completed bicorder file should have all or most of the values filled out. Filling out the values can be done either manually, through editing the JSON file directly, or by using software that takes input in other forms and translates it to a JSON reading. These instructions are for editing the JSON file directly, but they should be useful with other interfaces as well.
|
|
|
|
The bicorder consists of three components:
|
|
|
|
* `metadata` about the current reading, including information about the protocol and its analyst
|
|
* `diagnostic` composed of sets of gradients that measure the analyst's interpretation of the protocol
|
|
* `analysis` that interprets the diagnostic data
|
|
|
|
A `shortform` option is available for a version of the bicorder that uses a smaller number of gradients. These are the gradients that, according to the [`analysis/`](analysis/), are the most salient and predictive of the values of other gradients.
|
|
|
|
### Metadata
|
|
|
|
There are several pieces of information that provide metadata about a given reading with the bicorder. More details about the data formats for each input are provided in `bicorder.schema.json`.
|
|
|
|
* `protocol`: Name of the protocol or brief description
|
|
* `analyst`: Name or other identifier of the analyst conducting the diagnostic
|
|
* `standpoint`: Describe, even at some length, the relationship between the analyst and the protocol, including any relevant context that could affect the diagnostic readings
|
|
* `timestamp`: A timestamp for when the reading occurred
|
|
* `shortform`: Indicates whether the diagnostic was conducted using the abbreviated list of gradients
|
|
|
|
### Diagnostic
|
|
|
|
To carry out the diagnostic, the analyst should consider the protocol from the perspective of one of the `gradients` at a time. The gradients invite the analyst to determine where the protocol lies between two terms.
|
|
|
|
This is inevitably an interpretive exercise, but do your best to identify the most accurate `value`, with `1` being closest to `term_left` and `9` being closest to `term_right`.
|
|
|
|
Choosing a `value` in the middle, such as `5`, can mean "a bit of both." Leaving the gradient `value` as `null` means "not applicable."
|
|
|
|
There is a `notes` field for the analyst to add additional context or explanation.
|
|
|
|
The `shortform` boolean indicates whether this gradient is included in the abbreviated version of the bicorder.
|
|
|
|
### Analysis
|
|
|
|
The Analysis part of the bicorder is meant to be automated. Its `value` fields are based on calculations on the above gradients. Each analysis is also a gradient, whose value is derived from the gradients in the diagnostic. Each analysis has an `instructions` field that explains how to produce the `value` for that analysis.
|
|
|
|
## Interfaces
|
|
|
|
There are several ways to use the bicorder.
|
|
|
|
### Machine-readable JSON
|
|
|
|
The most basic way to use the bicorder is to simply edit a JSON file:
|
|
|
|
* Make a copy of `bicorder.json` with an appropriate file-name
|
|
* Fill out the `metadata` and `diagnostic` sections appropriately
|
|
* Based on the `diagnostic` inputs, process the `analysis` values following the relevant `instructions` fields
|
|
|
|
### ASCII chart
|
|
|
|
An ASCII chart can be generated from a JSON file. This can be useful as a human-readable output, or as a human-usable way to carry out a diagnostic. The included Python script works both for the `bicorder.json` template or for a completed JSON file with values added.
|
|
|
|
Usage:
|
|
|
|
`python ascii_bicorder.py [INPUT.json] [OUTPUT.txt]`
|
|
|
|
An example output file from the template is maintained at `bicorder.txt`.
|
|
|
|
Each gradient is represented this way:
|
|
|
|
```
|
|
term_left < [|||||||||] > term_right
|
|
```
|
|
|
|
To mark a gradient in a particular place, it is represented with a `#` like this:
|
|
|
|
```
|
|
term_left < [||||#||||] > term_right
|
|
```
|
|
|
|
|
|
### Human-usable web app
|
|
|
|
A progressive web app (PWA) for using the bicorder is located in [`bicorder-app/`](bicorder-app).
|
|
|
|
|
|
## Synthetic data analysis
|
|
|
|
The bicorder repository is equipped with a synthetic dataset of protocols, as well as AI-generated analysis of that dataset.
|
|
|
|
See [`analysis/`](analysis/) for complete documentation and materials.
|
|
|
|
|
|
<!---
|
|
### Gradient citations
|
|
|
|
- implicit / explicit
|
|
- See Pomerantz book on Standards, p. 16: de facto and de jure
|
|
- Social / technical
|
|
- From Primavera's Protocol Art talk
|
|
- Kafka / Whitehead (Asparouhva)
|
|
- Measuring the extent to which the protocol imposes burdens on users as opposed to freeing them to focus on something else
|
|
- flock / swarm (Fernández)
|
|
- Measuring the degree of variation as opposed to uniformity the protocol enables
|
|
- soft / hard (Stark)
|
|
- dead / alive (Friend; Alston et al.; Walch)
|
|
- related especially to whether it is actively performed)
|
|
- insufficient / sufficient (Kittel & Shorin; Rao et al.)
|
|
- Measuring the extent to which the protocol as such solves the problems it is designed to solve, or whether it relies on external mechanisms
|
|
- tense / crystallized
|
|
- Marc-Antoine Parent countered the idea of "engineered arguments" (which assume ongoing tension) with "crystallized arguments" (which memorialize past tensions that are no longer active). For instance, English is tense, Arabic numerals are crystallized.
|
|
--->
|
|
|
|
|
|
## Authorship and licensing
|
|
|
|
Initiated by [Nathan Schneider](https://nathanschneider.info) and available for use under the [Hippocratic License](https://firstdonoharm.dev/) (do no harm!). Several AI assistants, local and remote, were utilized in developing this tool.
|
|
|
|
[](https://firstdonoharm.dev/version/3/0/core.html)
|