Getting started

To get started with contributing to OpenProblems, you’ll need to fork and clone the OpenProblems task repository to your local machine.

Step 1: Create a fork

Go to the OpenProblems organization at https://github.com/openproblems-bio and search for the task repository you want to contribute to. Open the repository and click the Fork button in the top right corner.

This will create a copy of the repository under your GitHub account.

Tip

While you’re at it, why not click the Star button as well?

Step 2: Clone the repository

To clone the forked repository to your local machine, copy the URL by clicking the green Code button and selecting HTTPS or SSH.

In your terminal, navigate to the directory where you want to clone the repository and run:

git clone --recursive <forked repository URL>
cd <repository name>

This downloads a copy of the repository. Please commit your changes to a new branch following the branch naming convention.

Note

If no files are visible in the common submodule after cloning, run the following to initialize it:

git submodule update --init --recursive

Step 3: Download test resources

Download the test resources by running the following command from the repository root. These are needed for testing existing components and developing new unit tests.

scripts/sync_resources.sh

The test resources are stored in the resources_test/ directory.

Ready, set, go!

Now you should be able to test whether existing components work and start adding new functionality.

Run a component

Use viash run to run a Viash component. Everything after the -- separator is passed as arguments to the component itself.

viash run src/methods/logistic_regression/config.vsh.yaml -- \
  --input_train resources_test/task_template/cxg_mouse_pancreas_atlas/train.h5ad \
  --input_test resources_test/task_template/cxg_mouse_pancreas_atlas/test.h5ad \
  --output output.h5ad

Test a component

Each task ships with pre-defined unit tests that can be run with viash test:

viash test src/methods/logistic_regression/config.vsh.yaml

To run all unit tests for every component in a task at once:

viash ns test --parallel --engine docker

Example output

          namespace                 name               runner               engine            test_name exit_code duration               result
    control_methods          true_labels           executable               docker                start
            metrics             accuracy           executable               docker                start
    data_processors      process_dataset           executable               docker                start
            methods  logistic_regression           executable               docker                start
    data_processors      process_dataset           executable               docker     build_executable         0        2              SUCCESS
    data_processors      process_dataset           executable               docker run_and_check_output.py         0        4              SUCCESS
    control_methods          true_labels           executable               docker     build_executable         0        2              SUCCESS
    control_methods          true_labels           executable               docker run_and_check_output.py         0        4              SUCCESS
    control_methods          true_labels           executable               docker      check_config.py         0        3              SUCCESS
            metrics             accuracy           executable               docker     build_executable         0        2              SUCCESS
            metrics             accuracy           executable               docker run_and_check_output.py         0        5              SUCCESS
            metrics             accuracy           executable               docker      check_config.py         0        2              SUCCESS
            methods  logistic_regression           executable               docker     build_executable         0        2              SUCCESS
            methods  logistic_regression           executable               docker run_and_check_output.py         0        5              SUCCESS
            methods  logistic_regression           executable               docker      check_config.py         0        3              SUCCESS
All 11 configs built and tested successfully