From 052e7a3bd7adf1bac2d310daaa58b0365e298295 Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Tue, 14 May 2024 12:52:41 -0700 Subject: [PATCH 1/7] update readme --- README.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 65adfd1..d1f69dd 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ [![DOI](https://zenodo.org/badge/265254045.svg)](https://zenodo.org/doi/10.5281/zenodo.10442485) # metarepo -Template repository for a single point of access meta-repository to reproduce an experiment +`metarepo` is short for a meta-repository, a GitHub repository that contains instructions to reproduce results in a published work. This repo is a template for creating your own metarepo. ## 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. +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 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. +Click `Use this template` on the main repository page (shows up above `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: @@ -16,26 +16,30 @@ The following naming conventions should be used when naming your repository: - Multiple publications in the same journal: `lastname-etal_year-letter_journal` (e.g., `human-etal_2020-b_nature`) ## Customize your `.gitignore` file -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. +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. ## 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. +- 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 downloading and using. - 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. +It is important to version and release your meta-repository 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 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 +2. Clone your new repository to your 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'` +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 +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 +10. Modify the `README.md` file to represent your experiment and use the `add`, `commit`, `push` workflow to update your remote repository + +## :star: Stellar Examples + + From d13aec467712db2893b9fb58dd3a0c7abe52b2d4 Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Thu, 16 May 2024 13:31:20 -0700 Subject: [PATCH 2/7] rename dir for scripts, overhaul of readme --- README.md | 76 ++++++++++++++++++++++++++++---------------- figures/README.md | 1 - metarepo_template.md | 33 +++++++++++-------- scripts/README.md | 1 + workflow/README.md | 1 - 5 files changed, 70 insertions(+), 42 deletions(-) delete mode 100644 figures/README.md create mode 100644 scripts/README.md delete mode 100644 workflow/README.md diff --git a/README.md b/README.md index d1f69dd..865b479 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,66 @@ [![DOI](https://zenodo.org/badge/265254045.svg)](https://zenodo.org/doi/10.5281/zenodo.10442485) # metarepo -`metarepo` is short for a meta-repository, a GitHub repository that contains instructions to reproduce results in a published work. This repo is a template for creating your own metarepo. +`metarepo` is short for meta-repository, a GitHub repository that contains instructions to reproduce results in a published work. This repo is a template for creating your own metarepo. ## 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 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 -Click `Use this template` on the main repository page (shows up above `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: +## Workflow +These are the big picture steps for how to start from scratch and end up with a complete metarepo. There are more in depth steps below. + +A. [Use the template to initialize your own meta-repo](#a.-use-the-template-to-initialize-your-own-meta-repo) + +B. [Edit the README to provide instructions for how to reproduce your results](#b.-edit-the-readme-to-provide-instructions-for-how-to-reproduce-your-results) + +C. [Upload all materials necessary to reproduce your results](#c.-upload-all-materials-necessary-to-reproduce-your-results) + +D. [Create a Zenodo badge and a release number](#d.-create-a-zenodo-badge) + + +### A. Use the template to initialize your own meta-repo +Click `Use this template` on the main repository page (shows up above `Clone or download`) and click `Create a new repository`. Fill in your `Repository name` (naming conventions below), the `Description`, select whether you want the repository to be `Public` or `Private`, and leave `Include all branches` unchecked. Click `Create repository`. You'll be taken to the new repository you created. + +Note: 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`) -## Customize your `.gitignore` file +### B. Edit the README to provide instructions for how to reproduce your results + +A sample metarepo template is provided in this repository named `metarepo_template.md`. + +You now want to replace the `README.md` file with the `metarepo_template.md`. To do this, do the following: +1. Clone your new repository to your local machine +2. Change directories into your new meta-repository directory you just cloned +3. Rename `metarepo_template.md` as `README.md` by running `mv metarepo_template.md README.md` +4. Run `git add README.md` to stage the new file that will show up on load in your remote GitHub repository +5. Run `git rm metarepo_template.md` to remove the not-renamed file from GitHub +6. Run `git commit -m "set README to the metarepo template"` to set the changes +7. Run `git push` to send the changes to your remote GitHub repository + +Now you have the metarepo template as your README! The next step is to fill out all the applicable sections on your README. This can be done either locally (in the cloned GitHub repo on your computer using the `add`, `commit`, and `push` workflow), or in browser on the GitHub website. + +### C. Upload all materials necessary to reproduce your results + +If your experiment includes scripts, upload those to the `scripts` directory. No data should be stored in your metarepo, data should be uploaded to a data storage service. For IM3 folks, use [MSD-LIVE](https://msdlive.org/). + +### D. Create a Zenodo badge and a release number +First, create a Zenodo badge by following the [GitHub docs](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content). Your repo needs to be public. + +Second, once your metarepo is up to date with your current results, create a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release). If your experiment or results change at any time, update your metarepo and create a new release. It is important to version and release your meta-repository 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. + + +## Additional (not required) steps +### Customize your `.gitignore` file 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. -## 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 downloading and using. -- 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 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 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 your 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 experiment and use the `add`, `commit`, `push` workflow to update your remote repository +### Best Practices +- 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 downloading and using. If you are a part of IM3, use [MSD-LIVE](https://msdlive.org/) to store data. +- Test that the instructions in your metarepo are enough to completely recreate your experiment. +- Remove all the instructive text throughout the metarepo once you're done. + ## :star: Stellar Examples diff --git a/figures/README.md b/figures/README.md deleted file mode 100644 index d865b2d..0000000 --- a/figures/README.md +++ /dev/null @@ -1 +0,0 @@ -## 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 83230cd..c58dd2d 100644 --- a/metarepo_template.md +++ b/metarepo_template.md @@ -2,28 +2,30 @@ _your zenodo badge here_ # lastname-etal_year_journal -**A long-term global energy-economic model of carbon dioxide release from fossil fuel use** +**your Paper Title here** -Jae Edmonds1\* and John Reilly1 +First Last1\*, First Last1, and First Last1, 2 -1 Institute for Energy Analysis, Oak Ridge Associated Universities, 1346 Connecticut Avenue, NW, Washington, DC 20036, USA +1 Pacific Northwest National Laboratory, Richland, WA, USA. + +2 Institute for Energy Analysis, Oak Ridge Associated Universities, Washington, DC, USA \* 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. +_your abstract here_ ## 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 +_your journal reference_ ## Code reference 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. +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 username. 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 +_your software reference here_ ## Data reference @@ -32,11 +34,16 @@ Reference for each minted data source for your input data. For example: Human, I.M. (2021). My input dataset name [Data set]. DataHub. https://doi.org/some-doi-number +_your input data references here_ + ### Output data Reference for each minted data source for your output data. For example: Human, I.M. (2021). My output dataset name [Data set]. DataHub. https://doi.org/some-doi-number +_your output data references here_ + + ## Contributing modeling software | Model | Version | Repository Link | DOI | |-------|---------|-----------------|-----| @@ -45,19 +52,19 @@ Human, I.M. (2021). My output dataset name [Data set]. DataHub. https://doi.org/ | component 1 | version | link to code repository | link to DOI dataset | ## Reproduce my experiment -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. +Fill in detailed info here or link to other documentation to thoroughly walkthrough how to use the contents of this repository to reproduce your experiment. Below is an example. -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 experiment from [contributing modeling software](#contributing-modeling-software) +2. Download and install the supporting [input data](#input-data) required to conduct the experiment 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_two.py` | Script to run the second 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](#output-data) from my experiment 5. Run the following scripts in the `workflow` directory to compare my outputs to those from the publication | Script Name | Description | How to Run | @@ -69,4 +76,4 @@ Use the scripts found in the `figures` directory to reproduce the figures used i | 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` | +| `generate_figures.py` | Script to generate my figures | `python3 generate_figures.py -input /path/to/inputs -output /path/to/outuptdir` | diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..74bee7b --- /dev/null +++ b/scripts/README.md @@ -0,0 +1 @@ +## This is the directory for scripts to recreate your experiment diff --git a/workflow/README.md b/workflow/README.md deleted file mode 100644 index 32466e8..0000000 --- a/workflow/README.md +++ /dev/null @@ -1 +0,0 @@ -## This is the directory to place scripts or instructions in for recreating your experiment From 2bf08b70d2e00a2c15ffcddaeadd5fc9f99f1065 Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Thu, 16 May 2024 18:23:58 -0700 Subject: [PATCH 3/7] add figures dir back, add to overhaul of readme --- CITATION.cff | 8 +++++++- README.md | 39 ++++++++++++++++++++++++++++++--------- figures/README.md | 1 + metarepo_template.md | 10 ++++++---- 4 files changed, 44 insertions(+), 14 deletions(-) create mode 100644 figures/README.md diff --git a/CITATION.cff b/CITATION.cff index 9750353..97c55b4 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -4,5 +4,11 @@ authors: - family-names: "Vernon" given-names: "Chris R." orcid: "https://orcid.org/0000-0002-3406-6214" -title: "metarepo: A single point of access meta-repository that guides others in how to reproduce an experiment" + - family-names: "Rexer" + given-names: "Em" + orcid: "https://orcid.org/0000-0002-0327-183X" +title: "metarepo: A single point of access meta-repository that guides others in how to reproduce an experiment." repository-code: "https://github.com/IMMM-SFA/metarepo" +doi: 10.5281/zenodo.10442485 +url: https://github.com/IMMM-SFA/metarepo + diff --git a/README.md b/README.md index 865b479..62bb8e7 100644 --- a/README.md +++ b/README.md @@ -6,18 +6,23 @@ ## 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 any ancillary code used to transform the source data, create figures for your publication, conduct the experiment, and / or execute the contributing software. +## Lost? Start here +- Don't know how to use GitHub? Check out their [tutorial](https://docs.github.com/en/get-started/start-your-journey/hello-world). +- Want a video walk-through of what a metarepo is, why they're important, and how to create one? [Here ya go](https://youtu.be/1dJOXdm-Wvc?t=180). + ## Workflow These are the big picture steps for how to start from scratch and end up with a complete metarepo. There are more in depth steps below. -A. [Use the template to initialize your own meta-repo](#a.-use-the-template-to-initialize-your-own-meta-repo) +A. [Use the template to initialize your own meta-repo](#a-use-the-template-to-initialize-your-own-meta-repo) -B. [Edit the README to provide instructions for how to reproduce your results](#b.-edit-the-readme-to-provide-instructions-for-how-to-reproduce-your-results) +B. [Edit the README to provide instructions for how to reproduce your results](#b-edit-the-readme-to-provide-instructions-for-how-to-reproduce-your-results) -C. [Upload all materials necessary to reproduce your results](#c.-upload-all-materials-necessary-to-reproduce-your-results) +C. [Upload all materials necessary to reproduce your results](#c-upload-all-materials-necessary-to-reproduce-your-results) -D. [Create a Zenodo badge and a release number](#d.-create-a-zenodo-badge) +D. [Add a DOI to your metarepo](#d-add-a-doi-to-your-metarepo) +E. [Add your metarepo citation in your paper](#e-add-your-metarepo-citation-to-your-paper) ### A. Use the template to initialize your own meta-repo Click `Use this template` on the main repository page (shows up above `Clone or download`) and click `Create a new repository`. Fill in your `Repository name` (naming conventions below), the `Description`, select whether you want the repository to be `Public` or `Private`, and leave `Include all branches` unchecked. Click `Create repository`. You'll be taken to the new repository you created. @@ -46,22 +51,38 @@ Now you have the metarepo template as your README! The next step is to fill out If your experiment includes scripts, upload those to the `scripts` directory. No data should be stored in your metarepo, data should be uploaded to a data storage service. For IM3 folks, use [MSD-LIVE](https://msdlive.org/). -### D. Create a Zenodo badge and a release number -First, create a Zenodo badge by following the [GitHub docs](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content). Your repo needs to be public. +### D. Add a DOI to your metarepo + +[This tutorial](https://coderefinery.github.io/github-without-command-line/doi/) walks through three main steps for adding a DOI to your metarepo, the three steps are summarized below. Note that this should be done after your metarepo is public and up to date with your current results. If your experiment or results change at any time, update your metarepo and create a new release. It is important to version and release your meta-repository 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](mailto:chris.vernon@pnnl.gov) to get set up. + +1. Activate the repository on Zenodo. If your metarepo is a part of the [IMMM-SFA](https://github.com/IMMM-SFA) GitHub organization, you may need a member of the DSC team to help you with this. +2. Create a “release” for your metarepo in GitHub. Generally you can start with `v1.0.0`. +3. Get a DOI from Zenodo and dd the DOI badge to your repository. -Second, once your metarepo is up to date with your current results, create a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release). If your experiment or results change at any time, update your metarepo and create a new release. It is important to version and release your meta-repository 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. +### E. Add your metarepo citation to your paper +Lastly, and very importantly, you need to add your metarepo citation to your paper so that people can find the beautiful reproducible instructions you've created. + +1. Edit the `CITATION.cff` file to contain the correct author(s) (name, ORCID ID), version, DOI, and URL. +2. Click on the `Cite this repository` button on the right side of the main page of your metarepo. Copy either the APA or BibTex format. +3. Add the citation to your paper. ## Additional (not required) steps ### Customize your `.gitignore` file 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. -### Best Practices + +## Best Practices - 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 downloading and using. If you are a part of IM3, use [MSD-LIVE](https://msdlive.org/) to store data. - Test that the instructions in your metarepo are enough to completely recreate your experiment. -- Remove all the instructive text throughout the metarepo once you're done. +- Remove all the instructive text throughout your metarepo once you're done. ## :star: Stellar Examples +- [burleyson-etal_2024_applied_energy](https://github.com/IMMM-SFA/burleyson-etal_2024_applied_energy) +- [ssembatya-etal_2024_earths_future](https://github.com/IMMM-SFA/ssembatya-etal_2024_earths_future) + +## Have more questions? +Ask a question in the [Discussion Section](https://github.com/IMMM-SFA/metarepo/discussions)! \ No newline at end of file diff --git a/figures/README.md b/figures/README.md new file mode 100644 index 0000000..75cb9e8 --- /dev/null +++ b/figures/README.md @@ -0,0 +1 @@ +## This is the directory to place your figures diff --git a/metarepo_template.md b/metarepo_template.md index c58dd2d..6e7daf3 100644 --- a/metarepo_template.md +++ b/metarepo_template.md @@ -2,7 +2,7 @@ _your zenodo badge here_ # lastname-etal_year_journal -**your Paper Title here** +**your Paper Title here (once published, include a link to the text)** First Last1\*, First Last1, and First Last1, 2 @@ -74,6 +74,8 @@ Fill in detailed info here or link to other documentation to thoroughly walkthro ## 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 -input /path/to/inputs -output /path/to/outuptdir` | +| Figure Number(s) | Script Name | Description | How to Run | +| --- | --- | --- | --- | +| 1, 2 | `generate_plot.py` | Description of figure, ie. "Plots the difference between our two scenarios" | `python3 generate_plot.py -input /path/to/inputs -output /path/to/outuptdir` | +| 3 | `generate_figure.py` | Description of figure, ie. "Shows how the mean and peak differences are calculated" | `python3 generate_figure.py -input /path/to/inputs -output /path/to/outuptdir` | + From 1126070c00bc85d1cd321553228831c5e77b29b7 Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Thu, 16 May 2024 18:24:50 -0700 Subject: [PATCH 4/7] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 62bb8e7..72b081f 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ C. [Upload all materials necessary to reproduce your results](#c-upload-all-mate D. [Add a DOI to your metarepo](#d-add-a-doi-to-your-metarepo) -E. [Add your metarepo citation in your paper](#e-add-your-metarepo-citation-to-your-paper) +E. [Add your metarepo citation to your paper](#e-add-your-metarepo-citation-to-your-paper) ### A. Use the template to initialize your own meta-repo Click `Use this template` on the main repository page (shows up above `Clone or download`) and click `Create a new repository`. Fill in your `Repository name` (naming conventions below), the `Description`, select whether you want the repository to be `Public` or `Private`, and leave `Include all branches` unchecked. Click `Create repository`. You'll be taken to the new repository you created. From 723e6f56aa3bb468e8a97fe040bd0e8e72be4400 Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Fri, 17 May 2024 12:55:47 -0700 Subject: [PATCH 5/7] remove instructions from readme --- README.md | 81 +------------------------------------------------------ 1 file changed, 1 insertion(+), 80 deletions(-) diff --git a/README.md b/README.md index 72b081f..c09970b 100644 --- a/README.md +++ b/README.md @@ -1,88 +1,9 @@ [![DOI](https://zenodo.org/badge/265254045.svg)](https://zenodo.org/doi/10.5281/zenodo.10442485) # metarepo +## [Check out the website for instructions](https://immm-sfa.github.io/metarepo) `metarepo` is short for meta-repository, a GitHub repository that contains instructions to reproduce results in a published work. This repo is a template for creating your own metarepo. ## 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 any ancillary code used to transform the source data, create figures for your publication, conduct the experiment, and / or execute the contributing software. -## Lost? Start here -- Don't know how to use GitHub? Check out their [tutorial](https://docs.github.com/en/get-started/start-your-journey/hello-world). -- Want a video walk-through of what a metarepo is, why they're important, and how to create one? [Here ya go](https://youtu.be/1dJOXdm-Wvc?t=180). - - -## Workflow -These are the big picture steps for how to start from scratch and end up with a complete metarepo. There are more in depth steps below. - -A. [Use the template to initialize your own meta-repo](#a-use-the-template-to-initialize-your-own-meta-repo) - -B. [Edit the README to provide instructions for how to reproduce your results](#b-edit-the-readme-to-provide-instructions-for-how-to-reproduce-your-results) - -C. [Upload all materials necessary to reproduce your results](#c-upload-all-materials-necessary-to-reproduce-your-results) - -D. [Add a DOI to your metarepo](#d-add-a-doi-to-your-metarepo) - -E. [Add your metarepo citation to your paper](#e-add-your-metarepo-citation-to-your-paper) - -### A. Use the template to initialize your own meta-repo -Click `Use this template` on the main repository page (shows up above `Clone or download`) and click `Create a new repository`. Fill in your `Repository name` (naming conventions below), the `Description`, select whether you want the repository to be `Public` or `Private`, and leave `Include all branches` unchecked. Click `Create repository`. You'll be taken to the new repository you created. - -Note: 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`) - -### B. Edit the README to provide instructions for how to reproduce your results - -A sample metarepo template is provided in this repository named `metarepo_template.md`. - -You now want to replace the `README.md` file with the `metarepo_template.md`. To do this, do the following: -1. Clone your new repository to your local machine -2. Change directories into your new meta-repository directory you just cloned -3. Rename `metarepo_template.md` as `README.md` by running `mv metarepo_template.md README.md` -4. Run `git add README.md` to stage the new file that will show up on load in your remote GitHub repository -5. Run `git rm metarepo_template.md` to remove the not-renamed file from GitHub -6. Run `git commit -m "set README to the metarepo template"` to set the changes -7. Run `git push` to send the changes to your remote GitHub repository - -Now you have the metarepo template as your README! The next step is to fill out all the applicable sections on your README. This can be done either locally (in the cloned GitHub repo on your computer using the `add`, `commit`, and `push` workflow), or in browser on the GitHub website. - -### C. Upload all materials necessary to reproduce your results - -If your experiment includes scripts, upload those to the `scripts` directory. No data should be stored in your metarepo, data should be uploaded to a data storage service. For IM3 folks, use [MSD-LIVE](https://msdlive.org/). - -### D. Add a DOI to your metarepo - -[This tutorial](https://coderefinery.github.io/github-without-command-line/doi/) walks through three main steps for adding a DOI to your metarepo, the three steps are summarized below. Note that this should be done after your metarepo is public and up to date with your current results. If your experiment or results change at any time, update your metarepo and create a new release. It is important to version and release your meta-repository 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](mailto:chris.vernon@pnnl.gov) to get set up. - -1. Activate the repository on Zenodo. If your metarepo is a part of the [IMMM-SFA](https://github.com/IMMM-SFA) GitHub organization, you may need a member of the DSC team to help you with this. -2. Create a “release” for your metarepo in GitHub. Generally you can start with `v1.0.0`. -3. Get a DOI from Zenodo and dd the DOI badge to your repository. - -### E. Add your metarepo citation to your paper - -Lastly, and very importantly, you need to add your metarepo citation to your paper so that people can find the beautiful reproducible instructions you've created. - -1. Edit the `CITATION.cff` file to contain the correct author(s) (name, ORCID ID), version, DOI, and URL. -2. Click on the `Cite this repository` button on the right side of the main page of your metarepo. Copy either the APA or BibTex format. -3. Add the citation to your paper. - -## Additional (not required) steps -### Customize your `.gitignore` file -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. - - -## Best Practices -- 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 downloading and using. If you are a part of IM3, use [MSD-LIVE](https://msdlive.org/) to store data. -- Test that the instructions in your metarepo are enough to completely recreate your experiment. -- Remove all the instructive text throughout your metarepo once you're done. - - -## :star: Stellar Examples - -- [burleyson-etal_2024_applied_energy](https://github.com/IMMM-SFA/burleyson-etal_2024_applied_energy) -- [ssembatya-etal_2024_earths_future](https://github.com/IMMM-SFA/ssembatya-etal_2024_earths_future) - -## Have more questions? - -Ask a question in the [Discussion Section](https://github.com/IMMM-SFA/metarepo/discussions)! \ No newline at end of file From 98eb017f8d7da25a2fe6e6c27c37eeb73a990e6c Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Thu, 23 May 2024 11:50:09 -0700 Subject: [PATCH 6/7] merge metarepo template into readme --- README.md | 83 ++++++++++++++++++++++++++++++++++++++++++++ metarepo_template.md | 81 ------------------------------------------ 2 files changed, 83 insertions(+), 81 deletions(-) delete mode 100644 metarepo_template.md diff --git a/README.md b/README.md index c09970b..eac0460 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ [![DOI](https://zenodo.org/badge/265254045.svg)](https://zenodo.org/doi/10.5281/zenodo.10442485) + + # metarepo ## [Check out the website for instructions](https://immm-sfa.github.io/metarepo) `metarepo` is short for meta-repository, a GitHub repository that contains instructions to reproduce results in a published work. This repo is a template for creating your own metarepo. @@ -7,3 +9,84 @@ ## 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 any ancillary code used to transform the source data, create figures for your publication, conduct the experiment, and / or execute the contributing software. + + +# lastname-etal_year_journal + +**your Paper Title here (once published, include a link to the text)** + +First Last1\*, First Last1, and First Last1, 2 + +1 Pacific Northwest National Laboratory, Richland, WA, USA. + +2 Institute for Energy Analysis, Oak Ridge Associated Universities, Washington, DC, USA + +\* corresponding author: email@myorg.gov + +## Abstract +_your abstract here_ + +## Journal reference +_your journal reference_ + +## Code reference +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 username. 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`. + +_your software reference here_ + +## Data reference + +### Input data +Reference for each minted data source for your input data. For example: + +Human, I.M. (2021). My input dataset name [Data set]. DataHub. https://doi.org/some-doi-number + +_your input data references here_ + +### Output data +Reference for each minted data source for your output data. For example: + +Human, I.M. (2021). My output dataset name [Data set]. DataHub. https://doi.org/some-doi-number + +_your output data references here_ + + +## 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 experiment +Fill in detailed info here or link to other documentation to thoroughly walkthrough how to use the contents of this repository to reproduce your experiment. Below is an example. + + +1. Install the software components required to conduct the experiment from [contributing modeling software](#contributing-modeling-software) +2. Download and install the supporting [input data](#input-data) required to conduct the experiment +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 second part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` | + +4. Download and unzip the [output data](#output-data) from my experiment +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` | + +## Reproduce my figures +Use the scripts found in the `figures` directory to reproduce the figures used in this publication. + +| Figure Number(s) | Script Name | Description | How to Run | +| --- | --- | --- | --- | +| 1, 2 | `generate_plot.py` | Description of figure, ie. "Plots the difference between our two scenarios" | `python3 generate_plot.py -input /path/to/inputs -output /path/to/outuptdir` | +| 3 | `generate_figure.py` | Description of figure, ie. "Shows how the mean and peak differences are calculated" | `python3 generate_figure.py -input /path/to/inputs -output /path/to/outuptdir` | + diff --git a/metarepo_template.md b/metarepo_template.md deleted file mode 100644 index 6e7daf3..0000000 --- a/metarepo_template.md +++ /dev/null @@ -1,81 +0,0 @@ -_your zenodo badge here_ - -# lastname-etal_year_journal - -**your Paper Title here (once published, include a link to the text)** - -First Last1\*, First Last1, and First Last1, 2 - -1 Pacific Northwest National Laboratory, Richland, WA, USA. - -2 Institute for Energy Analysis, Oak Ridge Associated Universities, Washington, DC, USA - -\* corresponding author: email@myorg.gov - -## Abstract -_your abstract here_ - -## Journal reference -_your journal reference_ - -## Code reference -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 username. 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`. - -_your software reference here_ - -## Data reference - -### Input data -Reference for each minted data source for your input data. For example: - -Human, I.M. (2021). My input dataset name [Data set]. DataHub. https://doi.org/some-doi-number - -_your input data references here_ - -### Output data -Reference for each minted data source for your output data. For example: - -Human, I.M. (2021). My output dataset name [Data set]. DataHub. https://doi.org/some-doi-number - -_your output data references here_ - - -## 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 experiment -Fill in detailed info here or link to other documentation to thoroughly walkthrough how to use the contents of this repository to reproduce your experiment. Below is an example. - - -1. Install the software components required to conduct the experiment from [contributing modeling software](#contributing-modeling-software) -2. Download and install the supporting [input data](#input-data) required to conduct the experiment -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 second part of my experiment | `python3 step_two.py -o /path/to/my/outputdir` | - -4. Download and unzip the [output data](#output-data) from my experiment -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` | - -## Reproduce my figures -Use the scripts found in the `figures` directory to reproduce the figures used in this publication. - -| Figure Number(s) | Script Name | Description | How to Run | -| --- | --- | --- | --- | -| 1, 2 | `generate_plot.py` | Description of figure, ie. "Plots the difference between our two scenarios" | `python3 generate_plot.py -input /path/to/inputs -output /path/to/outuptdir` | -| 3 | `generate_figure.py` | Description of figure, ie. "Shows how the mean and peak differences are calculated" | `python3 generate_figure.py -input /path/to/inputs -output /path/to/outuptdir` | - From 06666ebb62b7bb5285a62cc474c68e495ae207ee Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Fri, 31 May 2024 08:22:22 -0700 Subject: [PATCH 7/7] clearer wording --- figures/README.md | 2 +- scripts/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/figures/README.md b/figures/README.md index 75cb9e8..9dbca3e 100644 --- a/figures/README.md +++ b/figures/README.md @@ -1 +1 @@ -## This is the directory to place your figures +## This directory contains figures and the code to create those figures diff --git a/scripts/README.md b/scripts/README.md index 74bee7b..3b9e539 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1 +1 @@ -## This is the directory for scripts to recreate your experiment +## This directory contains scripts to recreate your experiment and results