Skip to content

usage-guide.md

Latest commit

 

History

History
105 lines (72 loc) · 5.6 KB

usage-guide.md

File metadata and controls

105 lines (72 loc) · 5.6 KB
Raw

Usage Guide

Step 1: Gather your source material

Collect everything you have about the microscope. More is better — the AI can ignore irrelevant pages but can't invent missing specs. Typical sources:

  • Publications (methods section + supplementary): Best source for hardware specs, optical layout, performance numbers. Upload the PDF.
  • Supplementary materials: Often contain detailed component lists, optical diagrams, filter configurations.
  • User protocols / SOPs: Turn-on/off procedures, sample preparation, alignment guides. Even hand-written notes or photos of labeled switches.
  • Software config files: ImSwitch JSON, MicroManager cfg, ZEN experiment files, NIS acquisition settings. These contain exact device wiring, DAQ channels, default settings.
  • Calibration data: Power calibration CSVs, PSF measurements, flatfield images, bead calibration data.
  • Manufacturer manuals: Laser specs, camera datasheets, stage specs. Useful for max power, travel range, frame rate limits.
  • Tribal knowledge: Anything not written down — common problems, tips, things that break. Write these as brief notes and include them.

The Google Form is a good way to systematically collect this information from lab members before starting.

Step 2: Generate the KB — three waves

The generation prompt is split into three waves. Only hardware.yaml needs to be generated alone; everything else can be generated in parallel. This brings the total number of AI interactions from ~12 down to 3.

Why three waves and not one? All files reference hardware components by ID (e.g. laser_640_cw, cam_sCMOS). If IDs are established first in hardware.yaml and pasted into the Wave 2 prompt, the AI can generate all remaining files consistently in a single pass. The _index.yaml is generated last because it summarises the final content of everything else.

Wave 1 — hardware.yaml

Open a new AI session (Claude, ChatGPT, etc.). Paste the Wave 1 prompt from generation-prompt.md and attach all your source documents.

Tell the AI: "Here are my source documents for a [describe your microscope]. Please classify the system first, then generate hardware.yaml."

Review the output carefully — check every model number, wavelength, and ID against your actual system. This file is the foundation; errors here propagate everywhere.

Wave 2 — all other files in parallel

In the same AI session (so source documents stay in context), paste the Wave 2 prompt and insert your approved hardware.yaml where indicated.

The AI will output all remaining files (concepts, calibrations, software_config, procedures, safety, troubleshooting, limits, recipes, faq, _changelog) in a single response. Review each one, ask for corrections, then save them all.

Wave 3 — _index.yaml

Still in the same session, paste the short Wave 3 prompt. The AI generates _index.yaml based on everything produced so far.

Step 3: Review and test

After all three waves:

  1. YAML validation — run all files through a parser:

    python3 -c "
import yaml, os
for f in sorted(os.listdir('.')):
    if f.endswith('.yaml'):
        try:
            yaml.safe_load(open(f)); print(f'  OK  {f}')
        except Exception as e:
            print(f'FAIL  {f} -- {e}')
"

  2. ID cross-reference check — do IDs in calibrations.yaml and recipes.yaml match those in hardware.yaml? A quick grep helps:

    grep -h "laser:" recipes.yaml calibrations.yaml | sort -u
grep -h "id:" hardware.yaml | sort -u

  3. Smoke test — give the KB to an AI with the system prompt and ask:

    • "Can I image [X] with this system?"
    • "What's wrong if I see [symptom]?"
    • "Walk me through startup."
    • "Is my laser power safe for live cells?"

    If answers are wrong or the AI says "I don't know" for something clearly in the KB, there is a gap to fill.

Step 4: Maintain it

  • Update when hardware changes, calibrations are redone, or new protocols are developed
  • Log changes in _changelog.yaml
  • Re-run the smoke test after significant updates
  • A stale KB gives confident wrong answers — worse than no KB

Quick Start for Your Next Microscope

  1. Fork or copy the setups/etsted_knowledge_base/ folder as a template
  2. Delete system-specific content but keep the file structure
  3. Fill in the Google Form or gather source documents directly
  4. Run the three-wave generation workflow
  5. Review, validate, smoke-test

Tips for Multi-System Facilities

  • Standardize IDs: Use laser_<wavelength>nm_<type> for lasers, <modality>_<target> for recipes, etc. — consistent naming across all your KBs makes facility-wide tools easier to build.
  • Version control: Put KBs in a git repository. YAML diffs cleanly and you get a full audit trail of hardware and protocol changes.
  • Shared concepts: The concepts.yaml entry for "confocal" is mostly the same across your Zeiss, Nikon, and Leica confocals — fork and adapt only the system-specific paragraph.
  • Shared safety boilerplate: General laser safety, electrical safety, and biosafety rules are largely shared. Keep a _shared_safety.yaml and reference it.
  • Automate calibration ingestion: Write a script that reads calibration CSVs and updates calibrations.yaml entries automatically after each calibration run.
  • Facility-wide FAQ: Maintain a cross-system FAQ covering questions like "Which system should I use for [X]?" — this sits outside individual KBs and references them.