Ctrl+K

🐨 Model repo template#

In order for the scivision Python API to be able to load and run a computer vision (CV) model, a GitHub repository containing configuration for one or more models must first be created.

This guide explains how to set up a GitHub repository for your CV model(s) compatible with scivision.

This is also a pre-requisite for adding the model to the scivision “catalog”, enabling other users of scivision to use it. To learn how to do this, consult the contributor page after setting up your model as per this guide.

📚 Contents:

🧱 Model repo structure#

The model repo should be roughly structured as in the diagram below, where exampleuser is the GitHub user and comp_vis is the name of the repo that user has created, containing the model(s).

The essential components required for the model repo to be added to the scivision catalog are marked by an asterisk (*) and the requirements for the model(s) to be load-able via the scivision API are marked with two asterisks (**):

exampleuser/comp_vis
│   README           *
│   LICENSE          *
│   setup.py         **
│   requirements.txt
│
└───.scivision
│   │   model.yml    **
│
└───comp_vis
│   │   model.py     **
│   │   __init__.py
│
└───tests
│   │  test_modelA.py
│   │  test_modelB.py
│   │    ...
│
└───example_data
    │   data_1.csv
    │   data_2.csv
    │   ...

📁 Requirements for the scivision catalog#

The essential components of a scivision model repo include everything required for it to be added to the scivision catalog.

📄 Installation documentation#

A README, which includes detailed instructions on how the model can be installed. Without this, your model(s) will not be accepted for inclusion in the scivision catalog.

📜 Software license#

You should include a LICENSE file in the repository, so that scivision users who come across it can understand the conditions of its usage. For help deciding which license to include, see www.choosealicense.com or check out the section on software licenses in The Turing Way online handbook.

✨ Requirements for the scivision API#

It’s common in Python packages to house the core package code within a child directory of the same name as the repo parent directory, as in the model repo structure diagram above (i.e. comp_vis/comp_vis).

For your model(s) to be loadable by the scivision API, we additionally insist that you include a model.py in this child directory and set up a model.yml config file in a directory called .scivision.

🏗️ Model code#

The script called model.py must either contain the model itself (i.e. code that both trains and runs the model), or import a pre-trained model from elsewhere.

If you wish the model to be compatible with the scivision API, include a class within this script, which contains a prediction function that can be used to run the model on data. You can include multiple classes for different models.

For examples, check out the example model repos section.

🖋️ Model config file#

The default name for the config file included in your repo should be model.yml, and should be kept in the .scivision directory. Take a look at this config from one of our example model repositories: alan-turing-institute/plankton-cefas-scivision:

name: resnet50_cefas_model
url: https://github.com/alan-turing-institute/plankton-cefas-scivision
import: resnet50_cefas
model: resnet50
args:
    label_level: label3_detritus
prediction_fn:
    call: predict_batch
    args:
        X: image
    kwargs:
        batch_size: 3

What do the fields of this model.yml config refer to?

  • name: arbitrary name for the specified model(s)

  • url: points to the repo url

  • import: the folder containing the model code

  • model: the name of the model class specified in “model.py” (within the “import” folder)

  • args: key/value pairs for any arguments of the model class

  • prediction_fn:

    • call: the name of the model class’ prediction function

    • args: key/value pairs for any arguments of the prediction function

    • kwargs: key/value pairs for any key word arguments of the prediction function

It’s also possible to specify multiple models from the same model repository. For an example config that demonstrates this, see scivision-test-plugin/.scivision/model.yml.

🐍 Installability with pip#

You can include a setup.py to enable the model(s) to be installed via pip, which is neccessary for the scivision API to be able to load the model(s). For an explanation of how this works, see this packaging guide for Python. By additionally including a requirements.txt with the required packages for your model, you can make it so these are installed along with the model code.

This example setup.py is taken from alan-turing-institute/plankton-cefas-scivision:

from setuptools import find_packages, setup

requirements = []
with open("requirements.txt") as f:
    for line in f:
        stripped = line.split("#")[0].strip()
        if len(stripped) > 0:
            requirements.append(stripped)

setup(
    name="resnet50_cefas",
    version="0.0.1",
    description="scivision plugin, using CEFAS DSG Plankton ResNet50 model",
    url="https://github.com/alan-turing-institute/plankton-cefas-scivision",
    packages=find_packages(),
    install_requires=requirements,
    python_requires=">=3.7",
)

In scivision, once your model(s) have been included in the scivision catalog, pip installability gives users the option to use the load_pretrained_model function for easy use of your model code. See the 🌟 API docs for details.

💻 Requirements for scivision website#

🎆 Model Thumbnail#

When viewing the model in sci.vision a model thumbnail is required. The thumbnail can be an interesting image explaining the model and that catches the attention of the Scivision user (creativity encouraged!).

  • It must be a 256x256 PNG or JPEG file

  • The file name should be the name of the model as in the catalog

Once you have identified a suitable thumbnail please upload it to the thumbnail models folder.

Once you have identified a suitable thumbnail, follow the 🛠 How to contribute changes to this repository guide to open a pull request to the Scivision GitHub repo which adds the thumbnail image in the src/scivision/catalog/data/thumbnails/models folder.

🗃️ Example model repos#

Here are some example repositories that are set up to work with scivision as per this guide.

Scivision test plugin#

A simple test repository that demonstrates how to set up two models for use with scivision.

CEFAS Plankton resnet50 model#

A repository containing a pretrained ResNet-50 model for classification of plankton and example data.

Note: the example data is included as an intake catalog; see the scivision data repo template for more information.

Classification of plant patches/images using MapReader#

A repository that adapts the MapReader model to classification of plant patches. Example data included.

ODIN#

Object Detection in Images with Noise (ODIN).

On this page
Show Source