OSOS retrieves timeseries data and summary statistics on the usage and activity of open source repositories.

Note that github usage data (clones and views) are only available for repositories that you have push permissions to, and they are only available for the last two weeks. Also note that OSOS needs a github API token stored in the system environment variable GITHUB_TOKEN or the github secret GIT_API_TOKEN to pull data from github.

See the OSOS CLI documentation for details on how to run OSOS from the command line. If you want to set up a chron job to regularly pull and save usage statistics from your projects, see the instructions on how to fork OSOS below.

OSOS can be installed via pip: pip install nrel-osos or by cloning the repo and doing a developer install: pip install -e . from within the repo directory.

After installing, try calling the command line help page with osos --help to see the run options. There are currently two CLI commands: one for running the osos utility (osos run --help) and one for plotting the osos data files (osos plot --help).

You can also run osos from python directly, which will give you more detailed information on a given repository. Try launching binder and navigating to the osos example notebook. You will need your own github api token to run the notebook.

Finally, you can run OSOS from a config file for several repositories at once. We have a chron job set up using github actions to run a job every Monday morning. If you want to set up your own chron job you will have to fork and configure the OSOS repository (see details in the section below). Data produced from the github action is saved in the osos data directory and plots are saved to the osos plots directory. For example, here is the cumulative pypi downloads for reV, one of our open source projects:

*note that we started tracking OSOS data in October of 2021 and have no data on pypi downloads prior to this date.

If you fork the repo, you can schedule a github action workflow to automatically pull usage statistics for projects every Monday morning. To fork OSOS, follow these steps:

1. Go to the OSOS github page and click "Fork" in the top right
2. Fork the repository into a personal github account or organization
3. Create a github personal access token
4. Add the access token as a secret to your forked repository with the name GIT_API_TOKEN
5. Update your OSOS config file with the repositories you want to track
6. Set up your Update OSOS Data github action and try running it in the github actions interface
7. Check back when your update job is scheduled to run and make sure it actually ran successfully
8. Let us know how it goes and feel free to contribute improvements or bug fixes!