Creating an Operator

If you would like to integrate your pipeline into Beagle with an Operator, please follow this guide

1. Setup

Setup a local instance of Beagle (see https://github.com/mskcc/beagle#setup). Make sure to point to the staging Ridgeback instance using RIDGEBACK_ environment variables

2. Create Test Fixtures

Create test objects for the models that your operator will require

1. Most likely you will need to create Pipeline, Port, Operator, and File objects

2. Use Django fixtures, preferably in JSON format

3. Try to emulate how the data will look in the database for a real run. For example if a File has a sample ID, try to use one that is formatted similarly to how it will look in production, so that any operator logic can be reliably tested

4. See the below schema diagram to understand how these objects must be linked by their foreign keys

5. If you would like to do any testing outside of the subsequent unit tests, you should manually load these fixtures into your local Beagle database as the test DB will only be created at test runtime

3. Create a TestCase

1. Write a test case that loads these fixtures and calls the get_jobs() method of the Operator class

   1. You can emulate this example here: ACCESS SNV operator test

   2. Include the “fixtures” attribute of the test case to automatically load the fixtures

   3. Include assert statements any key aspects of the inputs file that you feel should be validated up front (such as sample IDs matching, or fields being present)

4. Write the Operator Code

1. Now you can write the code for the Operator by implementing the get_jobs() method of the Operator class

2. You can look at this example operator to start: ACCESS SNV operator
3. Notice how the relevant files are queried from the Beagle DB, and file paths are supplied as inputs to the pipeline

4. Make sure to register any input files in the Beagle DB using the /v0/files endpoint

5. Test the Operator

1. Test the operator by calling /v0​/run​/operator​/runs​/ through the Django Swagger UI

6. Submit a Pull Request

1. Once you have completed testing your operator, submit a PR to the Beagle codebase