openmod-tracker

KO | EN

gitlite — search

#javascript #python #typescript #llm #golang #rust #linux #cli #kubernetes #awesome-list #vue #openai #mcp #open-source

openmod-tracker

(★ 27)

Repository to support analyzing energy system design models based on data

openmod-tracker Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<!--
SPDX-FileCopyrightText: openmod-tracker contributors

SPDX-License-Identifier: MIT
-->

# Open Energy Modelling Tool Tracker (openmod-tracker)

[![REUSE status](https://api.reuse.software/badge/github.com/open-energy-transition/openmod-tracker/)](https://api.reuse.software/info/github.com/open-energy-transition/openmod-tracker/)

Built by [Open Energy Transition](https://openenergytransition.org/), with support by [Breakthrough Energy GRIDS](https://www.breakthroughenergy.org/), this project aims to provide consistent, up-to-date metrics across a range of open energy system modelling tools.

The result of the analysis is available in our [online dashboard](https://openmod-tracker.org/).

>[!NOTE]
>Although we share the same aim -
>that opening up energy models improves quality, transparency, and credibility, leading to better research and policy advice -
>this repository and `openmod-tracker.org` are not affiliated with and have not been endorsed by the [Open Energy Modelling (openmod) Initiative](https://openmod-initiative.org/) community.

## Features

- Merges and filters ESM tools from various inventories:
  - [LF Energy Landscape](https://github.com/lf-energy/lfenergy-landscape)
  - [G-PST OpenTools](https://api.github.com/repos/G-PST/opentools)
  - [Open Sustainable Technology](https://github.com/protontypes/open-sustainable-technology)
  - [Open Energy Modelling Initiative](https://wiki.openmod-initiative.org/wiki/Open_Models)
- Fetches source code repository and package statistics for each tool via the [ecosyste.ms](https://ecosyste.ms) API:
  - Repository creation
  - Repository last change
  - Stars and Forks
  - Number of contributors
  - Dependent repositories
  - Downloads
  - development distribution score (DDS)
- Fetches repository interactions and interacting user data using the [GitHub REST API](https://docs.github.com/en/rest) and classifies users based on string matching.
- Visualises ESM tool statistics in a [Streamlit](https://streamlit.io/)-powered dashboard: <https://openmod-tracker.org/>

## Add a tool

If you're looking to add a tool to the inventory, you can do one (or more) of three things:

1. [create an issue](https://github.com/open-energy-transition/openmod-tracker/issues/new?template=TOOLS.yml).
2. [directly edit our pre-defined list of tools](https://github.com/open-energy-transition/openmod-tracker/edit/main/inventory/pre_compiled_esm_list.csv) to include yours, then open a Pull Request with that change.
3. add your tool to one of the [upstream inventories](#features) from which we collate our final tool list.

Note that your tool may not be appropriate for our inventory.
For examples of tools we have excluded from upstream repositories, see [our exclusion list](https://github.com/open-energy-transition/openmod-tracker/blob/main/inventory/exclusions.csv).

## Our data processing approach

We collect tools listed in the following inventories:

- [LF Energy Landscape](https://github.com/lf-energy/lfenergy-landscape)
- [G-PST OpenTools](https://api.github.com/repos/G-PST/opentools)
- [Open Sustainable Technology](https://github.com/protontypes/open-sustainable-technology)
- [Open Energy Modelling Initiative](https://wiki.openmod-initiative.org/wiki/Open_Models)

Alongside a [pre-compiled list](https://github.com/open-energy-transition/openmod-tracker/blob/main/inventory/pre_compiled_esm_list.csv) of tools (based on [DOI:10.1016/j.rser.2018.11.020](https://doi.org/10.1016/j.rser.2018.11.020) and subsequent searches), we filter the collection to:

- Remove duplicates according to tool name, after normalising the string to lower case and converting all special characters to underscores.
- Remove duplicates according to tool source code URL, after normalising the string to lower case.
- Remove tools without a valid Git repository for their source code (hosted on e.g., GitHub, GitLab, Bitbucket, or a custom domain).
- Remove tools that we know, from manual inspection, are not appropriate for including in our inventory.
  This may be because they are duplicates of the same tool that we cannot catch with our simple detection methods, are supporting tools for another listed tool, or have been catalogued erroneously in the upstream inventory.
  We give the reason for manually excluding a tool in our [list of exclusions](https://github.com/open-energy-transition/openmod-tracker/blob/main/inventory/exclusions.csv).

For the remaining tools, we collect source code repository and package data using <https://ecosyste.ms> APIs.
At this stage, some tools will be filtered out for lack of any data.
Lack of repository data is usually because the repository is no longer available or because it is not publicly accessible (which we deem to be _not_ an open source tool, irrespective of the tool's license).
In very rare cases (<1% of tools in the inventory), the repository host is not indexed by <https://ecosyste.ms>.
If this is the case for your tool and you would like it to be included in this inventory then you should open an issue on the appropriate [ecosyste.ms repository](https://github.com/ecosyste-ms).

Further to data from <https://ecosyste.ms>, we rely on other sources to (1) link repositories with their documentation sites, (2) Fill gaps in package download numbers, and (3) gather data on user interactions.

1. The most likely hosts for documentation are readthedocs.org, Github/Gitlab Pages, or repository Wikis.
   For each repository, we check the most likely URL for each of these as they follow a pre-defined structure.
   If we get a positive match, we link that to the repository.
   This is not perfect; sometimes a project uses an unexpected site URL for their documentation.
1. Most packages are indexed on PyPI, conda-forge or on public Julia package servers.
   For each of these, since <https://ecosyste.ms> data is often missing here, we use direct or third party APIs to query the downloads for the previous month. PyPI download statistics can be fetched programmatically via BigQuery when GCP credentials are available, or loaded from a pre-built CSV fallback file. The file `inventory/output/pypi_downloads.csv` is built manually from the [BigQuery Web UI](https://console.cloud.google.com/bigquery) using the query defined in `inventory/get_download_data.py::query_file_downloads()`. This CSV is used by default when BigQuery credentials are unavailable or when `--use_bigquery=False`. To update this file manually: go to the [BigQuery Web UI](https://console.cloud.google.com/bigquery), copy the SQL query from the `query_file_downloads()` function (around lines 550-600), execute it with your desired package list and time range, then export the results as CSV and save to `inventory/output/pypi_downloads.csv`. This approach avoids authentication issues and is often simpler for periodic manual updates.
1. User interaction data utilises the direct GitHub API.
   This is the API with which much of the <https://ecosyste.ms> database is generated.
   However, they don't store user data unless a user is also a repository owner.
   Direct use of the GitHub API is time intensive due to hourly request limits.
   Therefore, this data (e.g., informing the rate of user interactions over the past 6 months) is updated less frequently than other tools stats.

## Development

### Installation

1. Clone this repository
1. Install [pixi](https://pixi.sh/latest/).
1. Install all project dependencies:

```sh
   pixi install
   ```

### Serve app locally

To serve the streamlit app, call `pixi run -e app serve` from the command line.

### Test

You can run our minimal test suite by calling `pixi run test`.

### Troubleshooting

If the [development version dashboard](https://openmod-tracker.streamlit.app/) is not loading then you can try a few things:

1. Delete the site data for <https://openmod-tracker.streamlit.app> in your browser and refresh the page.
1. Clone this repository locally and run `pixi run test` from the terminal (having followed our [installation instructions](#installation)).
1. If the tests fail, you can debug by setting [traces/breakpoints](https://docs.python.org/3/library/pdb.html) in the app python scripts (`website/**/*.py`) and then run `pixi run -e app serve` in the terminal.
1. If the tests pass and you are a repository maintainer, you can reboot the app from [the streamlit dashboard](https://share.streamlit.io/).

### Refreshing data

Data refreshes are necessary when changing the inventory source code and are recommended at periodic intervals to capture upstream changes.
These are automated with a Github action which runs once a month but you can force a manual update locally following the steps below.

>[!NOTE]
>The below steps leverage [pixi tasks](https://pixi.sh/dev/workspace/advanced_tasks/) which will run all steps in the sequence if there have been changes to the source code or it is the first time you are running the command.
>If you want to just run one step in isolation you will need to call the Python script directly, e.g., `pixi run python inventory/get_stats.py inventory/output/filtered.csv inventory/output/stats.csv`.
>See `pixi.toml` for the command to run for each step.

#### Tool stats

The model inventory and associated statistics can be updated by calling `pixi run get-docs`.
This will get tools from the various upstream inventories, filter them based on [our requirements](#our-data-processing-approach), and then get stats from ecosyste.ms and by speculatively querying known documentation sites.

>[!NOTE]
>To successfully call the ReadTheDocs API, you should add a suitable RTD API token as the `READTHEDOCS_API_TOKEN` environment variable on your device.
>You can store it directly in the repository within a `.env` file and it will be picked up automatically by the workflow.

#### User stats

All user statistics can be updated by calling `pixi run classify-users`.

The repository user interactions can be updated by calling `pixi run get-repo-users`.
This gets _all_ repository data from scratch as the [PyGitHub](https://github.com/PyGithub/PyGithub) API does not allow us to only access the most recent changes.
Therefore, it can be very time consuming.

The repository user details can be updated by calling `pixi run get-user-details`.
It will run `get-repo-users` first if this hasn't already been run.
This will append `inventory/output/user_details.csv` with any new users listed in `inventory/output/repo_interactions.csv`.
As we have already prepared the initial set of users, this should be relatively quick when refreshing.

Finally, our heuristic user classification approach can be applied to the updated user details by calling `pixi run classify-users`.

>[!NOTE]
>To successfully call the GitHub and Gitlab APIs, you should add a suitable API tokens as the `GITHUB_TOKEN` and `GITLAB_TOKEN` environment variables, respectively.
>You can store them directly in the repository within a `.env` file and it will be picked up automatically by the workflow.

#### Code quality assessment

>[!NOTE]
>This feature is currently under review for being added to the dashboard.

We manage forks of all GitHub repositories within our own GitHub organisation in order to have the necessary permissions to undertake code quality assessments.

##### Forking Repositories

Running `pixi run python code_quality/fork_repos.py` forks GitHub repositories to the specified organization and keeps existing forks in sync with their upstream repositories.
An appropriate GitHub token for the organisation, with repository "Administrator" and "Contents" read/write access, must be stored as `GITHUB_TOKEN` in a local `.env` file at runtime.

The script will:

1. Read repository information from the CSV file (which must contain an `html_url` column with GitHub repository URLs)
2. Check if each repository is already forked to the organization
3. Fork repositories that haven't been forked yet
4. Sync existing forks with their upstream repositories
5. Log all operations to the specified log file

##### Running code quality assessment

Running `pixi run python code_quality/sonarcloud.py create openmod-tracker` will create SonarQube cloud platform projects for each of the forked repositories.
For newly created projects, you will then need to trigger an assessment manually on SonarQube as there is no way to do so via the API.
Clicking on the project name is sufficient to start a project.

Running `pixi run python code_quality/sonarcloud.py get-metrics openmod-tracker code_quality/output/metrics.csv` will update the code quality statistics for all existing SonarQube cloud platform projects.

>[!NOTE]
>Only Python and C projects can be analysed automatically by SonarQube.
>Stats will therefore not be available for other other project types.

### Release guideline

We follow calendar versioning (CalVer) in this project.
To deploy new versions of the dashboard to <https://openmod-tracker.org>, follow these steps:

- Update the changelog with changes since the previous release under a heading with the current date in `YYYY-MM-DD` format.
- Update the version in the `pixi.toml` to the current date.
- Open a Pull Request with this change.
- Once status checks pass and the PR is approved and merged, create a tag locally on the latest commit in the main branch with the same name as the changelog heading, e.g.:

```sh
  git checkout main
  git pull
  git tag -a 2025-09-01
  git push --tag
  ```

- Create a release in the GitHub web console linked to the tag with the title `Release YYYY-MM-DD` and list the changes since the previous release.

## License

This project uses [REUSE](https://reuse.software/) to manage its licensing.

For a list of all `openmod-tracker contributors`, see [AUTHORS.md](AUTHORS.md).

The software in this repository is licensed under the [MIT license](LICENSES/MIT.txt).
The generated output data (`inventory/output/*`, `user_analysis/output/*`) are licensed under the [Creative Commons Attribution 4.0 license](LICENSES/CC-BY-4.0.txt) for easier reuse.
Individual configuration or generic files may be licensed [CC0 1.0 Universal](LICENSES/CC0-1.0.txt) and [Creative Commons Attribution ShareAlike 4.0](LICENSES/CC-BY-SA-4.0.txt); these files are marked explicitly either in the file header or in the [REUSE.toml](REUSE.toml) file.

openmod-tracker

openmod-tracker Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

openmod-tracker

openmod-tracker Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README