kb_djornl

This KBase module is a wrapper and visualization for RWR tools which use the random walk with restart method on multiplex coexpression networks representing genes (nodes) and distinct lines of evidence (edges) facilitating the rapid determination of the functional context of genes of interest. This 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.

RWRtoolkit CV

This app wraps the RWR Cross Validation tool which performs k-fold cross validation on a single gene set, finding the RWR rank of the left-out genes. One can choose either leave-one-out to leave only one gene from the gene set out and find its rank, or run k-fold cross-validation for a specified value of k.

RWRtoolkit LOE

This app wraps the RWR Lines of Evidence tool which has two possible functions. Given one geneset of seeds, rankings for all other genes in the network will be returned. Given a second geneset, ranking for just the genes in that geneset will be returned. This can be used to build multiple lines of evidence from the various input networks to relate the two gene sets.

Tests

Run

kb-sdk test

Add your KBase developer token to test_local/test.cfg and run:

kb-sdk test

This may take a long time, the build action is runs in approximately 30 minutes from scratch. Subsequent runs should be faster for two reasons. Firstly, the initial Docker build takes some time, primarily compiling the conda environment. This needs to be done only once since Docker will cache the results. Secondly, the exascale_repo data source is validated and this can take around 10 minutes on its own. Since this is loaded as refdata, this also only happens when the refdata is updated. For instructions on how to update the refdata, see the Howsto section below.

Contributing

Note: By default the module image uses Python 3.8.10, and these instructions are tested with this version, but will probably work with any higher version. Follow the following instructions to configure your development environment.

0. Install prerequisites:
   • kb-sdk
   • node >= 20.9.0
   • python >= 3.8.10
1. Make a virtual environment and activate it.

python -m venv $VENV
source $VENV/bin/activate

2. Install Python requirements:

pip install \
    --extra-index-url https://pypi.anaconda.org/kbase/simple \
    -r requirements.txt

2. Run kb-sdk test. This will generate a sample report.
3. Install the Javascript requirements:

npm install

4. Start a server to serve the sample report:

npm run serve

By default this server listens on port 8080, but you can specify any port with the following invocation:

npm run serve -- --port $PORT

5. (Optional) Enable the pre-commit hooks:

cp scripts/pre-commit.sh .git/hooks/pre-commit

Howsto

The instructions in this section refer to the following external repositories:

• Data: exascale_data
• Relation Engine (RE): relation_engine
• The RWRtoolkit repository.

Test a new version of the app

1. Register the app in the desired environment.
2. Update app cells in narratives with the new version of the app.
3. Create an app cell representing a call guaranteed to contain some of the new data to confirm that it has been updated correctly.

Update layer

This section specifically refers how to add, edit or replace edges in an existing network.

1. Update the exascale_data repo with the layer in question, this should ultimately be an update to a single file in the prerelease/edge_data folder.
2. Commit this change to the repository in GitHub.
3. Modify the git clone command for exascale_data in scripts/refdata-load.sh to point to the correct branch or commit.
4. Bump the data-version semantic version value in kbase.yml. This will ensure that the refdata is loaded in the next step.
5. Commit these changes to the kb_djornl repository in GitHub.
6. Test this new version of the app.

Add Layer

This section specifically refers how to add a single new network represented by a TSV file with four columns (node1, node2, score, edge_type) and a header row. It also assumes that this network introduces a single new edge_type.

1. Update the exascale_data repo.
   1. Add the layer in question, this should ultimately be an addition of a single file to the prerelease/edge_data folder.
   2. Update the prerelease/manifest.yaml file with appropriate metadata for this layer.
   3. Commit these changes to the repository in GitHub.
2. Update the RE repo.
   1. Modify the spec/datasets/djornl/edge_type.yaml file ensuring that the const key's value matches the edge type in the network (edge) file.
   2. Commit these changes to the repository in GitHub.
3. Update the kb_djornl app:
   1. Modify edgeMetadata in the report/app/style.js file. The key should be the desired edge_type and the value should contain the other appropriate metadata.
   2. Modify the git clone command for exascale_data and relation_engine in scripts/refdata-load.sh to point to the correct branch or commit for the changes above.
   3. Bump the data-version semantic version value in kbase.yml. This will ensure that the refdata is loaded in the next step.
   4. Commit these changes to the repository in GitHub.
4. Test this new version of the app.

View a sample report generated by the tests

1. Ensure that the test that generates the report runs last in the test suite. You may prefer to skip all other tests so that the test of interest is the only one that runs.
2. Run the postinstall script: npm run postinstall. This will automatically run the kb-sdk test command and download the static files required to make the report appear as it would in KBase.
3. If you have not yet already, run npm run serve and load the sample report: http://localhost:8080.
4. Update metadata.json. You need to set objid to the obect id of the workspace object holding the visual app state.
5. Add the workspace id to localStorage. In the javascript console run: localStorage.setItem("wsid", mywsid) where mywsid is the numeric workspace id of the workspace object holding the visual app state.
6. Set a browser cookie for the localhost hostname named kbase_session whose value should be a valid authentication token for your chosen KBase environment. You can reuse the token from test.cfg.
7. Disable CORS for localhost. This must be done since the app is not configured to use a KBase service proxy answering on localhost.
8. Reload the report. It should now be fully functional.