Scripting

SAMSON integrates Python Development Environment:

• SAMSON Python API
• Python interpreter
• Python package manager
• Code Editor
• The possibility to embed Python scripts and apps in SAMSON documents

SAMSON Python API

SAMSON comes with the Python Scripting Extension which exposes the SAMSON API in Python and provides a Jupyter Qt console embedded in SAMSON (see Python interpreter). This allows you to script almost everything in SAMSON with Python, model and simulate from scripts, create pipelines, integrate Python packages for deep learning, bioinformatics, statistics, visualization, and more.

You can use SAMSON AI to help you with Python development - it has been trained on the Python Scripting Guide. For that, use /script in the SAMSON AI assistant - it will generate Python scripts based on your requests. With this command, SAMSON AI can draft Python scripts using the SAMSON Python API, tailored to your specific needs.

See the Python Scripting Guide to learn more how to use SAMSON Python API.

Python Console

The Python Console provides the possibility to access SAMSON's functionality using Python and automate your workflow using scripts. The Python Console integrates the Jupyter Qt Console.

To open the Python Console, click on Interface > Python Console (1).

1. , : Ctrl+8, : Cmd+8

Managing Python packages

To manage installed Python packages, in Python Console go to Edit > Manage packages.... This will open the Python Package Manager window.

In the Package Manager, you can see the list of installed packages and their versions, install/uninstall Python packages.

Installing Python packages

To install a Python package provide its name and click Install.

Note

To install a Python package not available from PyPI, please see Installing a local Python package.

Packages are managed using pip and what you provide will be done using pip. This means that you can:

• Provide a list of packages to install/uninstall.

• Specify the package version, if necessary, as you would do when installing using pip, for example:

• foo==1.2.0 to install the version 1.2.0 of the foo package

• foo>=2.1.0 to install the foo package with the minimal version of 2.1.0

• Add various pip flags after the package name, e.g.: foo --upgrade to upgrade to the latest version.

Installing a local Python package

In the Package Manager, you can also install a local Python package:

• Provide a path to the package you want to install. Note that it should be a valid Python package, i.e. with setup.py, etc.
• Click "Install".

You can also install a local Python package in the editable/develop mode (i.e., same as pip install -e), such that changes in the package's code are dynamically reflected without needing to reinstall it. This is useful when you are making changes in the package since this allows Python to directly reference the package's source files in the package's working directory, so any changes you make are automatically reflected in the package. If you change the package's working directory then you will need to uninstall and reinstall the package again.

Note

If you want to install a package for which you don't need to modify its source code, then do not check the editable/develop mode.

Warning

On some macOS installations, packages installed in the editable mode might not load on the next launch of SAMSON. In this case, you might need to install them in the non-editable mode or reinstall them or register paths to directories with their source files in sys.path.

Uninstalling Python packages

To uninstall a Python package (either installed from PyPI or a local Python package), simply provide its name and click "Uninstall".

Code Editor

SAMSON provides Code editor which integrates Monaco Editor, from the Visual Studio Code. It offers you an intuitive and powerful coding experience, complete with syntax highlighting, auto-completion, and more.

The Code editor provides the possibility to open and modify text files, including Python scripts. It also provides the possibility to run Python files.

To open the Code editor, click on Interface > Code editor (1).

1. , : Ctrl+9, : Cmd+9

To run a Python script, click Run () on the left panel of the Code Editor or in its Run menu or use the integrated Python Console right within SAMSON for quick and easy execution. You get access to the entire SAMSON Python API and can even rapidly create Graphical User Interfaces (GUI) using PyQt.

The Code editor provides a set of Python script templates that demonstrate usages of SAMSON Python API. You can start from them. See the Python Scripting Guide to learn more how to use SAMSON Python API and for more examples.

Python templates

In the Code editor, you can find a set of python templates demonstrating the usage of the Python Scripting and SAMSON Python API for various tasks.

Note

You can find other examples in the Python Scripting Guide: Examples.

Embedding Python Scripts and Apps

SAMSON Documents can contain not only molecular models, they enable Universal File Embedding and can embed Python scripts and any number of files and folders. This makes it possible to embed Python scripts and whole Python apps (e.g., machine learning apps), research papers, images, data, and so much more.

To embed files and folders within a document, drag-and-drop them in SAMSON and you will be asked whether your would like to embed them or use Home > Embed files or Home > Embed folders.

Folders and files are stored within the document, making the document self-contained, so you can transfer documents between computers and share documents.

To open an embedded Python script in the Code Editor, simply double-click on it.

You can share/distribute a SAMSON document via email, GitHub, or the SAMSON Connect - Documents. Your colleagues or students can then open the document and run your embedded Python apps seamlessly.

Here are some of the possibilities:

• You can collaborate with your colleagues by sharing SAMSON Documents that include project files, meeting notes, and automated workflow scripts.
• As a researcher, you can attach executable data analysis scripts to their published molecular models, increasing transparency and reproducibility.
• As a professor, you can distribute SAMSON Documents containing both lecture notes and interactive Python-based exercises for students.
• As an educator, you can create comprehensive, interactive learning modules that students can execute directly within SAMSON.

Python code for commands, palettes, and visual presets

You can easily get the Python code corresponding to SAMSON commands. For example, to know the code corresponding to the Add hydrogens command, begin by searching the command in the Find everything box (1) and click on the Copy icon next to the message "This command is available as Python code":

1. Shortcut: Shift+E

You can then use the code in the Code editor or in the Python console.

You can also access Python code corresponding to color palettes from the color palette or color scheme windows:

as well as to Visual Presets, by clicking on the Copy as Python code button: