From a6a1f0c3cda61d02ec169f88d88216cf094d8490 Mon Sep 17 00:00:00 2001 From: crvernon Date: Wed, 14 Apr 2021 14:20:17 -0400 Subject: [PATCH 1/9] break out template to non readme md --- metarepo.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 metarepo.md diff --git a/metarepo.md b/metarepo.md new file mode 100644 index 0000000..db81d60 --- /dev/null +++ b/metarepo.md @@ -0,0 +1,57 @@ + + +# lastname-etal_year_journal + +**A long-term global energy-economic model of carbon dioxide release from fossil fuel use** + +Jae Edmonds1\* and John Reilly1 + +1 Institute for Energy Analysis, Oak Ridge Associated Universities, 1346 Connecticut Avenue, NW, Washington, DC 20036, USA +\* corresponding author: email@pnl.gov + +## Abstract +In this paper the authors develop a long-term global energy-economic model which is capable of assessing alternative energy evolutions over periods of up to 100 years. The authors have sought to construct the model so that it can perform its assigned task with as simple a modelling system as possible. The model structure is fully documented and a brief summary of results is given. + +## Journal reference +Edmonds, J., & Reilly, J. (1983). A long-term global energy-economic model of carbon dioxide release from fossil fuel use. Energy Economics, 5(2), 74-88. DOI: https://doi.org/10.1016/0140-9883(83)90014-2 + +## Code reference +References for each minted software release for all code involved. If you have modified a codebase that is outside of a formal release, and the modifications are not planned on being merged back into a version, fork the parent repository and add a `.` to the version number of the parent and conduct your own name. For example, `v1.2.5.hydro`. + +## Data reference + +### Input data +Reference for each minted data source for your input data. +For example: + +Human, I.M. (2020). My input dataset name [Data set]. DataHub. https://doi.org/some-doi-number + +### Output data +Reference for each minted data source for your output data. +For example: + +Human, I.M. (2020). My output dataset name [Data set]. DataHub. https://doi.org/some-doi-number + +## Contributing modeling software +| Model | Version | Repository Link | DOI | +|-------|---------|-----------------|-----| +| | | | | +| | | | | +| | | | | + +## Reproduce my experiement +Fill in detailed info here or link to other documentation that is a thorough walkthrough of how to use what is in this repository to reproduce your experiment. + + +1. Install the software components required to conduct the experiement from [Contributing modeling software](#Contributing modeling software) +2. Download and install the supporting input data required to conduct the experiement from [Input data](#Input data) +3. Run the following scripts in the `workflow` directory to re-create this experiment: + - | Script Name | Description | How to Run | + | --- | --- | --- | + | `step_one.py` | Script to run the first part of my experiment | `python3 step_one.py -f /path/to/inputdata/file_one.csv` + | `step_two.py` | Script to run the last part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` +4. Download and unzip the output data from my experiment [Output data](#Output data) +5. Run the following scripts in the `workflow` directory to compare my outputs to those from the publication + - | Script Name | Description | How to Run | + | --- | --- | --- | + | `compare.py` | Script to compare my outputs to the original | `python3 compare.py --orig /path/to/original/data.csv --new /path/to/new/data.csv` From efd0df176463d0b624ae81e3fc8b5b7ccf6ad318 Mon Sep 17 00:00:00 2001 From: crvernon Date: Wed, 14 Apr 2021 14:27:02 -0400 Subject: [PATCH 2/9] update name and tables --- metarepo.md => metarepo_template.md | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) rename metarepo.md => metarepo_template.md (68%) diff --git a/metarepo.md b/metarepo_template.md similarity index 68% rename from metarepo.md rename to metarepo_template.md index db81d60..e8705e9 100644 --- a/metarepo.md +++ b/metarepo_template.md @@ -6,7 +6,7 @@ Jae Edmonds1\* and John Reilly1 -1 Institute for Energy Analysis, Oak Ridge Associated Universities, 1346 Connecticut Avenue, NW, Washington, DC 20036, USA +1 Institute for Energy Analysis, Oak Ridge Associated Universities, 1346 Connecticut Avenue, NW, Washington, DC 20036, USA \* corresponding author: email@pnl.gov ## Abstract @@ -21,23 +21,21 @@ References for each minted software release for all code involved. If you have ## Data reference ### Input data -Reference for each minted data source for your input data. -For example: +Reference for each minted data source for your input data. For example: Human, I.M. (2020). My input dataset name [Data set]. DataHub. https://doi.org/some-doi-number ### Output data -Reference for each minted data source for your output data. -For example: +Reference for each minted data source for your output data. For example: Human, I.M. (2020). My output dataset name [Data set]. DataHub. https://doi.org/some-doi-number ## Contributing modeling software | Model | Version | Repository Link | DOI | |-------|---------|-----------------|-----| -| | | | | -| | | | | -| | | | | +| model 1 | version | link to code repository | link to DOI dataset | +| model 2 | version | link to code repository | link to DOI dataset | +| component 1 | version | link to code repository | link to DOI dataset | ## Reproduce my experiement Fill in detailed info here or link to other documentation that is a thorough walkthrough of how to use what is in this repository to reproduce your experiment. @@ -46,12 +44,12 @@ Fill in detailed info here or link to other documentation that is a thorough wal 1. Install the software components required to conduct the experiement from [Contributing modeling software](#Contributing modeling software) 2. Download and install the supporting input data required to conduct the experiement from [Input data](#Input data) 3. Run the following scripts in the `workflow` directory to re-create this experiment: - - | Script Name | Description | How to Run | - | --- | --- | --- | - | `step_one.py` | Script to run the first part of my experiment | `python3 step_one.py -f /path/to/inputdata/file_one.csv` - | `step_two.py` | Script to run the last part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` +| Script Name | Description | How to Run | +| --- | --- | --- | +| `step_one.py` | Script to run the first part of my experiment | `python3 step_one.py -f /path/to/inputdata/file_one.csv` +| `step_two.py` | Script to run the last part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` 4. Download and unzip the output data from my experiment [Output data](#Output data) 5. Run the following scripts in the `workflow` directory to compare my outputs to those from the publication - - | Script Name | Description | How to Run | - | --- | --- | --- | - | `compare.py` | Script to compare my outputs to the original | `python3 compare.py --orig /path/to/original/data.csv --new /path/to/new/data.csv` +| Script Name | Description | How to Run | +| --- | --- | --- | +| `compare.py` | Script to compare my outputs to the original | `python3 compare.py --orig /path/to/original/data.csv --new /path/to/new/data.csv` From d3836e6223b98aaacccdf1fb37ae5a4401e8d767 Mon Sep 17 00:00:00 2001 From: crvernon Date: Wed, 14 Apr 2021 14:29:29 -0400 Subject: [PATCH 3/9] update table format --- metarepo_template.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/metarepo_template.md b/metarepo_template.md index e8705e9..3d336d9 100644 --- a/metarepo_template.md +++ b/metarepo_template.md @@ -1,4 +1,4 @@ - +_your zenodo badge here_ # lastname-etal_year_journal @@ -7,7 +7,7 @@ Jae Edmonds1\* and John Reilly1 1 Institute for Energy Analysis, Oak Ridge Associated Universities, 1346 Connecticut Avenue, NW, Washington, DC 20036, USA -\* corresponding author: email@pnl.gov +\* corresponding author: email@myorg.gov ## Abstract In this paper the authors develop a long-term global energy-economic model which is capable of assessing alternative energy evolutions over periods of up to 100 years. The authors have sought to construct the model so that it can perform its assigned task with as simple a modelling system as possible. The model structure is fully documented and a brief summary of results is given. @@ -46,10 +46,10 @@ Fill in detailed info here or link to other documentation that is a thorough wal 3. Run the following scripts in the `workflow` directory to re-create this experiment: | Script Name | Description | How to Run | | --- | --- | --- | -| `step_one.py` | Script to run the first part of my experiment | `python3 step_one.py -f /path/to/inputdata/file_one.csv` -| `step_two.py` | Script to run the last part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` +| `step_one.py` | Script to run the first part of my experiment | `python3 step_one.py -f /path/to/inputdata/file_one.csv` | +| `step_two.py` | Script to run the last part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` | 4. Download and unzip the output data from my experiment [Output data](#Output data) 5. Run the following scripts in the `workflow` directory to compare my outputs to those from the publication | Script Name | Description | How to Run | | --- | --- | --- | -| `compare.py` | Script to compare my outputs to the original | `python3 compare.py --orig /path/to/original/data.csv --new /path/to/new/data.csv` +| `compare.py` | Script to compare my outputs to the original | `python3 compare.py --orig /path/to/original/data.csv --new /path/to/new/data.csv` | From 72531432af15c3e2957268d0c9e458b2fea3b9ad Mon Sep 17 00:00:00 2001 From: crvernon Date: Wed, 14 Apr 2021 14:31:16 -0400 Subject: [PATCH 4/9] fix to corresponding author --- metarepo_template.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/metarepo_template.md b/metarepo_template.md index 3d336d9..d42c4fc 100644 --- a/metarepo_template.md +++ b/metarepo_template.md @@ -7,6 +7,7 @@ _your zenodo badge here_ Jae Edmonds1\* and John Reilly1 1 Institute for Energy Analysis, Oak Ridge Associated Universities, 1346 Connecticut Avenue, NW, Washington, DC 20036, USA + \* corresponding author: email@myorg.gov ## Abstract @@ -44,12 +45,15 @@ Fill in detailed info here or link to other documentation that is a thorough wal 1. Install the software components required to conduct the experiement from [Contributing modeling software](#Contributing modeling software) 2. Download and install the supporting input data required to conduct the experiement from [Input data](#Input data) 3. Run the following scripts in the `workflow` directory to re-create this experiment: + | Script Name | Description | How to Run | | --- | --- | --- | | `step_one.py` | Script to run the first part of my experiment | `python3 step_one.py -f /path/to/inputdata/file_one.csv` | | `step_two.py` | Script to run the last part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` | + 4. Download and unzip the output data from my experiment [Output data](#Output data) 5. Run the following scripts in the `workflow` directory to compare my outputs to those from the publication + | Script Name | Description | How to Run | | --- | --- | --- | | `compare.py` | Script to compare my outputs to the original | `python3 compare.py --orig /path/to/original/data.csv --new /path/to/new/data.csv` | From 9e77bba43c8cad17dccc3b5aff1445b8a84fe180 Mon Sep 17 00:00:00 2001 From: crvernon Date: Wed, 14 Apr 2021 14:37:03 -0400 Subject: [PATCH 5/9] set up figure and workflow structure --- figures/README.md | 1 + metarepo_template.md | 7 +++++++ workflow/README.md | 1 + 3 files changed, 9 insertions(+) create mode 100644 figures/README.md create mode 100644 workflow/README.md diff --git a/figures/README.md b/figures/README.md new file mode 100644 index 0000000..d865b2d --- /dev/null +++ b/figures/README.md @@ -0,0 +1 @@ +## This is the directory to place scripts or instructions in for recreating the figures that are represented in your publication diff --git a/metarepo_template.md b/metarepo_template.md index d42c4fc..0570472 100644 --- a/metarepo_template.md +++ b/metarepo_template.md @@ -57,3 +57,10 @@ Fill in detailed info here or link to other documentation that is a thorough wal | Script Name | Description | How to Run | | --- | --- | --- | | `compare.py` | Script to compare my outputs to the original | `python3 compare.py --orig /path/to/original/data.csv --new /path/to/new/data.csv` | + +# Reproduce my figures +Use the scripts found in the `figures` directory to reproduce the figures used in this publication. + +| Script Name | Description | How to Run | +| --- | --- | --- | +| `generate_figures.py` | Script to generate my figures | `python3 generate_figures.py -i /path/to/inputs -o /path/to/outuptdir` | diff --git a/workflow/README.md b/workflow/README.md new file mode 100644 index 0000000..32466e8 --- /dev/null +++ b/workflow/README.md @@ -0,0 +1 @@ +## This is the directory to place scripts or instructions in for recreating your experiment From 61ee33a887eda7643428b0984ba4280dc0caa198 Mon Sep 17 00:00:00 2001 From: crvernon Date: Wed, 14 Apr 2021 14:46:18 -0400 Subject: [PATCH 6/9] update zenodo info --- metarepo_template.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/metarepo_template.md b/metarepo_template.md index 0570472..415bfa2 100644 --- a/metarepo_template.md +++ b/metarepo_template.md @@ -17,19 +17,25 @@ In this paper the authors develop a long-term global energy-economic model which Edmonds, J., & Reilly, J. (1983). A long-term global energy-economic model of carbon dioxide release from fossil fuel use. Energy Economics, 5(2), 74-88. DOI: https://doi.org/10.1016/0140-9883(83)90014-2 ## Code reference -References for each minted software release for all code involved. If you have modified a codebase that is outside of a formal release, and the modifications are not planned on being merged back into a version, fork the parent repository and add a `.` to the version number of the parent and conduct your own name. For example, `v1.2.5.hydro`. +References for each minted software release for all code involved. + +These are generated by Zenodo automatically when conducting a release when Zenodo has been linked to your GitHub repository. The Zenodo references are built by setting the author order in order of contribution to the code using the author's GitHub user name. This citation can, and likely should, be edited without altering the DOI. + +If you have modified a codebase that is outside of a formal release, and the modifications are not planned on being merged back into a version, fork the parent repository and add a `.` to the version number of the parent and construct your own name. For example, `v1.2.5.hydro`. + +Human, I.M. (2021, April 14). Project/repo:v0.1.0 (Version v0.1.0). Zenodo. http://doi.org/some-doi-number/zenodo.7777777 ## Data reference ### Input data Reference for each minted data source for your input data. For example: -Human, I.M. (2020). My input dataset name [Data set]. DataHub. https://doi.org/some-doi-number +Human, I.M. (2021). My input dataset name [Data set]. DataHub. https://doi.org/some-doi-number ### Output data Reference for each minted data source for your output data. For example: -Human, I.M. (2020). My output dataset name [Data set]. DataHub. https://doi.org/some-doi-number +Human, I.M. (2021). My output dataset name [Data set]. DataHub. https://doi.org/some-doi-number ## Contributing modeling software | Model | Version | Repository Link | DOI | @@ -58,7 +64,7 @@ Fill in detailed info here or link to other documentation that is a thorough wal | --- | --- | --- | | `compare.py` | Script to compare my outputs to the original | `python3 compare.py --orig /path/to/original/data.csv --new /path/to/new/data.csv` | -# Reproduce my figures +## Reproduce my figures Use the scripts found in the `figures` directory to reproduce the figures used in this publication. | Script Name | Description | How to Run | From 964488fa0ef51cb5a7139e89d0890234f399e41d Mon Sep 17 00:00:00 2001 From: crvernon Date: Wed, 14 Apr 2021 15:09:39 -0400 Subject: [PATCH 7/9] add new readme steps --- README.md | 92 +++++++++++++++++++------------------------------------ 1 file changed, 32 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 9ae4977..4c87918 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,43 @@ - -># meta-repository ->Template repository for a single point of access meta-repository to reproduce an experiment -> ->## Instructions for use ->NOTE: Delete this instructional section after creating your template! -> ->### Purpose ->A meta-repository allows us to create a single point of access for someone to find all of the components that were used to create a published work for the purpose of reproducibility. This repository should contain references to all minted data and software as well as house any ancillary code used to transform the source data, create figures for your publication, conduct the experiment, and / or execute the contributing software. -> ->### Using the Template ->Simply click `Use this template` on the main repository page (shows up to the left of `Clone or download`) and fill in your `Repository name`, the `Description`, select whether you want the repository to be `Public` or `Private`, and leave `Include all branches` unchecked. -> ->### Naming your meta-repository ->The following naming conventions should be used when naming your repository: ->- Single author: `lastname_year_journal` ->- Multi author: `lastname-etal_year_journal` ->- Multiple publications in the same journal: `lastname-etal_year-letter_journal` (e.g., `human-etal_2020-b_nature`) -> ->### Cutomize your `.gitignore` file ->A general `.gitignore` for use with Python development is included. However, you may wish to customize this to the needs of your project. -> ->### Suggestions ->- Don't bog down your repository with a bunch of raw data. Instead archive and mint a DOI for your data and provide the reference in this repository with instructions for use. ->- Create complete and tested documentation for how to use what is in this repository to reproduce your experiment. -> ->### Creating a minted release for your meta-repository ->It is important to version and release your meta-repository as well due to changes that may occur during the publication review process. If you do not know how to conduct a release on GitHub when linked with Zenodo, please contact chris.vernon@pnnl.gov to get set up. The first line of this file is a space holder for your Zenodo DOI badge. -> -> ->### The following is the template for you to fill in with your own information +# metarepo +Template repository for a single point of access meta-repository to reproduce an experiment -# lastname-etal_year_journal -One sentence describing your research +## Purpose +A meta-repository creates a single point of access for someone to find all of the components that were used to create a published work for the purpose of reproducibility. This repository should contain references to all minted data and software as well as house any ancillary code used to transform the source data, create figures for your publication, conduct the experiment, and / or execute the contributing software. -## Abstract -Your abstract here. +## Using the template +Simply click `Use this template` on the main repository page (shows up to the left of `Clone or download`) and fill in your `Repository name`, the `Description`, select whether you want the repository to be `Public` or `Private`, and leave `Include all branches` unchecked. -## Code reference -References for each minted software release for all code involved. If you have modified a codebase that is outside of a formal release, and the modifications are not planned on being merged back into a version, fork the parent repository and add a `.` to the version number of the parent and conduct your own name. For example, `v1.2.5.hydro`. +Use the following naming convention for your repository: ` | | | | -| | | | | - -## Reproduce my experiement -Fill in detailed info here or link to other documentation that is a thorough walkthrough of how to use what is in this repository to reproduce your experiment. +## The meta-repository markdown template +A sample meta-repository template is provided in this repository in the file `metarepo_template.md`. +To use it, do the following: +1. Create the template repository as mentioned above in [Using the template](#Using the template) +2. Clone your new repository to you local machine +3. Change directories into your new meta-repository directory you just cloned +4. Run `git rm README.md` to delete this file (`README.md`) and commit it using `git commit -m 'remove instructions'` +5. Rename `metarepo_template.md` as `README.md` +6. Run `git add README.md` to stage the new file that will show up on load in your remote GitHub repository +7. Run `git rm metarepo_template.md` to remove the original template +8. Run `git commit -m 'set up new template as readme'` to set the changes +9. Run `git push` to send the changes to your remote GitHub repository +10. Modify the `README.md` file to represent your experiement and use the `add`, `commit`, `push` workflow to update your remote repository From 5b288cc834537141d2db517028fff515efe894f7 Mon Sep 17 00:00:00 2001 From: crvernon Date: Wed, 14 Apr 2021 15:15:02 -0400 Subject: [PATCH 8/9] update link in instructions --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4c87918..bc25dc3 100644 --- a/README.md +++ b/README.md @@ -9,15 +9,13 @@ A meta-repository creates a single point of access for someone to find all of th ## Using the template Simply click `Use this template` on the main repository page (shows up to the left of `Clone or download`) and fill in your `Repository name`, the `Description`, select whether you want the repository to be `Public` or `Private`, and leave `Include all branches` unchecked. -Use the following naming convention for your repository: ` Date: Wed, 14 Apr 2021 15:16:22 -0400 Subject: [PATCH 9/9] update links in template --- metarepo_template.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/metarepo_template.md b/metarepo_template.md index 415bfa2..50b72cd 100644 --- a/metarepo_template.md +++ b/metarepo_template.md @@ -48,8 +48,8 @@ Human, I.M. (2021). My output dataset name [Data set]. DataHub. https://doi.org/ Fill in detailed info here or link to other documentation that is a thorough walkthrough of how to use what is in this repository to reproduce your experiment. -1. Install the software components required to conduct the experiement from [Contributing modeling software](#Contributing modeling software) -2. Download and install the supporting input data required to conduct the experiement from [Input data](#Input data) +1. Install the software components required to conduct the experiement from [Contributing modeling software](#contributing-modeling-software) +2. Download and install the supporting input data required to conduct the experiement from [Input data](#input-data) 3. Run the following scripts in the `workflow` directory to re-create this experiment: | Script Name | Description | How to Run | @@ -57,7 +57,7 @@ Fill in detailed info here or link to other documentation that is a thorough wal | `step_one.py` | Script to run the first part of my experiment | `python3 step_one.py -f /path/to/inputdata/file_one.csv` | | `step_two.py` | Script to run the last part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` | -4. Download and unzip the output data from my experiment [Output data](#Output data) +4. Download and unzip the output data from my experiment [Output data](#output-data) 5. Run the following scripts in the `workflow` directory to compare my outputs to those from the publication | Script Name | Description | How to Run |