A molecular project can be difficult to hand off even when the structure itself is easy to share. A colleague may receive the model but not the script that generated an analysis, the data it depends on, or the steps needed to run it. Reconstructing those pieces from memory costs time—and makes it harder to reproduce the same workflow later.
SAMSON offers a practical way to keep molecular documents and supporting files together: embed Python scripts, folders, and other files in the document. The result can serve as a handoff package for a project, classroom exercise, or analysis—not just as a container for the molecular model.
Start with a workflow you can run
SAMSON includes a Python environment with access to the SAMSON Python API. Use the integrated Python Console for quick experiments, or open a script in the Code Editor when you want a reusable file. The Code Editor supports Python scripts and includes templates that demonstrate API usage.
This distinction helps when turning an ad hoc task into a repeatable workflow. Try an idea in the console, then move the steps you want to keep into a script. You can run a Python file from the Code Editor or use the console for execution. To open these tools, choose Interface > Python Console or Interface > Code editor.
For tasks already available as SAMSON commands, you may be able to start from the command’s Python equivalent rather than writing it from scratch. Search for a command in the Find everything box, then use the copy icon when SAMSON indicates that the command is available as Python code. The copied code can be used in the Code Editor or Python Console.
Keep the supporting files with the document
When your workflow depends on scripts, input data, images, or folders, add those files to the SAMSON document. Drag and drop files or folders into SAMSON and respond to the prompt to embed them, or use Home > Embed files or Home > Embed folders.
Embedded items are stored within the document, which makes the document self-contained with respect to those files. To open an embedded Python script in the Code Editor, double-click it. You can then share the document by email, through GitHub, or via SAMSON Connect Documents. This is useful when a collaborator needs the model and the project materials in one place, or when you want to distribute an exercise with both instructions and runnable code.
Make the handoff easier to understand
Embedding files solves one part of reproducibility: keeping project materials together. A useful handoff also explains what the script is for and how to use it. Consider adding a short note or readme to the document that identifies the entry-point script, describes the expected inputs, and records the intended sequence of actions. This is a practical habit rather than a SAMSON requirement, but it helps recipients orient themselves before running anything.
There is one important distinction: embedding a script or data file does not, by itself, mean that every external Python package used by the script is included. SAMSON’s Python Package Manager, available from Python Console > Edit > Manage packages…, lets you install packages using pip. If your workflow uses additional packages, document which ones are needed and, where useful, the required versions. The manager accepts version specifications such as foo==1.2.0. Local Python packages can also be installed by providing a package path; editable/develop mode is intended for packages whose source code you are actively changing.
For a project that is still under development, editable installation can make source changes visible without reinstalling the package. For a package you simply need to use, the documentation advises leaving editable mode unchecked. It also notes that editable packages may fail to load after relaunch on some macOS installations, so test the setup you plan to share.
A simple sharing checklist
- Include the molecular document and the scripts, data, or folders required by the workflow.
- Open an embedded script in the Code Editor and confirm it is the one intended to run.
- Record any external Python package requirements and relevant versions.
- Give recipients a short explanation of the workflow’s purpose and starting point.
- Share the document through a channel that works for your collaborators, students, or team.
A little organization at the point of sharing can save recipients from hunting through separate attachments and trying to infer how the analysis was performed. It also makes it easier for you to return to the project later and understand what belongs together.
For details on the Python environment, package management, the Code Editor, and embedding files, see the SAMSON Scripting documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.