Documentation for GCAM
The Global Change Analysis Model
View the Project on GitHub JGCRI/gcam-doc
This memo outlines some suggested guidelines for the community of GCAM users to employ in peer-reviewed journal articles using GCAM or versions of GCAM. The memo focuses on two areas: i.) guidelines for co-authorship of GCAM team members in papers led by community members, and ii.) guidelines for suggested language to be used to describe GCAM in papers.
GCAM is an open-source community model. GCAM capability developments are typically conducted in teams and major developments are often multi-year efforts involving multiple staff members from JGCRI and partner organizations. Most capability developments are conducted in research versions of GCAM which are documented or used in peer-reviewed papers often led by JGCRI staff. Once capability developments are made public through are GitHub repositories, the community is welcome to use the latest version of GCAM with the latest capabilities for papers.
While we make ongoing efforts to keep our documentation up to date (http://jgcri.github.io/gcam-doc/), not all nuances of the model and interpretation of its results can be included. Please reach out with any questions you may have about GCAM input data or interpreting GCAM results. The primary avenue for this is the discussions section of the GCAM GitHub page (https://github.com/JGCRI/gcam-core/discussions).
In addition, if it would be helpful to your study to have the expertise from a GCAM team member at JGCRI, we welcome GCAM community users to approach one or more GCAM team members to serve as co-author(s) in their papers. These invitations are welcome to go out to experts in the topical area of the paper being written. If in doubt about who to invite, please feel free to reach out to the GCAM core model committee listed below. The GCAM team values research collaborations with the GCAM community.
GCAM is under continuing development. The suggested language for the opening paragraphs of a methodology or introduction section of a paper describing GCAM in papers is as follows:
“The Global Change Analysis Model (GCAM) is an integrated multisector model developed and maintained at the Pacific Northwest National Laboratory’s Joint Global Change Research Institute (JGCRI, 2023) <include additional citations to previous GCAM studies as relevant>. GCAM is an open-source community model. In this study, we use GCAM v NN. The documentation of the model is available at the GCAM documentation page (http://jgcri.github.io/gcam-doc/) and the description below is a summary. GCAM includes representations of: economy, energy, agriculture, and water supply in 32 geopolitical regions across the globe; their GHG and air pollutant emissions and global GHG concentrations, radiative forcing, and temperature change; and the associated land allocation, water use and agriculture production across 384 land sub-regions and 235 water basins. <If using GCAM-USA, include without quotes: “This study uses a U.S.-focused version of GCAM called GCAM-USA that includes representation of energy, economy, and water systems for the fifty states and the District of Columbia in addition to 31 regions outside of the United States.”>. The version of GCAM used in this study is available – along with full source code and instructions for use – in a public repository <include citation including link to the GCAM repository with doi used in paper>.
Subsequent paragraphs of the description might expound on particular capabilities, systems, or sectors of focus in the paper. Details in the GCAM documentation page can be used as a reference to develop these paragraphs.
Community users of GCAM might also undertake their own model developments and/or assumptions for papers. It is recommended that these departures from the publicly available version of the model be clearly described. In addition, if these developments are substantial, we suggest making this clear by including an additional phrase (e.g. region name or name of institution) in the name of the model and explicitly calling it out in place of or immediately following the italicized portion in the above paragraphs. For example: “This study uses a modified version of GCAM/GCAM-USA called GCAM-<institution name>/GCAM-USA-<institution name>. GCAM-<institution name>/GCAM-USA-<institution name> incorporates additional details and modified assumptions from GCAM v NN as described subsequently”.
JGCRI, 2023. GCAM Documentation (Version 7.0). https://github.com/JGCRI/gcam-doc. Joint Global Change Research Institute. https://zenodo.org/doi/10.5281/zenodo.11377813.
<cite latest version of model documentation>