The APEER SDK Family

14.12.2018
How-tos

APEER SDKs for Python, Java and Matlab now available

Peers!

This is Thomas – one of the dedicated developers behind APEER. We have all been working hard for the past 18 months to get APEER up and running. Now that it’s live and you are using it we get a lot of feedback which features we need to develop in the future and which parts are not as easy as they should be. One of those parts is the creation of modules itself. As software developers we often don’t realize things that are part of our daily business can be real hurdles to you. The three things you have to deal with if you want to build a module on APEER are

  1. Reading inputs and writing outputs in the APEER environment
  2. Module Specification
  3. Docker

Today I’m very excited to tell you how we already solved the first problem in this list.

Background: Reading your inputs

Those of you who already created a module on APEER will know that it is actually not that easy to access your inputs. Inputs come in as a JSON structure via environment variable called WFE_INPUT_JSON. This could look like this

{% c-block language="json" %}

{
 "wfe_output_params_file": "module_0_0_outputs.json",
 "input_image_path": "/input/cell_image.tiff",
 "threshold_value": 128
}

{% c-line-end %}

That means your code has to read environment variables from the operation system it’s running on. In Python that could look like this

  1. import os
  2. input_json = os.environ['WFE_INPUT_JSON']

But this is not enough since you also need to parse that JSON.

  1. import json
  2. inputs = json.loads(input_json)

Now you would be able to access your inputs in the json object

  1. input_image_path = inputs.pop('input_image_path')

Congratulations you read one of your inputs. But that’s not all since you also need to provide your outputs as inputs to the next module, which you do by generating the above mentioned JSON structure yourself and writing it to the wfe_output_params_file. And you also need to know where to store the files you generate such that the APEER environment can find them after finishing your module. All in all that is too much knowledge you need to have about our system.

Reading inputs and writing outputs easily – Announcing the APEER SDK Family

So that’s why we are announcing the APEER SDK Family. We have been working intensively on three open source APEER SDKs in the languages available as examples on APEER. These SDKs take away all the pain you might have had with reading inputs and writing outputs. All you need now is a single line of code for reading your inputs and a single line of code for each output. You don’t need to know anything about environment variables or JSON structures because the SDKs hide that away. All modules you can use as examples when creating a new module already use those SDKs. We currently have

In case you want to have a look into the code you can. They are all hosted on GitHub. And the best part is: They are all open source under MIT license and, of course, free. That means you can also contribute to them.

Easy module creation with APEER SDKs

Let me quickly show you how easy module creation becomes with the SDKs. The structure and method names are the same for every SDK. So I’ll use the Python SDK as an example here. This can easily be installed via pip install apeer-dev-kit.

The main idea of the SDKs is that it keeps the technical code to communicate with the APEER environment completely seperate from your code. So you can concentrate on the actual image processing problem and test and use your code independently from APEER.

All our examples have a apeer_main file that serves as the entry point to your module and uses the SDK to read the inputs, writes the outputs and just calls your code, which we will just call your_code.py and assume it has a method run(input_image, threshold).

  1. #### apeer_main.py ####
  2. from apeer_dev_kit import adk
  3. import your_code
  4. if __name__ == '__main__':
  5. inputs = adk.get_inputs()
  6. outputs = your_code.run(inputs['input_image_path'], inputs['threshold_value'])
  7. adk.set_output('cell_count', outputs['cell_count'])
  8. adk.set_file_output('thresholded_image', outputs['thresholded_image'])
  9. adk.finalize()

That’s it. That’s all the technical code you need to execute your module on APEER. You can know go ahead and implement your_code.run(...). It actually doesn’t matter how you return the results generated by your code but we recommend a dictionary.

  1. #### your_code.py ####
  2. def run(input_image_path, red, green, blue):
  3. # your processing code goes here ...
  4. # just make sure you save all result files and return their paths
  5. output_file_path = 'result.tiff'
  6. io.imsave(output_file_path, ...)
  7. return {'cell_count': 42, 'thresholded_image': output_file_path}

Ok, there you go. We hope that you will have no more pain creating modules on APEER and can concentrate on the actual problem, like creating a machine learning workflow for Neuroscientists like the one we just published.. We will be working on more SDKs and also aim to solve the other two problems on this list. So stay tuned!

If you have any questions feel free to comment on this post.

Happy coding

Thomas Irmer

Software Developer

Related Posts

Stay in touch with our newsletter!

Thank you! Your submission has been received!

Oops! Something went wrong while submitting the form