Give Every Research Figure a Small Manifest

Об этом предложении

By Tian @ FigCanvas Disclosure: I work on FigCanvas. The manifest below is a suggested workflow, not a report of a measured experiment or a built-in FigCanvas feature. A research figure is often assembled from several sources: a plot exported by a script, a workflow diagram, a schematic, and a caption in a separate document. File names such as figure_final_v4_revised.png do little to explain how those pieces fit together. A small manifest can make that relationship explicit. It is a text file kept next to the figure sources. Its job is to identify the inputs and decisions behind one export, so a later revision does not depend on someone's memory. Start with a panel map For each panel, record its letter, purpose, source file, and the condition or analysis version it represents. Use stable paths within the project. Avoid putting confidential data or credentials into a public repository; a local reference is enough when the underlying input cannot be shared. Here is a fictional example: { "figure_id": "figure_03", "revision": "r02", "panels": [ { "label": "A", "purpose": "Explain the processing workflow", "source": "diagrams/workflow.svg", "review_status": "checked" }, { "label": "B", "purpose": "Compare the two example conditions", "source": "plots/comparison.svg", "analysis_ref": "analysis/comparison_v2.py", "review_status": "needs_caption_check" } ], "caption": "captions/figure_03.md", "export": "exports/figure_03_r02.png" } The schema is deliberately small. It names the material needed for review without trying to replace a laboratory's data-management system. A manifest is also a record of intended provenance, not proof that the referenced analysis was executed correctly. Record meaning as well as file paths Add a short note describing shared conventions. For example: circles denote measured samples, dashed arrows denote proposed relationships, and a particular label always refers to the same condition. These decisions are easy to lose when two people edit different panels. A manifest gives a reviewer somewhere to check the intended meaning before changing a color or symbol. It can also record unresolved questions instead of letting an uncertain relationship look settled in the artwork. If a generative tool helped create a schematic, keep the relevant prompt and review notes with the sources when appropriate. A prompt alone is not a reproducibility guarantee: model behavior, settings, and subsequent manual edits can change the result. Preserve the actual editable output as well. Make revisions explicit When a reviewer requests a change, update the source and identify the affected panel in the manifest. Then export the complete figure again and inspect that export. Reusing an old composite after updating one source file can leave the delivered figure out of sync with the project. For a code-driven plot, a commit identifier or a content checksum can help distinguish revisions. For a manually edited diagram, a versioned source file and a short change note may be more practical. Use the simplest method your collaborators will maintain. Keep assembly separate from verification FigCanvas provides a canvas for arranging scientific illustrations, charts, and flowcharts. A manifest can sit alongside that workflow and identify the sources and review decisions that matter to your project; it does not require an integration with the tool. Before sharing a final figure, check that every panel in the manifest exists in the export, every caption reference points to the intended panel, and every unresolved review item has been addressed. The benefit is a clear handoff: another collaborator can see what changed and where to begin the next revision.