Implementing a custom tool in Reveal: scripting (PRO ONLY)

Reveal Chromatography isn’t just a software tool with a user interface. If it was, it would constantly be limited to what is available behind its buttons and menu entries. And that is never sufficient for good science to be made.

Consequently, this application was built, from the beginning, with the idea that it needed to allow extensibility to implement custom tools and support custom scientific workflows. Therefore, there are two ways to write and run custom scripts for Reveal users familiar with the Python language. Both tools are available from the Tools menu entry.

Reveal’s Python console

The first tool available to implement custom chromatography analysis is Reveal’s interacive Python console, accessible via Tools > External Python console:

Launch Python jupyter Qt console

That console is a state of the art Jupyter QtConsole, from the Jupyter project and exposes the set of packages that the Reveal Chromatography application ships with. It is a Matlab like console, allowing users to do the following:

  • type one Python command at a time to interactively compute or plot things, load some project file, ... . Just hit ENTER to execute.
  • use tab completion to explore the content of a package, to complete package, function and class names,
  • use ? at the end of a module or function name to get its description,
  • type %run <SCRIPT NAME> to run any self-contained python script,
  • and so many more ...

To try it out, users can launch the console and type:

from kromatography import version_info

The result of these two commands should be to display the version of Reveal Chromatography currently running:

The fact that the kromatography package can be imported indicates any of the Reveal Chromatography functionalities are available inside that console. To learn about what that includes, and what can be done with it, please refer to the Developer Reference section of the documentation.

We also encourage users not familiar with that tool to learn some of its basic features, for example from the IPython documentation.

For some advanced tips and tricks about how to debug issues while developing a custom analysis in the Python console, please refer to Debugging tips and tricks in the Python console.

Reveal’s Python script runner

The tool

The second tool available in Reveal is a script editor/runner. It exposes a basic code editor supporting syntax highlighting for writing new scripts, a script loader/saver for existing ones, and a button to run them:

Launch Python script runner

Any python file can be loaded into the script runner, and run by clicking the OK button. One can also type in a set of commands to be executed directly in the code editor, and these commands can be saved as a Reveal script for future use.

There are 2 major differences with the interactive Python console:

  1. the script runner code editor isn’t interactive, which makes it more of a tool to use once users have figured out, in the interactive console, how to do what they would like to do.
  2. If the Python console runs in a completely independent way compared to the Reveal application, the script runner has access to the application, and therefore, can read its content and state, as well as modify it.

It is important to understand that the script isn’t run simply as a standalone script. It is run after being provided access to the application and study objects. That expands tremendously what can be done by the script. If it is provided the study object, it can therefore for example access its simulation list, create a new one, and run it programmatically before adding it back into the study. More generally it can access the study data or the user data, and modify them, for example to make batch contributions to them.

Additionally, since it has access to the complete application object, it can open new data or plot tabs, export plot data currently open to a specific files, and so on. To summarize, the script has access to all aspects of the Reveal application, from the data to the GUI aspects, and can therefore do anything to the currently running application in addition to doing anything that this language can do on its own.

Example scripts

The simplest possible script that could be written in the tool would just contain the following:

print("Hello world!")

Clicking OK will lead to the following window to open:

Launch Python script hello world

There are more example scripts in Reveal Chromatography and the interested reader is encouraged to read the section dedicated to providing more details about how scripts are run in Interacting with the application from a Reveal script.

How to write your own script?

Writing new scripts requires to have some knowledge of the following:

  1. the Python language,
  2. how scripts are run, and what they have access to,
  3. the package behind the Reveal Chromatography application, called kromatography.

The Python language is one of the most popular open source programming languages, and the interested reader is advised to benefit from the swath of resources to learn it.

Learning about the kromatography package is the purpose of the Developer Reference section. There, the code organization is presented, and a tutorial goes over some of the most commonly used functionalities such as creating a simulation mimic-ing an experiment, running simulation grids, or customizing optimizers.

Finally, for more details on how scripts are run, and how they can have access to the application elements, please continue on to Interacting with the application from a Reveal script if standalone scripts are not enough, and there is a need for developing a tool which modifies one’s application while running.

When to use the script runner and when to use the console?

By default, if a user is developing a new analysis, the Python console, with its interactivity, will be the tool of choice. The script runner was developed to be used in the following situations:

  1. A user has developed a set of commands that is useful, and that needs to be applied over and over in various projects, or applied by users not familiar or comfortable with Python. Saving these commands into a Python file allows such a user to just run things by loading the script and clicking OK.
  2. A set of commands needs to be applied to a running application, and closing and saving the project isn’t an option. For example, an optimizer has been run, and while all simulations of the optimizer are still in memory (saving a project will only save the three or so optimal simulations), the user would like to try out a new cost function to explore the stability of the optimal parameters.