Create your first task

In this tutorial you will learn how to create and test a Task. This required basic understanding of what a Task is and what a Resource is.

• Please check the following link if you don't know what is a Task : Task > what-is-a-task-?.
• Please check the following link if your don't know what is a Resource : Resource > what-is-a-resource?.

The goal of this tutorial is to create a simple task that apply a factor to all the data of a Table. A Table is one of the main Resource that represent a 2d array (it contains a Dataframe).

You can also follow this tutorial in video:

Let's do it 💪

Create your task

Specify your task

First, you need to create an empty task named TableFactor in the folder src/gws_academy/tutorials/table_factor. To learn on how to create a Task, please check the following link Task > how-to-create-a-task-?.

Define an input_specs named input_table and an output_specs named output_table, both of type Table . To learn about inputs and outputs, please check the following link Task > inputs-&-outputs.

Define an IntParam named factor . The value of this parameters will be apply to the whole Dataframe. We use a parameter so a user will be available to configure it when he uses your task .To learn about the task configuration, please check the following link Task > configuration.

Write the run method

Now all the specifications of your task are done you can write the task code . Define an empty run method like so (all the classes are imported from gws_core)

def run(self, params: ConfigParams, inputs: TaskInputs) -> TaskOutputs:
    return {}

Now to write the method, you will need to :

1. retrieve the input Table
2. retrieve the config value
3. get the Dataframe from the Table (use the get_data method)
4. apply the factor to the Dataframe
5. create a Table with the new Dataframe (Table(my_dataframe))
6. return the new Table as output

Test your task

Now that your task is written, we need to test it to check if it is working.

Create the test

Create an empty test named TestTableFactor in the folder tests/table_factor. To learn about the unit test and how to create them, please check the following link Task > write-unit-test.

Create the async test method test_table_folder .

Now to write the test you will need to :

1. create a simple Table to test the Task
2. create a Dataframe : dataframe = DataFrame({'A': [0, 1, 2],'B': [9, 7, 5]})
3. create the Table from the Dataframe : table = Table(dataframe)
4. create the TaskRunner (see exemple in the link above)
1. provide the task type TableFactor to the task runner. You will have to import you TableFactor class : from gws_academy.table_factor.task.table_factor import TableFactor. The import must be an absolute import (not a relative) because the tests folder is outside the scope of the gws_academy python package.
2. provide the previously created Table as input of the TaskRunner.
3. provide the configuration value, let's use a factor of 2.
5. execute the TaskRunner
6. retrieve the output Table
7. manually create the expected table to compare it to the TaskRunner result. Create a Table from the Dataframe : DataFrame({'A': [0, 2, 4],'B': [18, 14, 10]})
8. Compare the two Table using an assert function : self.assertTrue(result_table.equals(expected_table))

And that's it your test is done 🍾! You can run it to check if everything is working.

Here is the complete example

def test_table_factor(self):
        # create the input table
        dataframe = DataFrame({'A': [0, 1, 2], 'B': [9, 7, 5]})
        table = Table(dataframe)
        # create and configure task runner
        tester = TaskRunner(
            task_type=TableFactor,
            inputs={'input_table': table},
            params={'factor': 2},
        )
        # run the task and retrieve the outputs
        outputs = tester.run()
        # get the output table
        result_table: Table = outputs['output_table']
        # create the expected table
        expected_dataframe = DataFrame({'A': [0, 2, 4], 'B': [18, 14, 10]})
        expected_table = Table(expected_dataframe)
        # compare the output table with the expected table
        self.assertTrue(result_table.equals(expected_table))

Run the test

To know how to execute and debug a test, check the following link : Run test

When you click on the Run single file button, enter your brick name and your test file run to run the test : gws_academy/test_table_factor.

You test will then run and if you have errors, please fix them. If you test was ok you should see a similar message than the photo bellow. 

Check your task with the pre-written test.

In the gws_academy brick we wrote a test file that you should execute to see if you task was correctly developed. It could also help you to see how to write a clean test. The test file is available at tests/solutions/test_so_table_factor.py.

You can run the test the same way your run your own test, the file name is test_so_table_factor, here is the complete input to run the test: gws_academy/test_so_table_factor.

If this test ends up in success, it means you correctly wrote you task and your Test, CONGRATULATION, you’re done with this tutorial!

If this test ends up in error, it means 2 things:

• your task was not implemented correctly
• please check the class name and the name of your input, output and configuration, they must match the names provided in the tutorial.
• your test was not written correctly because your test should have ended up in error and not success. It means that your test is not correctly testing your task. 

Test your task in the interface

Now that your task is ready to be used, you can test it in real conditions. Start your lab in dev mode : Start dev server

In dev mode, upload a csv file and import it as Table so it can be used as input of our task. Create a scenario and add the task to it. Plug your imported table as input and add and output to the task.