Analysis Modules

WAD-QC 2.0 makes use of different Analysis Modules to define tests to perform on incoming data. These Modules can be User Modules (i.e. private Modules developed by a user), or publicly available Factory Modules developed by the WAD-QC 2.0 developers.

User Modules

Anyone can develop a User Module, and distribute it to other users. To that end, WAD Admin has implemented an import/export mechanism.

To export a Module, select the Module Configuration files to include (the Module itself is added automatically), and press the Export button. The generated zip-file can then be imported by another user. Any installed Module can exported this way. Note that if you export a Factory Module, it will be exported as a User Module.

When importing a Module from an zip-file, WAD Admin first checks for conflicts with existing Modules, and offers suggestions on how to solve them.

If you develop a new module, please inform the developers of WAD-QC so the link can be added and possible dependencies can be added to the base installation.

Factory Modules

The supported and publicly available Factory Modules are available in a repository hosted on GitHub. These Modules are tested and will be supported by the developers. WAD Admin can be used to query for new Factory Modules or updates of installed Modules. WAD Admin will offer to upgrade or install the found Factory Modules.

Pre-releases

Pre-releases are release candidates intended for limited testing before release. They are marked as such in the repository, and are identifiable by the version number: e.g. v1.0-rc.2 marks release candidate 2 for release version 1.0. Release candidates are not supported, and can be deleted from the repository at a later time.

Releases

Official releases are also identifiable by the version number: e.g. v1.1 marks update 1 for release version 1. These releases will be supported by the developers.

Dependencies

When installing new modules, or updating existing modules, it is possible that new dependencies to certain python packages are introduced. The dependencies of a module are described in the wiki of that module.

If analysis fails because of a missing dependency, this can be spotted by inspecting the logs of the failed Process, and looking for mentions of "ImportError". That error, in combination with the published list of dependencies should pin point what package should be installed.

To install a specific package, open a command line and activate the virtualenv (workon wad2env3), and issue:

pip3 install <package>

pip3 install foo-bar==1.2.1

Updates

When an existing Module is updated through WAD Admin, the linked Configs are also replaced with new versions. This means that if a user added some Configs to that Module, then these Configs will be removed when updating the Module, so download those Configs (and Metas) before upgrading!

Note that Configs used in Results, Processes and Selectors are NOT changed. So if you want to take advantage of and updated Config in a Selector, you have to manually modify the Selector after updating the Module. Similarly, to rerun a Result or Process with updated Config, you have to first update the Selector, then delete the Process or Result, and resend the data to the Selector using WAD Admin.

New Releases

New releases can be published using the release functionality of GitHub. To make a new release, the developer should adhere to some good practices.

1. The Module should have wiki page with documentation of its usage and performed analysis
2. The release should contain all Configs needed to access all different functionalities of the Module. For example, if a Module is used to do only subsets of all available tests for certain phantoms, then either a generically usable Config with all functionalities should be included, or a different Config for each phantom should be supplied.
3. All Configs included should be tested for this specific Release, so the developer needs sample data sets for each Config.
4. The make_factory_module.py script should be used to make importable zip-file of this release of the Factory Module. It should be tested that the resulting zip-file can be imported as User Module without problems.
5. The release should include release notes, stating the most important changes in the module, so that a user can determine if old results should be regenerated with the updated module and if there are any modifications needed to the Config files used at present by Selectors.
6. The release number should be of the format v2.3 (for a supported release) or v2.3-rc.2 (for a unsupported release candidate).

GitHub API Rate Limit Exceeded

By default, checking for Factory Modules on GitHub uses public access. The downside is that only 60 public access requests per hour are allowed, so one quickly exceeds the API Rate Limit.

I is possible to switch to authenticated access, which removes the 60 requests per hour limit. To do so, you need a GitHub account.

Since WAD-QC version 2.0.10, you can provide a Personal Access Token of your own GitHub account. The token can be entered through the WAD-QC Admin/factorymodules page. Note: this access token does not need any special GitHub scopes.

Creating a GitHub Personal Access token

If you already have a GitHub account, start at step 2.

1. Go to GitHub and sign up for an account
2. Login to GitHub with your account and go directly to https://github.com/settings/tokens/new
3. Use the Note to indicate this token will be used for WAD-QC Factory Modules access
4. Specify the Expiration time
5. Do not select anything in the scopes menu (the token is only to be used to confirm you have a github account)
6. Click "Generate token"
7. Now copy the token and store it for later usage (you will not get a second chance to see this token)

WAD-QC version before 2.0.10

For WAD-QC version before 2.0.10, you have to write down your GitHub credentials in plain text in the file <WADDROOT>/WAD_QC/repo.ini. Use the following format:

[https://api.github.com/users/MedPhysQC/repos]
# developer authentication
USER = your_github_user_name
PSWD = your_github_password