Protocolbot
6ae77a4f9b
Strategy: key runs by bicorder version (not date), promote shared inputs
to analysis/data/, and stamp every output with its bicorder_version so
a re-run on edited gradients is self-describing.
Data layout:
- Promote the shared protocol inputs out of the run directory:
analysis/data/protocols_edited.csv (411 cleaned protocols)
analysis/data/protocols_raw.csv (774 un-cleaned entries)
- Rename the v1.2.6 synthetic run:
data/synthetic_20251116/ -> data/synthetic_1.2.6/
so the bicorder version it was scored against is explicit (gradient
structure changes between versions make date-based names ambiguous)
Provenance:
- bicorder_analyze.py now writes a 'bicorder_version' column into every
output readings.csv, recording which gradient structure produced it
Scripts:
- Update the real code defaults that pointed at the old run path
(bicorder_classifier.py, classify_readings.py, sync_readings.sh,
compare_analyses.py) and refresh docstring/help examples
- Remove a stray committed __pycache__/.pyc
Docs: analysis/README.md documents the new layout + how to add a run;
WORKFLOW.md, TEST_COMMANDS.md, INTEGRATION_GUIDE.md paths updated.
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:
metadataabout the current reading, including information about the protocol and its analystdiagnosticcomposed of sets of gradients that measure the analyst's interpretation of the protocolanalysisthat 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 descriptionanalyst: Name or other identifier of the analyst conducting the diagnosticstandpoint: Describe, even at some length, the relationship between the analyst and the protocol, including any relevant context that could affect the diagnostic readingstimestamp: A timestamp for when the reading occurredshortform: 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.jsonwith an appropriate file-name - Fill out the
metadataanddiagnosticsections appropriately - Based on the
diagnosticinputs, process theanalysisvalues following the relevantinstructionsfields
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.
