Skip to content

Commit 5170f47

Browse files
crvernoncrvernon
authored
Merge pull request #6 from JGCRI/dev
Update protocol based on feedback
2 parents 48d1541 + 9fc78e4 commit 5170f47

File tree

4 files changed

+105
-61
lines changed

4 files changed

+105
-61
lines changed

‎README.md

Lines changed: 31 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,41 @@
1-
<!--your zenodo badge here-->
21

3-
># meta-repository
4-
>Template repository for a single point of access meta-repository to reproduce an experiment
5-
>
6-
>## Instructions for use
7-
>NOTE: Delete this instructional section after creating your template!
8-
>
9-
>### Purpose
10-
>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.
11-
>
12-
>### Using the Template
13-
>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.
14-
>
15-
>### Naming your meta-repository
16-
>The following naming conventions should be used when naming your repository:
17-
>- Single author: `lastname_year_journal`
18-
>- Multi author: `lastname-etal_year_journal`
19-
>- Multiple publications in the same journal: `lastname-etal_year-letter_journal` (e.g., `human-etal_2020-b_nature`)
20-
>
21-
>### Cutomize your `.gitignore` file
22-
>A general `.gitignore` for use with Python development is included. However, you may wish to customize this to the needs of your project.
23-
>
24-
>### Suggestions
25-
>- 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.
26-
>- Create complete and tested documentation for how to use what is in this repository to reproduce your experiment.
27-
>
28-
>### Creating a minted release for your meta-repository
29-
>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 [email protected] to get set up. The first line of this file is a space holder for your Zenodo DOI badge.
30-
>
31-
>
32-
>### The following is the template for you to fill in with your own information
332

3+
# metarepo
4+
Template repository for a single point of access meta-repository to reproduce an experiment
345

35-
# lastname-etal_year_journal
36-
One sentence describing your research
6+
## Purpose
7+
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.
378

38-
## Abstract
39-
Your abstract here.
9+
## Using the template
10+
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.
4011

41-
## Code reference
42-
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 `.<shortname>` to the version number of the parent and conduct your own name. For example, `v1.2.5.hydro`.
12+
## Naming your meta-repository
13+
The following naming conventions should be used when naming your repository:
14+
- Single author: `lastname_year_journal`
15+
- Multi author: `lastname-etal_year_journal`
16+
- Multiple publications in the same journal: `lastname-etal_year-letter_journal` (e.g., `human-etal_2020-b_nature`)
4317

44-
#### Example:
18+
## Customize your `.gitignore` file
19+
A general `.gitignore` for use with Python or R development is included. However, you may wish to customize this to the needs of your project. The `.gitignore` file lets Git know what to push to the remote repository and what needs to be ignored and stay local.
4520

46-
Human, I.M. (2020, January 1). human/myrepo: v1.2.5.hydro (Version v1.2.5.hydro). Zenodo. https://doi.org/some-doi-number
21+
## Suggestions
22+
- 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.
23+
- Create complete and tested documentation for how to use what is in this repository to reproduce your experiment.
4724

48-
## Journal reference
49-
Update your journal reference here after acceptance.
25+
## Creating a minted release for your meta-repository
26+
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 [email protected] to get set up.
5027

51-
## Data reference
52-
53-
### Input data
54-
Reference for each minted data source for your input data.
55-
56-
#### Example:
57-
58-
Human, I.M. (2020). My dataset name [Data set]. DataHub. https://doi.org/some-doi-number
59-
60-
### Output data
61-
Reference for each minted data source for your output data.
62-
63-
## Contributing models
64-
| Model | Version | Repository Link | DOI |
65-
|-------|---------|-----------------|-----|
66-
| <model 1> | <version> | <link to code repository> | <link to DOI dataset> |
67-
| <model 2> | <version> | <link to code repository> | <link to DOI dataset> |
68-
69-
## Reproduce my experiement
70-
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.
28+
## The meta-repository markdown template
29+
A sample meta-repository template is provided in this repository in the file `metarepo_template.md`.
7130

