The KBase Combinatrix

This is a KBase module generated by the KBase Software Development Kit (SDK).

You will need to have the SDK installed to use this module. Learn more about the SDK and how to use it.

You can also learn more about the apps implemented in this module from its catalog page or its spec file.

Help

You may find the answers to your questions in our FAQ or Troubleshooting Guide.

Installation from another module

To use this code in another SDK module, call kb-sdk install combinatrix in the other module's root directory.

Local development

The Combinatrix repo has been developed using Python 3.12 and automated tests are run on 3.10, 3.11, and 3.12. No support is provided for earlier python versions.

There are three sets of dependencies for the repo:

requirements.txt - packages required for runtime
requirements-test.txt - packages used in testing and generating coverage
requirements-dev.txt - includes a range of extra tools for formatting and linting code.

The contents of the three files are mutually exclusive, so all three should be installed for the full development environment.

Pip is not always completely reliable at pulling in package dependencies, so it is recommended that you install packages one at a time as follows:

$ cat requirements.txt | sed -e '/^\s*#.*$/d' -e '/^\s*$/d' | xargs -n 1 pip install

...substituting in the appropriate requirements file name.

To keep everything neat and tidy and to prevent clashing module installations, it is recommended that you create a python environment for local development.

Example set-up instructions using pyenv and the virtualenv plugin:

# create a virtual environment for the combinatrix app
pyenv virtualenv 3.12 combinatrix

# activate the virtual environment (if necessary)
pyenv activate combinatrix

# install the requirements
cat requirements.txt | sed -e '/^\s*#.*$/d' -e '/^\s*$/d' | xargs -n 1 pip install

If you make changes to the module spec, you will need to rerun kb-sdk to recompile the server, implementation, and compile_report.json. Using the shortcut make compile is the simplest way to do this.

Fetching workspace data

The test directory includes a command-line script that can be used to fetch data from the workspace and either save it as-is or convert it to CSV. See test/fetch_ws_data.py to use it.

Testing

Note: a few of the tests contact various KBase services (the workspace and the sample server). The code uses vcrpy to replay previously-recorded server responses so that the tests can be run without needing a token. In the instructions below, the auth token can be left blank or unset.

The test datasets that are used are on the appdev server.

If you are using VSCode, you can use the built-in testing framework to run tests. You will need to ensure that the following settings are configured:

    "python.envFile": "${workspaceFolder}/.vscode/test.env",
    "python.testing.pytestEnabled": true,

.vscode/test.env should be a simple environment file in the following form:

PYTHONPATH=/path/to/the/combinatrix/directory/lib
KB_AUTH_TOKEN=YOUR_APPDEV_TOKEN_HERE_IF_NECESSARY

You can then navigate to the test pane (the little flask icon) and run tests as you please.

To run tests from the command line, use the script test/run_tests.sh. It will automatically set the PYTHONPATH environment variable but you will need to add the KB_AUTH_TOKEN value if you are planning to connect to any of the KBase services.

# run tests, no external services required
sh test/run_tests.sh

# run tests using KBase services
KB_AUTH_TOKEN=MY_COOL_APPDEV_TOKEN sh test/run_tests.sh

Testing the Combinatrix output

Although the Combinatrix creates a KBase report as its output, the request to create the report has been mocked out to remove the dependency on the SDK callback server, which necessitates the use of the SDK for testing.