Skip to content

Commit

Permalink
Updating Community Partners Guide (#426)
Browse files Browse the repository at this point in the history 
* Changes on documentation for CP and Upload

* Update community-partners-guide.md

* Update community-partners-guide.md

Fixing link
  • Loading branch information
@cfusterbarcelo
cfusterbarcelo authored Nov 7, 2024
1 parent 7d8a8b3 commit b4cd643
Show file tree
Hide file tree
Showing 3 changed files with 13 additions and 104 deletions.
3 changes: 1 addition & 2 deletions docs/guides/community-partners-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -168,8 +168,7 @@ api.export(new ImJoyPlugin())

## How to join as a community partner?

Note that in order to contribute resources to the BioImage.IO Model Zoo you do not need to become a community partner. How to contribute resources is described [here](/contribute_models/README.md). The role of a community partner is described [here](/community_partners/README.md).

Note that in order to contribute resources to the BioImage.IO Model Zoo you do not need to become a community partner. How to contribute resources is described [in the developers guide](https://bioimage.io/docs/#/guides/developers-guide). The role of a community partner is described above.

If you are eligible and willing to join as a community partner, please submit a request issue [here](https://github.com/bioimage-io/collection-bioimage-io/issues/new) with relevant information including the following:
1. Description of your software, organization, company or team.
Expand Down
60 changes: 5 additions & 55 deletions docs/guides/community_partners_guide/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -180,69 +180,19 @@ The admin team of BioImage.IO will discuss the request and decide whether to app

Upon approval, we will guide you to follow these steps in order to incorporate your contribution to BioImage.IO:

1. Firstly, please create or choose a GitHub repo for hosting your resource collection that you would like to contribute. We recommend to create a dedicated repository in your organization for this purpose. As an example you might want to take a look at the [ilastik collection](https://github.com/ilastik/bioimage-io-resources/blob/main/collection.yaml).
1. Add a [collection RDF](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/collection_spec_latest.md) in your chosen repository, which lists all resources you would like to contribute. For this, you will also need to prepare the icons of your software or project.
1. Setup CI service for testing your collection RDF. Please refer to [how to setup CI service](/community_partners/how_to_join?id=how-to-setup-ci-service-for-a-community-partners39-repo).
1. Make a PR (or an issue) in the BioImage.IO Collection repo to link your collection to the [collection_rdf_template.yaml](https://github.com/bioimage-io/collection-bioimage-io/blob/main/collection_rdf_template.yaml)(under `config.partners`). We only require the link to your collection RDF here and need to agree on a partner id for you.
1. To make the maintainance easier, we also ask you to add one of the admin member as collabrators in your resource collection repository. This will make it easier for us to help you maintaining your collection, and keep synchronized in case we make changes to the specification.
1. First, you will need to create a PR to insert relevant metadata into [bioimageio_collection_config.json](https://github.com/bioimage-io/collection/blob/4087336ad00bff0198f5de83c94aa13be357840d/bioimageio_collection_config.json) under `"partners"`.
Checkout [ilastik partner entry](https://github.com/bioimage-io/collection/blob/4087336ad00bff0198f5de83c94aa13be357840d/bioimageio_collection_config.json#L283-L301) for an example.
2. Then, you will need to add the Community Partner Compatibility Checks. Any community partner is invited to add a GitHub Actions workflow in this repo (please make a PR) that generates reports on its software compatibility with new and updated resources in the bioimage.io collection.
See [ilastik compatibility checks worfklow](https://github.com/bioimage-io/collection/blob/main/.github/workflows/check_compatibility_ilastik.yaml) for an example.


## How to register a software or application?

A community partner can have one or multiple associated software, you can register them in the collection RDF file of your repository (see the previous section about creating a collection repository). A software is categorized as "Application" in the BioImage Model Zoo. The first thing to do is to create an application file in the [ImJoy plugin file format](https://imjoy.io/docs/#/development?id=plugin-file-format). This basically allows you define a landing page for your software with executable features such as download or test run buttons for your software. The most common use case is to create a landing page for your software. Each software will have an unique id, typically in the format of `<community partner id>/<software name>`. Every model can add links (manually when upload or automatically via the CI) to the software. For each model, the user can click the link on top of the model card, and the landing page will be loaded. Through the ImJoy plugin mechanism, the context information contains the current model information will be injected to the landing page, it's up to the developer who made the software app to decided how to use those information.

To see an example, you can find the [source for the ilastik app](https://github.com/ilastik/bioimage-io-resources/blob/main/src/ilastik-app.imjoy.html) and also the corresponding entry in the collection file [here](https://github.com/ilastik/bioimage-io-resources/blob/2d2f1b12b185b1b880bfb679ed2aa981bf88d1ed/collection.yaml#L45-L59).

## How to setup CI service for a community partners' repo?

The CI service is an useful tool to autotomize the maintenance of the model repo and ensure a high quality for all BioImage.IO resources.
You basically need to add some testing scripts to your repo and configure it using CI services such as Github Actions, Travis or Circle CI etc. The testing script will be triggered by a new commit or pull request to the repo. For simplicity, we recommend Github Actions which can be triggered by adding a yaml file under the folder `.github/workflows`. For example, here is an example file [.github/workflows/compile-manifest.yml](https://github.com/deepimagej/models/blob/master/.github/workflows/compile-manifest.yml) that we used to verify the model spec in the central repo.

There are at least three steps are recommended:
1. Run the [`compile_model_manifest.py`](https://github.com/bioimage-io/bioimage-io-models/blob/master/manifest.bioimage.io.yaml) script to make sure the manifest can be correctly compiled.
2. Verify the yaml files according to model spec with [.github.com/bioimage-io/python-bioimage-io](https://github.com/bioimage-io/python-bioimage-io).
3. If possible, test every models added to the repo.

As a start, you can use [.github/workflows/compile-manifest.yml](https://github.com/deepimagej/models/blob/master/.github/workflows/compile-manifest.yml) as your template.

See more information here: https://github.com/bioimage-io/collection-bioimage-io#contribute-resource-test-summaries


## Report User Analytics

We provide the analytics service to help consumer software to keep track of their resource (including model, datasets etc.) downloads.

### Report resource downloads

To help us maintain the resource download statistics at BioImage.IO, please send a report to our analytics service when a resource item is downloaded.

Under the hood, we use [matomo](https://matomo.org) to track the user downloads. It provide tracking api in various programming languages and frameworks, see here: https://developer.matomo.org/api-reference/tracking-api.

The easiest way to report a model download is to send an http request to matomo.


You need to construct an URL to report the download:

`https://bioimage.matomo.cloud/matomo.php?download=https://doi.org/[MODEL DOI]&idsite=1&rec=1&r=646242&h=13&m=35&s=20&url=http://bioimage.io/#/?id=[MODEL DOI]&uadata={"brands":[{"brand":"[CONSUMER ID]","version":"[CONSUMER VERSION]"}]}`


In the above URL, you need to provide the following parameters:
* `[MODEL DOI]`: The resource doi, it should be similar to `10.5281/zenodo.55555555`. Also note that Zenodo deposit has concept doi and version doi, we recommend to use the concept doi such that the downloads across versions can be aggregated.
* `[CONSUMER ID]`: The id for the registered consumer software, for example: `ilastik` or `deepimagej`.
* `[CONSUMER VERSION]`: The software version for the consumer software.


### Obtain resource usage statistics
You can get the user statistics from via the HTTP API, for example:
* To get the global statistics of the whole website: `https://bioimage.matomo.cloud/?module=API&method=Live.getCounters&idSite=1&lastMinutes=30&format=JSON&token_auth=anonymous`
* To get the number of downloads: `https://bioimage.matomo.cloud/?module=API&method=Actions.getDownloads&idSite=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous`
* To get the number of downloads for a specific resource (via DOI): ```https://bioimage.matomo.cloud/?module=API&method=Actions.getDownload&downloadUrl=https://doi.org/`[MODEL DOI]`&idSite=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous```. To see an example, click here: https://bioimage.matomo.cloud/?module=API&method=Actions.getDownload&downloadUrl=https://doi.org/test&idSite=1&idCustomReport=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous

For more detailed API, see here: https://developer.matomo.org/api-reference/reporting-api


Please note that the reports are not processed in realtime, this means you won't see the statistics for your reports immediately:
- In the report request, we need to configure the date properly. For example, we can change period to `year` and date to `2023-03-01` (see here: https://developer.matomo.org/api-reference/Piwik/Period)
- The report will only be generated every 15 minutes: https://matomo.org/faq/general/faq_41/ so we won't see the report immediately.

## BioImage.IO Partner Collection

Expand Down
54 changes: 7 additions & 47 deletions docs/guides/developers-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ In some cases, the model may need additional files.

### Model contribution requirements

- Follow the [BioImage.IO Model Resource Description File Specification (RDF)](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/user_docs/model_descr_latest.md) with `format_version>= 0.4.5`.
- Follow the [BioImage.IO Model Resource Description File Specification (RDF)](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/user_docs/model_descr_latest.md).
- The model is expected to be cross-compatible among the consumer software, and should always run on at least one.
- The model should be well documented (i.e., human readable name and rich description tailored for life-scientists, citations)
- The model should be public and can be used by anyone under the chosen licensing conditions.
Expand All @@ -50,53 +50,13 @@ Two options:

**2. Upload the model to the BioImage Model Zoo**

To upload a model to the BioImage Model Zoo, you have a tutorial video of the process step by step available [here](https://oc.embl.de/index.php/s/JBWwJGgsXh0vYM6).

<img src="./guides/contribute_model.png" align="center" width="1000"/>

For a detailed explanation, follow these steps:
1. In [BioImage.IO](https://bioimage.io/), click on `+Upload` and follow the steps:

2. Log in to Zenodo and give access to the BioEngine application. You will see an automatic message once you are logged in. If not, refresh the page. This step needs to be done only for the first time you upload a model.

3. Upload your model RDF.
<img src="./guides/upload_1.png" align="center" width="500"/>

4. Complete the missing fields.
<img src="./guides/upload_2.png" align="center" width="500"/>
<img src="./guides/upload_3.png" align="center" width="500"/>

5. A [Pull Request (PR)](https://github.com/bioimage-io/collection-bioimage-io/pulls/bioimageiobot) is generated (this process may take some minutes). In the PR, the model is tested by a Continuous Integration (CI) workflow for its technical correctness. and reviewed by a maintainer from the BioImage.IO team. This PR is aimed for further discussions between model contributors and the BioImage.IO team.

6. Once the model passes all checks and has the approval of a maintainer, it will be added to the BioImage.IO collection and displayed in the webpage (this process may take some minutes).

### Upload a model through Zenodo
**Note:** This tutorial provides a temporary solution for uploading models to the BioImage Model Zoo via Zenodo while the upload feature on the BioImage.IO website is being fixed.

This tutorial will guide you through the process of uploading a model to the BioImage Model Zoo community on Zenodo. The BioImage Model Zoo project aims to collect and share bioimage analysis models, and your contribution is valuable. Follow the steps below to upload your model.

1. Open your web browser and navigate to the Zenodo website at [https://zenodo.org/](https://zenodo.org). You need to create a Zenodo account if you do not have one.
<!-- ![Zenodo initial page](contribute_models/zenodo_upload_01.png) -->
<img src="./guides/zenodo_upload_01.png" alt="Zenodo initial page" align="center" width="1000"/>

2. On the right, close to your username, click the "New upload" button to begin the model upload process. Make sure that the repository is set as public.
The files in the BioImage.IO zip have to be uploaded one-by-one (See the example in the image below). Note that you can drag & drop all together at once.
<!-- ![New upload](contribute_models/zenodo_upload_04.png) -->
<img src="./guides/zenodo_upload_04.png" alt="New upload" align="center" width="1000"/>

3. Add `bioimage.io` on Keywords and subjects. This is crucial for us to identify your submission.
<!-- ![Find BioImage.IO community](contribute_models/zenodo_upload_03.png) -->
<img src="./guides/zenodo_upload_03.png" alt="Find BioImage.IO community" align="center" width="1000"/>

4. Follow the on-screen instructions to provide the required information about your model. Make sure to include a clear description, relevant tags, and any necessary documentation.

5. Once finished, click on Submit.

6. Your model will be proposed as a new contribution to the BioImage Model Zoo automatically. If the model passes all the tests, it will be automatically displayed in the Zoo. If the model does not pass the test, the GitHub users indicated in `maintainers` in the `rdf.yaml` file will be noitified through GitHub. This process can take 12-24h.

You've successfully uploaded your model to the BioImage Model Zoo community on Zenodo. Thank you for your contribution to the BioImage Model Zoo project. Remember that this is a temporary solution while the upload feature on the BioImage.IO website is being fixed. We appreciate your patience and support!
1. Visit the [bioimageio](https://bioimage.io) website and click the "Upload" button to access the model upload page.
2. Log in using your Google or GitHub account.
3. Upload a resource file, which can be a single zip archive containing all necessary files, or you can select/drag and drop individual files. The 'rdf.yaml' file needed for uploading can be created in the next step.
4. In the "Review and Edit Your Model" section, provide all necessary metadata to create the 'rdf.yaml' file. Ensure to give a descriptive name and description, and add the maintainer responsible for the upload. See the Model Documentation below for details such as how to name your model.
5. Once ready, click "Validate" and wait for your model to be reviewed.

All models and resources in the BioImage Model Zoo undergo testing and validation before being accepted for publication. Some modifications may be required to meet the publication specifications after uploading.

### Model Documentation
#### Model naming
Expand Down

0 comments on commit b4cd643

Please sign in to comment.