{"id":20212,"name":"gridemissions","description":"Displays the hourly carbon footprint of the US electricity system.","url":"https://github.com/jdechalendar/gridemissions","last_synced_at":"2026-04-23T22:30:37.392Z","repository":{"id":38119614,"uuid":"296957761","full_name":"jdechalendar/gridemissions","owner":"jdechalendar","description":"Tools for power sector emissions tracking","archived":false,"fork":false,"pushed_at":"2024-07-25T10:25:28.000Z","size":21733,"stargazers_count":40,"open_issues_count":8,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-06T14:04:02.835Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdechalendar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-09-19T21:55:28.000Z","updated_at":"2026-02-05T08:18:23.000Z","dependencies_parsed_at":"2023-09-21T19:24:24.817Z","dependency_job_id":"3453b114-a4f0-48ac-bb0a-e2689f2801ba","html_url":"https://github.com/jdechalendar/gridemissions","commit_stats":{"total_commits":64,"total_committers":4,"mean_commits":16.0,"dds":0.171875,"last_synced_commit":"66cb57f899bd3dd53b96d76a2d602c3c6b389cc5"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/jdechalendar/gridemissions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdechalendar","download_url":"https://codeload.github.com/jdechalendar/gridemissions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31560476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"owner":{"login":"jdechalendar","name":"Jacques de Chalendar","uuid":"20404131","kind":"user","description":"","email":"","website":"https://jdechalendar.su.domains","location":null,"twitter":null,"company":"Stanford University","icon_url":"https://avatars.githubusercontent.com/u/20404131?u=1f2472140989b273293073924fb6718a75de3182\u0026v=4","repositories_count":13,"last_synced_at":"2024-06-11T16:17:35.836Z","metadata":{"has_sponsors_listing":false},"html_url":"https://github.com/jdechalendar","funding_links":[],"total_stars":87,"followers":31,"following":0,"created_at":"2022-11-05T21:06:54.025Z","updated_at":"2024-06-11T16:17:40.528Z","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdechalendar","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdechalendar/repositories"},"packages":[{"id":9158898,"name":"gridemissions","ecosystem":"pypi","description":null,"homepage":null,"licenses":"mit","normalized_licenses":["MIT"],"repository_url":"https://github.com/jdechalendar/gridemissions","keywords_array":[],"namespace":null,"versions_count":8,"first_release_published_at":"2024-03-02T21:31:02.000Z","latest_release_published_at":"2024-07-07T12:49:34.000Z","latest_release_number":"0.1.10","last_synced_at":"2026-04-06T14:01:06.005Z","created_at":"2024-03-02T21:32:53.520Z","updated_at":"2026-04-06T14:01:06.005Z","registry_url":"https://pypi.org/project/gridemissions/","install_command":"pip install gridemissions --index-url https://pypi.org/simple","documentation_url":"https://gridemissions.readthedocs.io/","metadata":{"funding":null,"documentation":null,"classifiers":[],"normalized_name":"gridemissions","project_status":null},"repo_metadata":{"id":38119614,"uuid":"296957761","full_name":"jdechalendar/gridemissions","owner":"jdechalendar","description":"Tools for power sector emissions tracking","archived":false,"fork":false,"pushed_at":"2024-06-10T17:55:13.000Z","size":11900,"stargazers_count":35,"open_issues_count":15,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-06-11T20:53:46.423Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdechalendar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-19T21:55:28.000Z","updated_at":"2024-06-13T04:08:10.249Z","dependencies_parsed_at":"2023-09-21T19:24:24.817Z","dependency_job_id":"3453b114-a4f0-48ac-bb0a-e2689f2801ba","html_url":"https://github.com/jdechalendar/gridemissions","commit_stats":{"total_commits":64,"total_committers":4,"mean_commits":16.0,"dds":0.171875,"last_synced_commit":"66cb57f899bd3dd53b96d76a2d602c3c6b389cc5"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdechalendar","download_url":"https://codeload.github.com/jdechalendar/gridemissions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":206874882,"owners_count":14636829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"},"owner_record":{"login":"jdechalendar","name":"Jacques de Chalendar","uuid":"20404131","kind":"user","description":"","email":"","website":"https://jdechalendar.su.domains","location":null,"twitter":null,"company":"Stanford University","icon_url":"https://avatars.githubusercontent.com/u/20404131?u=1f2472140989b273293073924fb6718a75de3182\u0026v=4","repositories_count":13,"last_synced_at":"2024-06-11T16:17:35.836Z","metadata":{"has_sponsors_listing":false},"html_url":"https://github.com/jdechalendar","funding_links":[],"total_stars":87,"followers":31,"following":0,"created_at":"2022-11-05T21:06:54.025Z","updated_at":"2024-06-11T16:17:40.528Z","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdechalendar","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdechalendar/repositories"},"tags":[{"name":"v0.1.3","sha":"ab43c905705fa8961af399a2a84d3cb85a27b29b","kind":"commit","published_at":"2024-03-03T02:55:50.000Z","download_url":"https://codeload.github.com/jdechalendar/gridemissions/tar.gz/v0.1.3","html_url":"https://github.com/jdechalendar/gridemissions/releases/tag/v0.1.3","dependencies_parsed_at":null,"dependency_job_id":null,"tag_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags/v0.1.3","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags/v0.1.3/manifests"},{"name":"v0.1.2","sha":"dbb9b9c3801c9c8b3ab1adefe81d5446c72e16e3","kind":"commit","published_at":"2024-03-02T22:26:15.000Z","download_url":"https://codeload.github.com/jdechalendar/gridemissions/tar.gz/v0.1.2","html_url":"https://github.com/jdechalendar/gridemissions/releases/tag/v0.1.2","dependencies_parsed_at":null,"dependency_job_id":null,"tag_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags/v0.1.2","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags/v0.1.2/manifests"},{"name":"v0.1.1","sha":"01cbe90e19a65b1f927277fcdc6c62e7050de6d2","kind":"commit","published_at":"2024-03-02T21:26:29.000Z","download_url":"https://codeload.github.com/jdechalendar/gridemissions/tar.gz/v0.1.1","html_url":"https://github.com/jdechalendar/gridemissions/releases/tag/v0.1.1","dependencies_parsed_at":null,"dependency_job_id":null,"tag_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags/v0.1.1","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags/v0.1.1/manifests"},{"name":"v0.1.0","sha":"120f57cba7c37527b296f328363a8c04a96780bd","kind":"commit","published_at":"2023-11-14T20:26:06.000Z","download_url":"https://codeload.github.com/jdechalendar/gridemissions/tar.gz/v0.1.0","html_url":"https://github.com/jdechalendar/gridemissions/releases/tag/v0.1.0","dependencies_parsed_at":null,"dependency_job_id":null,"tag_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags/v0.1.0","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/tags/v0.1.0/manifests"}]},"repo_metadata_updated_at":"2024-09-07T19:53:41.048Z","dependent_packages_count":0,"downloads":53,"downloads_period":"last-month","dependent_repos_count":0,"rankings":{"downloads":null,"dependent_repos_count":64.44437535661513,"dependent_packages_count":9.767962429225614,"stargazers_count":null,"forks_count":null,"docker_downloads_count":null,"average":37.10616889292037},"purl":"pkg:pypi/gridemissions","advisories":[],"docker_usage_url":"https://docker.ecosyste.ms/usage/pypi/gridemissions","docker_dependents_count":null,"docker_downloads_count":null,"usage_url":"https://repos.ecosyste.ms/usage/pypi/gridemissions","dependent_repositories_url":"https://repos.ecosyste.ms/api/v1/usage/pypi/gridemissions/dependencies","status":null,"funding_links":[],"critical":null,"issue_metadata":{"last_synced_at":"2024-09-07T18:32:26.513Z","issues_count":31,"pull_requests_count":35,"avg_time_to_close_issue":3862533.533333333,"avg_time_to_close_pull_request":334856.02857142856,"issues_closed_count":15,"pull_requests_closed_count":35,"pull_request_authors_count":2,"issue_authors_count":8,"avg_comments_per_issue":0.9354838709677419,"avg_comments_per_pull_request":0.2857142857142857,"merged_pull_requests_count":33,"bot_issues_count":0,"bot_pull_requests_count":0,"past_year_issues_count":27,"past_year_pull_requests_count":23,"past_year_avg_time_to_close_issue":3079135.75,"past_year_avg_time_to_close_pull_request":305163.60869565216,"past_year_issues_closed_count":12,"past_year_pull_requests_closed_count":23,"past_year_pull_request_authors_count":1,"past_year_issue_authors_count":4,"past_year_avg_comments_per_issue":0.8888888888888888,"past_year_avg_comments_per_pull_request":0.34782608695652173,"past_year_bot_issues_count":0,"past_year_bot_pull_requests_count":0,"past_year_merged_pull_requests_count":22,"issues_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/issues","maintainers":[{"login":"jdechalendar","count":54,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/jdechalendar"}],"active_maintainers":[{"login":"jdechalendar","count":44,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/jdechalendar"}]},"versions_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/packages/gridemissions/versions","version_numbers_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/packages/gridemissions/version_numbers","dependent_packages_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/packages/gridemissions/dependent_packages","related_packages_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/packages/gridemissions/related_packages","codemeta_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/packages/gridemissions/codemeta","maintainers":[{"uuid":"jdechalendar","login":"jdechalendar","name":null,"email":null,"url":null,"packages_count":1,"html_url":"https://pypi.org/user/jdechalendar/","role":"Owner","created_at":"2024-03-02T21:33:57.625Z","updated_at":"2024-03-02T21:33:57.625Z","packages_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/maintainers/jdechalendar/packages"}],"registry":{"name":"pypi.org","url":"https://pypi.org","ecosystem":"pypi","default":true,"packages_count":835813,"maintainers_count":356904,"namespaces_count":0,"keywords_count":270194,"github":"pypi","metadata":{"funded_packages_count":53084},"icon_url":"https://github.com/pypi.png","created_at":"2022-04-04T15:19:23.364Z","updated_at":"2026-04-05T05:05:39.368Z","packages_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/packages","maintainers_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/maintainers","namespaces_url":"https://packages.ecosyste.ms/api/v1/registries/pypi.org/namespaces"}}],"commits":{"id":1254193,"full_name":"jdechalendar/gridemissions","default_branch":"main","total_commits":99,"total_committers":4,"total_bot_commits":0,"total_bot_committers":0,"mean_commits":24.75,"dds":0.14141414141414144,"past_year_total_commits":0,"past_year_total_committers":0,"past_year_total_bot_commits":0,"past_year_total_bot_committers":0,"past_year_mean_commits":0.0,"past_year_dds":0.0,"last_synced_at":"2026-04-06T14:02:39.433Z","last_synced_commit":"696838bc82c74aa40ab54206b36aec2026908a2d","created_at":"2023-03-27T10:59:34.624Z","updated_at":"2026-04-06T14:02:26.346Z","committers":[{"name":"Jacques de Chalendar","email":"jdechalendar@stanford.edu","login":"jdechalendar","count":85},{"name":"Jacques de Chalendar","email":"ec2-user@ip-172-31-12-155.us-east-2.compute.internal","login":null,"count":11},{"name":"Elijah J. Passmore","email":"elijahjpassmore@elijahjpassmore.com","login":"eljpsm","count":2},{"name":"Jacques de Chalendar","email":"ec2-user@ip-172-31-29-186.us-east-2.compute.internal","login":null,"count":1}],"past_year_committers":[],"commits_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/commits","host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-04-08T00:00:24.542Z","repositories_count":6212203,"commits_count":914906080,"contributors_count":35345446,"owners_count":1143114,"icon_url":"https://github.com/github.png","host_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories"}},"issues_stats":{"full_name":"jdechalendar/gridemissions","html_url":"https://github.com/jdechalendar/gridemissions","last_synced_at":"2026-04-06T14:00:41.835Z","status":"error","issues_count":23,"pull_requests_count":33,"avg_time_to_close_issue":3862533.533333333,"avg_time_to_close_pull_request":355146.2121212121,"issues_closed_count":15,"pull_requests_closed_count":33,"pull_request_authors_count":2,"issue_authors_count":8,"avg_comments_per_issue":1.173913043478261,"avg_comments_per_pull_request":0.30303030303030304,"merged_pull_requests_count":31,"bot_issues_count":0,"bot_pull_requests_count":0,"past_year_issues_count":0,"past_year_pull_requests_count":0,"past_year_avg_time_to_close_issue":null,"past_year_avg_time_to_close_pull_request":null,"past_year_issues_closed_count":0,"past_year_pull_requests_closed_count":0,"past_year_pull_request_authors_count":0,"past_year_issue_authors_count":0,"past_year_avg_comments_per_issue":null,"past_year_avg_comments_per_pull_request":null,"past_year_bot_issues_count":0,"past_year_bot_pull_requests_count":0,"past_year_merged_pull_requests_count":0,"created_at":"2023-05-09T10:37:13.688Z","updated_at":"2026-04-06T14:00:41.836Z","repository_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions","issues_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdechalendar%2Fgridemissions/issues","issue_labels_count":{},"pull_request_labels_count":{"dependencies":1,"docker":1},"issue_author_associations_count":{"OWNER":13,"NONE":8,"CONTRIBUTOR":1},"pull_request_author_associations_count":{"OWNER":48,"CONTRIBUTOR":2,"NONE":1},"issue_authors":{"jdechalendar":13,"maoudia-via":3,"eljpsm":1,"nelsonauner":1,"gschivley":1,"zaneselvans":1,"klo9klo9kloi":1,"gailin-p":1},"pull_request_authors":{"jdechalendar":47,"eljpsm":2,"dependabot[bot]":1,"hcssmith":1},"host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-04-08T00:00:09.900Z","repositories_count":14147583,"issues_count":34546263,"pull_requests_count":112868491,"authors_count":11230090,"icon_url":"https://github.com/github.png","host_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories","owners_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/owners","authors_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors"},"past_year_issue_labels_count":{},"past_year_pull_request_labels_count":{},"past_year_issue_author_associations_count":{},"past_year_pull_request_author_associations_count":{},"past_year_issue_authors":{},"past_year_pull_request_authors":{},"maintainers":[{"login":"jdechalendar","count":60,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/jdechalendar"},{"login":"hcssmith","count":1,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/hcssmith"}],"active_maintainers":[]},"events":{"total":{"ForkEvent":1,"WatchEvent":4},"last_year":{"ForkEvent":1,"WatchEvent":1}},"keywords":[],"dependencies":[{"ecosystem":"pypi","filepath":"setup.py","sha":null,"kind":"manifest","created_at":"2022-08-08T23:01:20.686Z","updated_at":"2022-08-08T23:01:20.686Z","repository_link":"https://github.com/jdechalendar/gridemissions/blob/main/setup.py","dependencies":[{"id":702308899,"package_name":"requests","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false}]},{"ecosystem":"actions","filepath":".github/workflows/basic.yml","sha":null,"kind":"manifest","created_at":"2023-09-21T19:24:23.668Z","updated_at":"2023-09-21T19:24:23.668Z","repository_link":"https://github.com/jdechalendar/gridemissions/blob/main/.github/workflows/basic.yml","dependencies":[{"id":13856666232,"package_name":"actions/checkout","ecosystem":"actions","requirements":"v2","direct":true,"kind":"composite","optional":false},{"id":13856666233,"package_name":"actions/setup-python","ecosystem":"actions","requirements":"v2","direct":true,"kind":"composite","optional":false}]}],"score":9.246479418592056,"created_at":"2023-09-11T14:52:10.854Z","updated_at":"2026-04-23T22:30:37.395Z","avatar_url":"https://github.com/jdechalendar.png","language":"Python","category":"Emissions","sub_category":"Carbon Intensity and Accounting","monthly_downloads":53,"total_dependent_repos":0,"total_dependent_packages":0,"readme":"# gridemissions: Tools for power sector emissions tracking\n\u003cimg src=\"https://user-images.githubusercontent.com/20404131/129465144-5b086d9b-6c46-462f-a036-3f1e4cd958eb.png\" width=\"50%\" align=\"right\"\u003e\n\nThe tools in this repository power the visualization at [energy.stanford.edu/gridemissions](https://energy.stanford.edu/gridemissions), updated hourly. Associated datasets on electricity and emissions are made publicly available. In addition to tools to create the data, the `gridemissions` package provides a module to retrieve data from the API and methods to load and manipulate the data. This README file serves as a quick primer for the tools in this repository and includes a short FAQ, please refer to the documentation for more.\n\n## Documentation\nDocumentation generated using Sphinx can be found [here](https://docs.gridemissions.jdechalendar.su.domains/).\n\n## README Contents\n* [How the datasets are created](https://github.com/jdechalendar/gridemissions#how-the-datasets-are-created)\n* [Retrieving data from the API](https://github.com/jdechalendar/gridemissions#Retrieving-data-from-the-API)\n* [FAQ](https://github.com/jdechalendar/gridemissions#FAQ)\n* [Installation](https://github.com/jdechalendar/gridemissions#Installation)\n* [The `GraphData` class](https://github.com/jdechalendar/gridemissions#The-GraphData-class)\n\n\n## How the datasets are created\nTwo main operations are needed to create the datasets for the the visualization at [energy.stanford.edu/gridemissions](https://energy.stanford.edu/gridemissions).\n\n### 1. Consumption-based emissions\nElectric grid data on production, consumption and exchanges, along with the emissions associated with electricity production, are used to compute the emissions embodied in electricity **consumption**. By default, we are using IPCC Life-Cycle Assessment emissions factors to compute the emissions associated with generating electricity from different sources, so the CO2 data we release are in units of CO2-eq. If you wish to use different emissions factors, or factors for other quantities (e.g. SO2, NOx, PM2.5, or H2O), you can use the tools in this package to generate corresponding consumption-based data. A tutorial on how to do this will be available soon.\n\nFor more on this operation, see \"Tracking emissions in the US electricity system\", by Jacques A. de Chalendar, John Taggart and Sally M. Benson. Proceedings of the National Academy of Sciences Dec 2019, 116 (51) 25497-25502; DOI: 10.1073/pnas.1912950116\n\n### 2. Physics-based data reconciliation\nRaw electric grid data typically have errors and inconsistencies, but we need \"clean\" data to compute consumption-based emissions. We use an optimization-based algorithm to reconcile the raw data while enforcing certain physical constraints, e.g. conservation of energy. We publish both the raw and reconciled electric data that we use.\n\nFor more on this operation, see \"Physics-informed data reconciliation framework for real-time electricity and emissions tracking\", by Jacques A. de Chalendar and Sally M. Benson. Applied Energy Dec 2021; DOI: 10.1016/j.apenergy.2021.117761 [ArXiv preprint](https://arxiv.org/abs/2103.05663).\n\n## Bulk dataset\nThe main source of data for this project is the [US EIA's Grid Monitor](https://www.eia.gov/electricity/gridmonitor). Bulk files from that source are now available in six-month chunks, so we have switched to doing the same. The processed files can be downloaded all at once from [here](https://gridemissions.s3.us-east-2.amazonaws.com/processed.tar.gz) (1.3 GB as of Jan 16, 2024). See notebook `notebooks/Bulk Data Demo.ipynb` that makes a few plots from this dataset as a sanity check. We plan to also host a version of these datasets converted to Parquet for easier access -- this README will be updated when that is done.\n\n## Retrieving data from the API\nFor a quick introduction to the package, see the notebooks in the `notebooks/` folder. The [API Demo.ipynb](https://colab.research.google.com/drive/1HYHqiA2iA-vVMuqFHrKtUUkdPLN5UJYS) notebook can also be loaded on Colab and shows how data can be retrieved from the API and then manipulated using the `GraphData` methods. Note that only one month of historical data is available from the API.\n\nA download script is provided to quickly download data from the API and can be used after installing the package (see below):\n```bash\n# Downloads data for CAISO for a year\ngridemissions_download --variable=co2 --region=CISO --start=20190101 --end=20200101\n\n# Print help\ngridemissions_download -h\n\n# Download one of the datasets in bulk\ngridemissions_download --variable co2 --all\n```\nNote that the data are downloaded to the `DATA_PATH` you configured during setup (see Installation notes below).\n\nYou can also use the `api` module to retrieve data programmatically. This is what the `gridemissions_download` script uses under the hood.\n```python\nfrom gridemissions import api\n\n# Download CO2 emissions embodied in electricity consumption in the California ISO (CISO)\ndata = api.retrieve(dataset=\"co2\", region=\"CISO\", field=\"D\")\n\n# Download electricity generated by the Electric reliability council of Texas (ERCO) and in the Bonneville Power Administration (BPAT)\ndata = api.retrieve(dataset=\"elec\", region=[\"ERCO\", \"BPAT\"], field=\"NG\")\n```\nBy default, the `api.retrieve` function returns data in a pandas DataFrame. We also provide an abstraction to load and manipulate data called `GraphData`. This object is a light wrapped around a pandas DataFrame that provides convenient functionality to represent and access data from different fields on a graph. More on that below.\n\n### Data naming conventions\nIn the datasets that is generated from this work, we use the following conventions for naming columns (see `eia_api.py`). Replace `%s` in the following dictionaries by the balancing acronyms listed [here](https://www.eia.gov/electricity/gridmonitor/about).\n* For electricity, we follow the naming convention followed by the US EIA data source we are using:\n```python\n\"E\": {\n      \"D\": \"EBA.%s-ALL.D.H\",  # Demand (Consumption)\n      \"NG\": \"EBA.%s-ALL.NG.H\",  # Generation\n      \"TI\": \"EBA.%s-ALL.TI.H\",  # Total Interchange\n      \"ID\": \"EBA.%s-%s.ID.H\",  # Interchange\n  }\n```\nFor example, `\"EBA.CISO-ALL.D.H\"` is the column for demand in the California ISO.\n* For all other variables, we use a different convention, that only uses underscores as separators. For example, for carbon dioxide:\n```python\n\"CO2\": {\n    \"D\": \"CO2_%s_D\",  # Demand (Consumption)\n    \"NG\": \"CO2_%s_NG\",  # Generation\n    \"TI\": \"CO2_%s_TI\",  # Total Interchange\n    \"ID\": \"CO2_%s-%s_ID\",  # Interchange\n}\n```\nFor example, `\"CO2_CISO_D\"` is the column for consumed emissions in the California ISO, `\"CO2_CISO_NG\"` is the column for produced emissions in the California ISO.\n\n## FAQ\n### I tried to retrieve data from the API from 2018 without success\nThe backend API only stores a month's worth of data (to save on AWS costs). We suggest downloading data in bulk instead.\n\n### Where do the emissions factors come from?\nThese are life-cycle emissions factors from the [IPCC](https://www.ipcc.ch/report/renewable-energy-sources-and-climate-change-mitigation/) (Table A.II.4 on page 982 of the report at the link). If you want, you can use other emissions factors. [This](https://github.com/jdechalendar/gridemissions/blob/main/src/gridemissions/emissions.py#L14-L28) is where they are being read in by the codebase. If you pass in custom emissions factors, you can then re-run the code to generate estimates using your favorite ones. It would also not be too difficult to modify this code to make the emissions factors depend on the balancing-area and time of year, although that would require a bit more work.\n\n## Installation\nClone this repository on your machine using HTTPS:\n```\ngit clone https://github.com/jdechalendar/gridemissions.git\n```\nor using SSH (your GitHub account needs to have been configured in this case):\n```\ngit clone git@github.com:jdechalendar/gridemissions.git\n```\nFrom the `gridemissions` directory (the one that contains this README file), install this repository:\n```\npip install .\n```\nInstalling the project in this way means that you can now use statements like `import gridemissions` to make the code in this repository accessible anywhere on your system.\nTo install the optional dependencies as well (needed if you would like to run the automated data cleaning workflows)\n```\npip install .[all]\n```\nIf you intend to modify the code, you may want to install with the editable flag:\n```\npip install -e .[all]\n```\nAs explained [here](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs), this installs the package in setuptools' [\"Development mode\"](https://setuptools.readthedocs.io/en/latest/userguide/development_mode.html) so that you don't need to re-build the project every time you edit the code.\nOpen a Python interpreter and import the package to create the default configuration files for the project. When you import the package, it will check if configuration files exist. If not, a message will be printed to the screen to tell you where the configuration files are created on your system.\nOptionally, you can customize the configuration files. See the configuration section for details.\n\n### Configuration\nSome configuration is needed for this project, to hold environment variables like data paths, API keys and passwords. The recommended option is to use a configuration file (`config.json`). A default is created for you the first time you import the package, in the folder `~/.config/gridemissions`. `~` stands for your home directory. On Linux, this is what `$HOME` evaluates to, on Windows/OSX, this is the directory that contains your Documents, Desktop and Downloads folders.\n\nAlternatively, configuration settings can be read from environment variables, e.g. with\n```bash\nexport GRIDEMISSIONS_CONFIG_DIR_PATH=\"$HOME/.config/gridemissions_test\"\n```\n\n#### The config.json file\nWhenever you import the `gridemissions` module, the key-value pairs stored in `config.json` are loaded into a dictionary that then becomes available to you as the dictionary `gridemissions.config`. These can also be modified at runtime. At a minimum, your `config.json` should contain:\n* `DATA_PATH`: path to local data store, by default `~/data/gridemissions`\n* `TMP_PATH`: for scratch data (e.g. when downloading data), by default `~/tmp/gridemissions`\n\n#### Supported Environment Variables\n\n```text\nGRIDEMISSIONS_CONFIG_DIR_PATH:      the configuration directory (default: \"$HOME/.config/gridemissions\")\nGRIDEMISSIONS_LOG_CONFIG_FILE_PATH: the file used to store logging (default: \"$HOME/.config/gridemissions/logging.conf\")\nGRIDEMISSIONS_CONFIG_FILE_PATH:     the configuration file (default: \"$HOME/.config/gridemissions/config.json\")\nGRIDEMISSIONS_DEFAULT_LOGGING_CONF: the default logging configuration (default can be read within ./src/gridemissions/configure.py\")\nGRIDEMISSIONS_DATA_DIR_PATH:        the data directory (default: \"$HOME/data/gridemissions\")\nGRIDEMISSIONS_TMP_DIR_PATH:         the temporary data directory (default: \"$HOME/tmp/gridemissions\")\n```\n","funding_links":[],"readme_doi_urls":[],"works":{},"citation_counts":{},"total_citations":0,"keywords_from_contributors":[],"project_url":"https://ost.ecosyste.ms/api/v1/projects/20212","html_url":"https://ost.ecosyste.ms/projects/20212"}