Interop idea: hand-off from a research-thinking plugin. From theory → starting codebook, from questions → extraction templates

[maxonamission]

Hi @chrisgrieser, first off, thanks for Quadro. I like it :-)

I have worked with atlas.ti but found it too expensive for my intermittent use.

Reason to post this question: I maintain Parallax, a plugin that helps me through the thinking phase before data collection: problem exploration, choosing theoretical lenses, graded literature synthesis, challenging your framing, and a methodological audit trail. All as plain markdown artefacts. Parallax ends roughly where Quadro begins: its research-design step proposes study designs, and when that design is qualitative, the user currently starts their QDA setup from scratch.

I'm exploring a file-level hand-off (no runtime dependency in either direction. We'd only generate and read plain files, and we'd point users to your separate-vault recommendation rather than scaffolding inside their thinking vault):

1. Theoretical lenses → starting codebook: generate code files from the user's chosen lenses (e.g. Codes/social-capital/weak-ties.md), as an a-priori/deductive starting set next to their grounded coding.
2. Research questions → extraction templates: generate Template.md files per extraction type (e.g. Extractions/interview-claims/Template.md) whose fields derive from the sharpened sub-questions.
3. QDA process → methodological account: read progress.json (counts, saturation ratio) and the codebook structure to include the analysis phase in Parallax's deterministic audit trail.
4. Later, maybe: read coded data back as an "own empirical data" evidence tier the user can confront their recorded beliefs with.

A few questions before I build against your conventions:

• Code files: does Quadro expect anything specific in a code file to recognize it (front-matter keys, naming), or is "a markdown file under Codes/" sufficient? Anything an externally generated code file typically gets wrong?
• Templates: any constraints on Template.md front-matter I should know about?
• progress.json: do you consider its fields stable enough for third parties to read, or is it internal and subject to change without notice?
• Stability in general: any planned changes to the folder or block-ID conventions I should design against? I'd pin my assumptions to a Quadro version and read tolerantly either way.

To be clear: this needs nothing from you beyond a sanity check. I'm absolutely happy to document the pairing from my side. And if the hand-off direction itself seems off from a QDA-methodology standpoint (e.g. you'd argue a-priori codebooks undermine grounded coding), I'd genuinely like to hear that too.

Kind regards,

Max

[chrisgrieser]

Thank you for the kind words. Other plugins or even apps interacting with Quadro is exactly what I was intended to enable with the pure plain-text storage of data via Quadro, so I very much welcome your approach.

Code files: does Quadro expect anything specific in a code file to recognize it (front-matter keys, naming), or is "a markdown file under Codes/" sufficient? Anything an externally generated code file typically gets wrong?

The files do not necessarily have to sit in Codes/, the folder can be configured in the Quadro settings, and Codes/ is just the default. Same thing with the extraction folder /Extractions. All Quadro plugin settings are stored in .obsidian/plugins/quadro/data.json, which you might simply read to determine the folder you need.

Otherwise, Code files are kept quite simple, with code description being the only key created by Quadro by default, and users can create the Template.md file in the Codes folder, which will prefill frontmatter keys.

Creating code files externally should work with no problem by simply creating a markdown file in the code folder (or one of its subfolders).

Quadro was also intentionally written in a very modular manner, so to make it easier for third parties to either contribute or interact with Quadro. The code file creation logic is mostly isolated in the file create-new-code-file.ts, which you can check out for details.

Templates: any constraints on Template.md front-matter I should know about?

Nope, for Code Files, only the frontmatter is read, the rest of the Template.md is ignored.

However, the Template.md for Extraction files, the keys extraction-date and extraction-source are reserved for Quadro.

progress.json: do you consider its fields stable enough for third parties to read, or is it internal and subject to change without notice?

The keys are kept stable, not only for third parties, but also for Quadro itself being able to read them (which is the reason some of them don't have the most intuitive name, but simply the name I came up first… 😅). So you should be able to read the file without any issues.

Stability in general: any planned changes to the folder or block-ID conventions I should design against? I'd pin my assumptions to a Quadro version and read tolerantly either way.

block-id conventions could potentially change, with the reason being that they are just are not interacted much from Quadro's side. Quadro simply uses the datetime to ensure that the ids are unique (and otherwise also have some "meaning" other than just being an id). For new features in the future they might change, but right now I don't see a reason to do so.

Nonetheless, Quadro is mostly stable, and the code features basically finished. For reasons of backwards compatibility with existing projects, I will mostly refrain from changing any conventions used.

I also adhere to proper commit message conventions, so if there are any updates to Quadro, you'll be able to see via the commit log whether the changes are relevant to your plugin. Though as mentioned, breaking changes should be unlikely at this point.

---

As mentioned, one motivation for Quadro was to make things interoperable with other plugins instead of making one giant QUAL app trying to do everything. So if you are done with creating interactions of your plugin with Quadro, feel free to drop a message here and I'll gladly link Parallax in the Quadro readme.

[maxonamission]

Cool, thanks for your elaborate response! This is exactly what I needed, especially the data.json pointer and the reserved extraction keys. I'll build against these conventions and will report back here when I think it is ready to ship.

[maxonamission]

Hi Chris,

Took a few days but here is what I feel is a solid first attempt :-)

Thanks again first of all for the detailed answers earlier!

Everything you confirmed is baked in and pinned to Quadro v1.29.0:

