Web Analytics Made Easy - Statcounter
Skip to content

Scripting#

Use this page when you want to automate SAMSON workflows with Python, run code in the integrated console, manage packages, edit scripts, or embed scripts and apps in documents.

The integrated Python environment includes:

See also: Python Scripting Guide.

What this page covers#

This page explains how to use the integrated Python environment in SAMSON for automation, reproducibility, and custom workflows.

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.

Note

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

Python Console

Managing Python packages#

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

Manage packages...

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.

Package Manager: install a Python package

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 or 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.

Package Manager: install a local Python package

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 Visual Studio Code. It offers an intuitive 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

Code Editor Interface

To run a Python script, click Run (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 execution. You get access to the entire SAMSON Python API and can even rapidly create graphical user interfaces 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 Python Scripting and the SAMSON Python API for various tasks.

Python templates

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 much more.

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

Embed file dialog

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 or 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 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 Copy icon next to the message "This command is available as Python code":

  1. Shortcut: Shift+E

Copy Python code for a command

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:

Copy Python code for a color palette

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

Copy Python code for a visual preset

Next step#