Write a macro

CCPN Analysis provides a simple macro method to interact with your NMR data. Macros are similar to 'plug-ins' in other software. In this brief how-to come tutorial, we'll learn how to write a simple macro to allow you to assign a keyboard key to an Analysis function.

Problem:

You find yourself having to click an uncomfortable number of times to reach a function that you frequently use. Wouldn't it be nice to have the same function attached to a keyboard shortcut? Of course it would! Can you do this with Analysis? Of course you can! Let's say that your favourite function is 'Propagate assignments' in the right-click -> 'Assign' menu. In this how-to we will write a macro that allows us to assign this function to a keyboard shortcut.

Solution:

Part 1. What will our macro do?

Before we can write a good macro, we need to know what it must do. As the macro should do the same thing as clicking 'Propagate assignments', so that button seems like a good place to start. Let's have a closer look at the 'Propagate assignments' function - but where is it? We can easily search the Analysis code for this button using:

$ grep -Ir 'Propagate assignments' <ccpn_dir>/python/*

which tells us (amongst other things) that the button which is labelled 'Propagate assignments' is defined in the file

ccpnmr/analysis/frames/WindowFrame.py

Let's open that file up and have a closer look. You will see that in a class called WindowFrame there is a function called propagatePeakAssigments(). More exactly, it looks like this;

  def propagatePeakAssignments(self, event):

    peaks = self.topPopup.currentPeaks

    if peaks:

      propagatePeakAssignments(peaks)

This function simply gets the selected peaks and calls another (different) function called propagatePeakAssigments(). This is all our macro needs to do as well. 

Part 2. Writing the macro file.

The macro file is simply a short python script containing the function that you want to call, in our case propagatePeakAssigments(). When Analysis calls the macro function in the file, it first needs to know where to find any function not in the file. The first line of our macro should look like this:

from ccpnmr.analysis.core.AssignmentBasic import propagatePeakAssignments

Next we must define the function that will be called when we press the keyboard shortcut. We do this by creating a python function with a sensible sounding name:

def propagatePeakAssignmentsMacro(argServer):

The argServer part is what connects us with the Analysis program. We use it in the next line to give us the peaks that have been picked:

  peaks = argServer.getCurrentPeaks()

The last part of the function is just like the 'Propagate assignments' function in WindowFrame.py - we check that we actually have some peaks, and then if we do we calle the propagatePeakAssignments() function.

  if peaks:

    propagatePeakAssignments(peaks)

After all that, you should have a file whose contents look remarkably similar to:

from ccpnmr.analysis.core.AssignmentBasic import propagatePeakAssignments

def propagatePeakAssignmentsMacro(argServer):

  peaks = argServer.getCurrentPeaks()

  if peaks:

    propagatePeakAssignments(peaks)

and that's it. 

Part 3. Adding your macro to Analysis. 

Open up Analysis and load a project. As you're testing out a macro that you've just written, it's probably not wise to open the project that you're using to find a cure for cancer, write the next Nature frontpage article or about to show your Boss - just in case! Once you've got a project open, go to the 'Macros' menu option in the Analysis main bar and choose 'Organise Macros'. At the bottom of the pop-up choose 'Add Macro' and choose the file that you've just created. Any available functions in that file will then be listed at the bottom of the pop-up. Choose the function that you'd like to call as your macro, and click 'Load Macro'. 

Now, in the Macro pop-up that appeared initially, you should find your shiny new macro. Double-click in the 'Shortcut' cell to assign a keyboard shortcut. You new macro is now ready to be tested!

Part 4. Testing your macro.

Inevitably your new macro won't work. If it does work you are a coding guru and should feel very proud of yourself. Everybody else should read on: Fixing and testing your macro is Very Easy so don't feel too put out. Just change whatever was miss-spelt, miss-aligned or just plain wrong in the macro function and click 'Reload' in the Organise Macros pop-up. Your fixed macro is now a finger click away - test it out!

If you are still having problems with your macros, just drop the CCPN Jisc list a line and some-one will be sure to help you out. CCPN have a library of pre-written macros that you are welcome to experiment and try out for yourself here.