For Developers

Astrapia is a fully open-source project. Anyone is welcome to contribute to the project. This page provides some guidelines for adding new Explainers, Samplers and Transfer functions to the main Astrapia codebase for everyone to use. This might be especially useful for developers contributing new Explainers as users will be able to use and understand your Explainer’s advantages.

Documentation

Due to the size of the Astrapia codebase, this extensive documentation is compiled to help new users get started. If you add new functionality, please document it in the appropriate section. The following segment provides you with the tools needed to get started working on the documentation.

Astrapia is using sphinx and reStructuredText to generate the documentation you are reading.

To improve on it, navigate to the docs directory. To add content, look into the docs/source directory and add your content at the appropriate place. To see your changes on a linux based distribution, run

$ make html

On Windows, run

$ ./Makefile html

The documentation will be generated in the docs/build/html directory. Use a regular html viewer such as firefox or chrome to view the documentation. To build the documentation to other formats such as PDF or LaTeX, view the sphinx documentation

Explainers

Astrapia aims to provide a large set of off-the-shelf explainers. The more explainers and types of explainers we provide, the more users will learn about the advantages and disadvantages of their own explainers. As such, we welcome you to contribute your own explainers to the Astrapia codebase.

To add your own explainer, visit the astrapia/explainers directory and add a new python file containing your explainer. Then, add your explainer to the astrapia/explainers/__init__.py file.

You should now be able to import your explainer with

from astrapia.explainers import MyExplainer

Please make sure to document your explainer both in-code and in the documentation.

Samplers

To add your own sampler, visit the astrapia/samplers directory and add a new python file containing your sampler.

To simplify the usage of your sampler, you can add your sampler to the explain_representative function in the astrapia/comparator.py file. Otherwise, you can just use your sampler object directly.

Please make sure to document your sampler both in-code and in the documentation.

Transfer Functions

Evaluating Explainers is difficult. No metric can fully represent the quality of an explainer. While astrapia provides a few metrics to evaluate on, new explainers might require a new set of metrics. While you can define them for each explainer individually, transfer functions allow you to define them indirectly.

To add new transfer functions, visit the astrapia/transfer_functions.py file. Add your new indirect metrics to the generate_default_transfer_functions method.

The following would be an example of adding the area_absolute_log metric defined in the Transfer document as a general metric.

# astrapia/transfer_functions.py

import math # import math for the log function

def generate_default_transfer_functions(add_transfer):

    # [...] other transfer functions

    # define a new metric depending on the *area_absolute* metric
    def area_absolute_log(area_absolute):
        return math.log(area_absolute()) # remember, metrics are functions (not values)
    add_transfer(area_norm) # add the metric to the global transfer module