Create a Custom Report Method for the MassHunter Productivity App

Version 11

    The MassHunter Productivity App allows an admin to add custom reporting methods as long as the methods follow a few guidelines. This document describes those method requirements and is intended for a user that has some scripting experience. If you simply want to change the graphical settings of the default report methods, skip to the end of this document.


    NOTE: This guide is only applicable to reports generated with python for use in MassHunter Quantitative Analysis.


    This document assumes the reader has already installed the MassHunter Quant SDK and reviewed the provided documentation, such as the Reporting Developers Guide.pdf. This documentation can be found at <MassHunter Home>\SDKs\Quant\Documents once installed.


    Technical Overview

    The quant reporting system is invoked by the Productivity App as a command line process. At a high level, data from the Productivity App is passed to the reporting system by XML and then parsed into a global variable (APP_CONTROL_DATA) that is accessible from within the report script environment. This data consists of the compound results that were selected for reporting in the review page, as well as their associated tag and comment data.


    The app uses its own support script to provide additional global definitions and functions to load, sort, and format result data. In addition, the resource manager (used to read entries from the report’s resource file) is automatically loaded into a global variable without the need to supply the name of the resource file. For further reference, this support script is located at <MassHunter Home>\Report Templates\Quant\PDF-Reporting\Codes\, and is automatically included in the script environment at runtime, so it does not need to be explicitly loaded.


    The base directory of a report method is <report method name>.m\DaMethod\Quant. Within the base directory, two files are required for importing into the Productivity App:

    • reportmethod.xml – The traditional report method file used by MH Quantitative Analysis. This file will exist for any existing report method and specifies paths and formatting parameters.
    • template.xml – This file declares the files required to generate the report. In the “Codes” element of this file there must be only one .resx file and at least one .py script listed. Note: a reference to the common script ( will automatically be added by the app at runtime.


    Step-by-step Method Creation

    1. Make a temporary copy of your new report with the basic files

    If you already have a python report method you have been using in MH Quant, you will want to copy the relevant reportmethod.xml and template file to a new, temporary folder somewhere like the desktop. The folder should have a “.m” extension (e.g. Drinking Water EPA 1234.m), and have the \DaMethod\Quant subdirectories under it (e.g. Drinking Water EPA 1234.m\DaMethod\Quant\). Rename your template file to template.xml.


    Note: As an easier option, you could start with one of the default report methods located at <MassHunter Home>\Methods\Productivity App\Report Methods, by renaming the report and copying it to a new location. If you choose this option you will not have to copy any files and the directory structure will be set up for you.


    2. Update code references in template.xml, if required

    You will likely have to update the references in your template file to point to the correct code (.py) file(s). Using a complete (absolute) path to the code file can allow you to reuse code between different methods.


    Note: In most cases, it makes more sense to simply copy the .py file to your new method alongside the template and method files. Any scripts under the report method directory will be copied with it on import, making it a safer option to guarantee the required code is always correct and the reference remains intact.


    Any relative path references must be below the level of the report method directory. Relative references that traverse out of the method are not allowed. For example: “Codes\” is acceptable but “..\..\..\..\” is not. For these files, use an absolute reference.


    Note: You do not need to update the method file at all. The application will automatically edit the method file to point to the template file, provided you have named your template file template.xml and put it in your method folder.


    3. Define user option variables for your script

    If you want to allow users to modify variables used in your report script (e.g. the document Title), copy a config.xml file from the default report methods and put it into your report method’s base directory with the other files. This file contains xml entries for each variable (user option) that you wish to appear in the app while designing the report. Values that the user selects will be available for use through the APP_CONTROL_DATA global in your script.


    4. Update the reporting code to use functions, if desired

    The common code script contains function and class definitions traditionally included in and, additional formatting functions, as well as functions that load the APP_CONTROL_DATA, RESOURCE_MANAGER, and other globals. You will probably wish to copy the python script that generates your report to the new method base directory.


    5. Import your report into the App

    In the admin page of the application, add your custom report method by navigating to and selecting the .m method folder. The application will scan the method to make   sure it’s correctly formatted. If there are any errors, the application will inform you of them.


    For more information, watch this helpful video:


    Modifying Colors and Graph Styles in the Default Report Methods

    You can format graph and text colors (and other graphical options) for any default report method by opening the method in MH Quant as you would normally and modifying any of the below options.


    Important Note About Generating the Results File

    The Productivity App doesn't natively support the generation of the results file and accompanying data. If you wish to generate the results file from the app, you will need to first remove files in the Reports subdirectory of your data folder, if the subdirectory exists. The app will not automatically remove or overwrite the contents of this folder. If your report template requires the generation of the results file, be sure the script handles the management of this directory prior to generating files.