Skip to content

Skyparlour — scientific tutorial

Released in FCC v1.2.1. You are running controlled experiments and want to instrument Skyparlour with reproducible measurements. This tutorial shows how to capture inputs and outputs, version the artifacts, and feed the results into the v1.2.1 vocabulary contract path so downstream Athenium / Mnemosyne consumers can ingest them.

What this subsystem does

The Skyparlour subsystem provides the Sky-Parlour Visualization Bridge that transforms EventBus events into D3-friendly payloads (force graphs, Sankey diagrams, chord diagrams, heatmaps) for the React frontend.

The implementation lives at src/fcc/protocols/visualization_bridge.py. It ships with FCC core (no separate install needed) and is exercised by:

Focus persona: HEX — Hypothesis Explorer

We anchor this scientific-track tutorial on HEX because that's the persona most relevant to a scientific use of the Skyparlour subsystem.

from fcc._resources import get_personas_dir
from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
persona = registry.get("HEX")
print(persona.name)
print(persona.role_title)
print(persona.riscear.role)

Capturing reproducible inputs and outputs

The scientific use case for skyparlour centers on measurement reproducibility. Every run should:

  1. Pin its inputs (event data, query parameters, FAIR scoring criteria)
  2. Capture its outputs (broadcast manifests, query results, D3 payloads, FAIR scores)
  3. Record the FCC version, plugin versions, and any installed sister-project versions
  4. Persist the full trace for replay

Wiring into the v1.2.1 vocabulary contract

If you produce artifacts that match an Athenium or Mnemosyne shape, the v1.2.1 vocabulary loader can verify the cross-project entity resolution path:

from fcc.objectmodel.vocabulary_loader import VocabularyMappingLoader

loader = VocabularyMappingLoader()
store = loader.from_data_dir()

# If your artifacts are mnemosyne-shaped:
from fcc_mnemosyne_plugin import MnemosyneVocabularyProvider
result = loader.verify_against_plugin(store, MnemosyneVocabularyProvider())
assert result.is_clean, f"Vocabulary contract broken: {result}"

This is the experimentally verifiable contract that lets your downstream consumers (analytics in Athenium, retention in Mnemosyne) trust the artifacts you produce.

What you learned

  • Mock mode + version pinning + trace capture = reproducible measurement
  • The vocabulary contract is the bridge between FCC and downstream sister projects
  • v1.2.1's loader fails fast when the contract drifts

Verification

Run the focused test suite for this subsystem:

pytest tests/test_visualization_bridge.py -v

All tests should pass on a clean v1.2.1 install. If they don't, check that you have the optional deps from the [full] extras group:

pip install -e ".[full]"

Next steps