• Theoretical lenses → starting codebook. the command "Quadro - export codebook (from lenses)" writes one code file per adopted lens, with code description as the only front-matter key, names sanitized the way create-new-code-file.ts does it. Your data.json pointer paid off: when the export runs inside a vault that has Quadro, the reader resolves the configured folder names from .obsidian/plugins/quadro/data.json instead of assuming the defaults.
• Research questions → extraction templates. the command "Quadro - export starter kit" writes a self-contained kit (README, a Data/ intake note, the codebook, and one Extractions//Template.md per research question). The reserved keys (extraction-date, extraction-source) are deliberately absent as I understand Quadro adds those itself.
• Method fit per question. New since the version 0.5.0 I was at when we started this discussion: Parallax's research-design step now proposes a method fit per question (qualitative / quantitative / mixed, with a one-line rationale), which the user can adjust. The starter-kit export then opens a selection screen where quantitative-leaning questions are simply unticked by default. So what lands in Extractions/ is the subset that actually suits extraction-based coding. Nothing is blocked, the researcher decides.
• QDA phase → methodological account. Parallax's audit trail now includes an optional QDA section read from progress.json (glad it's stable - it's read as-is) and the codebook structure. A vault without Quadro traces produces a byte-identical account.

No runtime dependency in either direction, as discussed, plain files only. If your offer to add a link in the Quadro README still stands, I'd gladly take you up on it :-) https://github.com/maxonamission/obsidian-parallax (Parallax's own README already points to Quadro under "Works well with").

One more piece has landed since we last spoke: I also maintain Voxtral Transcribe (https://github.com/maxonamission/obsidian-voxtral), a separately installable transcription plugin. It does real-time transcription but for the QDA use case specifically it does transcription of existing audio as well. You can right-click any audio file in the vault and it becomes a markdown transcript note, split into paragraphs, with optional speaker labels (Speaker 1: …). That makes it a natural intake for Quadro's Data/ folder: record an interview, transcribe it, code it.

I've chosen voxtral because it's excellent quality and it's in the eu. The plugin doesn't support on device transcription - yet ... I'm exploring that but really want it to work both on desktop as well as mobile. My main challenge there is achieving high quality real time transcription without requiring a serious GPU :-)

I'm mentioning this because transcription raises three small interoperability questions on the Data side, where I couldn't find pinned conventions yet:

• Data files: does Quadro expect or benefit from any front-matter on files in the Data folder (reserved keys like the extraction templates have, or recommended properties for Bases aggregation — interview date, participant, link to the source audio)? Or is "a markdown file in the Data folder" the whole contract?
• Paragraph unit: since coding is paragraph-wise, is one speaker turn per paragraph the layout you'd recommend for transcripts? And does a bold speaker prefix at the start of a paragraph interact fine with coding?
• Pre-existing block-ids: if a transcript already carries its own block-ids (e.g. timestamps per paragraph), does Quadro reuse them when assigning codes, or always append its own ^id-…? I'd like to avoid generating anything that collides.

If it's useful I can write the answers up as a short "preparing transcripts for Quadro" section in the Voxtral README or have a specific toggle for the required output format there and link Quadro there too.

Kind regards,

Max

[chrisgrieser]

If your offer to add a link in the Quadro README still stands, I'd gladly take you up on it :-) https://github.com/maxonamission/obsidian-parallax (Parallax's own README already points to Quadro under "Works well with").

great, just added!

Data files: does Quadro expect or benefit from any front-matter on files in the Data folder (reserved keys like the extraction templates have, or recommended properties for Bases aggregation — interview date, participant, link to the source audio)? Or is "a markdown file in the Data folder" the whole contract?

For data files there is only one key, the read key which is used by the Mark current Data File as read command. Also, technically, any file outside of the data, extraction, and analysis folder is treated as a (potential) data file.

Paragraph unit: since coding is paragraph-wise, is one speaker turn per paragraph the layout you'd recommend for transcripts? And does a bold speaker prefix at the start of a paragraph interact fine with coding?

What works best imho is one paragraph per speaker turn, and splitting up a paragraph into multiple ones when the speaker speaks longer. But that's to a degree dependent on your data analysis style. Quadro works entirely by the suffix of a paragraph (wikilinks to extraction / code files, and the trailing block id), and is otherwise agnostic to the content of the paragraph.

Pre-existing block-ids: if a transcript already carries its own block-ids (e.g. timestamps per paragraph), does Quadro reuse them when assigning codes, or always append its own ^id-…? I'd like to avoid generating anything that collides.

Since Quadro does not work with the block IDs itself, and just inserts them for Obsidian's embedded-link feature (which in turn only needs unique IDs), Quadro will just re-use existing block-ids if there are any, yes.

[maxonamission]

Thanks first of all of course! Hoping it will help get actual feedback from others to help improve how this combination works for them.

The answers on the transcriptions are the best I could hope for. Exactly what I needed, and simple: no toggle required to create a special output format :-)

I've written the conventions up as a "Preparing transcripts for Quadro" section in the Voxtral README (one paragraph per speaker turn, speaker labels safe, existing block ids reused, read reserved), added Quadro under its "Works well with", and Parallax's starter kit now ships the same advice in its Data/README, in all thirteen artifact languages.

I'll release the new version of the readme shortly, I'm also preparing work on a quantitative route that I am hoping to ship later today.

Just later - first more testing I just found out ;-)

Kind regards,

Max