Skip to main content

Toolkit to build algorithms for model recovery

Project description

AutoRA Template

Quickstart Guide

Create GitHub Repository

You should create a GitHub repository from the root folder of this project:

  • Create a new repository on GitHub (a sensible name for the repository would be autora-theorist-toolkit)
  • Follow the guide under …or push an existing repository from the command line

Virtual Environment

Install this in an environment using your chosen package manager. In this example we are using virtualenv

Install:

Create a new virtual environment:

virtualenv venv

Note: You want to ensure that the python version matches that of autora. If necessary you can specify the respective python version directly, e.g., virtualenv venv --python=python3.9

Activate it:

source venv/bin/activate

Install Dev Dependencies

Use pip install to install the current project (".") in editable mode (-e) with dev-dependencies ([dev]):

pip install -e ".[dev]"

Note: You may install new dependencies via pip install packagename inside your virtual environment. If those dependencies are vital to your package, you will have to add them to the pyproject.toml (see Step 6 of the Contribution Guide).

Contribution Guide

Theorist

An sklearn regressor that returns an interpretable model relating experiment conditions $X$ to observations $Y$.
Example: The Bayesian Machine Scientist (Guimerà et al., 2020, in Science Advances) returns an equation governing the relationship between $X$ and $Y$.

Step 1: Implement Your Code

You may now add your code to src/autora/theorist/toolkit/__init__.py file. You may also add additional files in this folder. Just make sure to import the core function or class of your feature in the __init__.py if it is implemented elsewhere.

Step 2 (Optional): Add Tests

It is highly encouraged to add unit tests to ensure your code is working as intended. These can be doctests or test cases in tests/test_toolkit.py.

Note: Tests are required if you wish that your feature becomes part of the main autora package. However, regardless of whether you choose to implement tests, you will still be able to install your package separately, in addition to autora.

Step 3 (Optional): Add Documentation

It is highly encouraged that you add documentation of your package in your docs/index.md. You can also add new pages in the docs folder. Update the mkdocs.yml file to reflect structure of the documentation. For example, you can add new pages or delete pages that you deleted from the docs folder.

Note: Documentation is required if you wish that your feature becomes part of the main autora package. However, regardless of whether you choose to write documentation, you will still be able to install your package separately, in addition to autora.

Step 4: Add Dependencies

In pyproject.toml add the new dependencies under dependencies

Install the added dependencies

pip install -e ".[dev]"

Step 5: Publish Your Package

Once your project is implemented, you may publish it as subpackage of AutoRA. If you have not thoroughly vetted your project or would otherwise like to refine it further, you may nervous about the state of your package–you will be able to publish it as a pre-release, indicating to users that the package is still in progress.

Step 5.1: Update Metadata

To begin publishing your package, update the metadata under project in the pyproject.toml file to include

  • name
  • description
  • author-name
  • author-email Also, update the URL for the repository under project.urls.

Step 5.2 Publish via GitHub Actions

To automate the publishing process for your package, you can use a GitHub action:

  • Add a github secret in your repository named PYPI_API_TOKEN, that contains a PyPI token of your account
  • Add the GitHub action to the .github/workflows directory: For example, you can use the default publishing action:
    • Navigate to the actions on the GitHub website of your repository.
    • Search for the Publish Python Package action and add it to your project
  • Create a new release: Click on create new release on the GitHub website of your repository.
  • Choose a tag (this is the version number of the release. If you didn't set up dynamic versioning it should match the version in the pyproject.toml file)
  • Generate release notes automatically by clicking generate release, which adds the markdown of the merged pull requests and the contributors.
  • If this is a pre-release check the box set as pre-release
  • Click on publish release

Step 6: Add the package to autora

Once your package is working and published, you can make a pull request on autora to have it vetted and added to the "parent" package. To do so, you'll need to clone the parent repository, add your package to it as an optional dependency, and make sure your documentation is imported. Then create a pull request with the changes to let us know about your contribution.

Add the package as optional dependency

In the pyproject.toml file of your cloned autora package, add an optional dependency for your new package in the [project.optional-dependencies] section:

example-contribution = ["autora-example-contribution==1.0.0"]

!!! success Ensure you include the version number.

Add the example-contribution to be part of the corresponding all-contribution-type dependencies:

all-contribution-type = [
    ...
    "autora[example-contribution]",
    ...
]

Add documentation from the package repository

Import your documentation in the mkdocs.yml of the autora package:

- User Guide:
  - Contribution Type:
    - Overview: 'contribution-type/overview.md'
    ...
    - Example Contribution: '!import https://github.com/example-contributor/example-contribution/?branch=v1.0.0&extra_imports=["mkdocs/base.yml"]'
    ...

Questions & Help

If you have any questions or require any help, please add your question in the Contributor Q&A of AutoRA Discussions. We look forward to hearing from you!

autora-theorist-toolkit

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

autora-theorist-toolkit-0.2.3.tar.gz (27.1 kB view details)

Uploaded Source

Built Distribution

autora_theorist_toolkit-0.2.3-py3-none-any.whl (24.3 kB view details)

Uploaded Python 3

File details

Details for the file autora-theorist-toolkit-0.2.3.tar.gz.

File metadata

File hashes

Hashes for autora-theorist-toolkit-0.2.3.tar.gz
Algorithm Hash digest
SHA256 3e28888c34f13d9009fe9327d03365b6af19bbec865c388cd4daaf90f6b15b3f
MD5 3dd2c0552e52af01ca5bdbd1a3118609
BLAKE2b-256 692e51c53ece7eb486cf6ee449ab4205dde3d7f3c57f89b5c843122d5e53f51a

See more details on using hashes here.

File details

Details for the file autora_theorist_toolkit-0.2.3-py3-none-any.whl.

File metadata

File hashes

Hashes for autora_theorist_toolkit-0.2.3-py3-none-any.whl
Algorithm Hash digest
SHA256 e013bf6a36a5c50d98ce675731bcb90eda61a9b69cf211d6a65802dbc2cdbf00
MD5 8b9129df3c8903e1fc239a892769a400
BLAKE2b-256 ffc9a9e694a6600da0adda107d02a69c1d326e7280339d4b1a5e61585589f02f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page