protocol-bicorder/README.md

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, 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. The name was also used 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/, 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/.

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/ for complete documentation and materials.

Authorship and licensing

Initiated by Nathan Schneider and available for use under the Hippocratic License (do no harm!). Several AI assistants, local and remote, were utilized in developing this tool.