31+
To use it, do the following:
32+
1. Create the template repository as mentioned above in [Using the template](#using-the-template)
33+
2. Clone your new repository to you local machine
34+
3. Change directories into your new meta-repository directory you just cloned
35+
4. Run `git rm README.md` to delete this file (`README.md`) and commit it using `git commit -m 'remove instructions'`
36+
5. Rename `metarepo_template.md` as `README.md`
37+
6. Run `git add README.md` to stage the new file that will show up on load in your remote GitHub repository
38+
7. Run `git rm metarepo_template.md` to remove the original template
39+
8. Run `git commit -m 'set up new template as readme'` to set the changes
40+
9. Run `git push` to send the changes to your remote GitHub repository
41+
10. Modify the `README.md` file to represent your experiement and use the `add`, `commit`, `push` workflow to update your remote repository

‎figures/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
## This is the directory to place scripts or instructions in for recreating the figures that are represented in your publication

‎metarepo_template.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
_your zenodo badge here_
2+
3+
# lastname-etal_year_journal
4+
5+
**A long-term global energy-economic model of carbon dioxide release from fossil fuel use**
6+
7+
Jae Edmonds<sup>1\*</sup> and John Reilly<sup>1</sup>
8+
9+
<sup>1 </sup> Institute for Energy Analysis, Oak Ridge Associated Universities, 1346 Connecticut Avenue, NW, Washington, DC 20036, USA
10+
11+
\* corresponding author: [email protected]
12+
13+
## Abstract
14+
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.
15+
16+
## Journal reference
17+
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
18+
19+
## Code reference
20+
References for each minted software release for all code involved.
21+
22+
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.
23+
24+
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 `.<shortname>` to the version number of the parent and construct your own name. For example, `v1.2.5.hydro`.
25+
26+
Human, I.M. (2021, April 14). Project/repo:v0.1.0 (Version v0.1.0). Zenodo. http://doi.org/some-doi-number/zenodo.7777777
27+
28+
## Data reference
29+
30+
### Input data
31+
Reference for each minted data source for your input data. For example:
32+
33+
Human, I.M. (2021). My input dataset name [Data set]. DataHub. https://doi.org/some-doi-number
34+
35+
### Output data
36+
Reference for each minted data source for your output data. For example:
37+
38+
Human, I.M. (2021). My output dataset name [Data set]. DataHub. https://doi.org/some-doi-number
39+
40+
## Contributing modeling software
41+
| Model | Version | Repository Link | DOI |
42+
|-------|---------|-----------------|-----|
43+
| model 1 | version | link to code repository | link to DOI dataset |
44+
| model 2 | version | link to code repository | link to DOI dataset |
45+
| component 1 | version | link to code repository | link to DOI dataset |
46+
47+
## Reproduce my experiement
48+
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.
49+
50+
51+
1. Install the software components required to conduct the experiement from [Contributing modeling software](#contributing-modeling-software)
52+
2. Download and install the supporting input data required to conduct the experiement from [Input data](#input-data)
53+
3. Run the following scripts in the `workflow` directory to re-create this experiment:
54+
55+
| Script Name | Description | How to Run |
56+
| --- | --- | --- |
57+
| `step_one.py` | Script to run the first part of my experiment | `python3 step_one.py -f /path/to/inputdata/file_one.csv` |
58+
| `step_two.py` | Script to run the last part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` |
59+
60+
4. Download and unzip the output data from my experiment [Output data](#output-data)
61+
5. Run the following scripts in the `workflow` directory to compare my outputs to those from the publication
62+
63+
| Script Name | Description | How to Run |
64+
| --- | --- | --- |
65+
| `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` |
66+
67+
## Reproduce my figures
68+
Use the scripts found in the `figures` directory to reproduce the figures used in this publication.
69+
70+
| Script Name | Description | How to Run |
71+
| --- | --- | --- |
72+
| `generate_figures.py` | Script to generate my figures | `python3 generate_figures.py -i /path/to/inputs -o /path/to/outuptdir` |

‎workflow/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
## This is the directory to place scripts or instructions in for recreating your experiment

0 commit comments

Comments
 (0)