Introduction Version

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.

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).

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
    1. retrieve the config value
      1. get the Dataframe from the Table (use the get_data method)
        1. apply the factor to the Dataframe
          1. create a Table with the new Dataframe (Table(my_dataframe))
            1. 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
                1. create a Dataframe : dataframe = DataFrame({'A': [0, 1, 2],'B': [9, 7, 5]})
                  1. create the Table from the Dataframe : table = Table(dataframe)
                    1. 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.
                        1. provide the previously created Table as input of the TaskRunner.
                          1. provide the configuration value, let's use a factor of 2.
                          2. execute the TaskRunner
                            1. retrieve the output Table
                              1. 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]})
                                1. 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(
                                              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

                                  Run the test

                                  To know how to execute and debug a test, check the following link : https://constellab.community/bricks/gws_core/latest/doc/developer-guide/dev-environment/getting-started

                                  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 : https://constellab.community/tech-doc/doc/developer-guide/dev-environment/getting-started#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 an experiment and add the task to it. Plug your imported table as input and add and output to the task.