diff --git a/CITATION.cff b/CITATION.cff deleted file mode 100644 index 97c55b4..0000000 --- a/CITATION.cff +++ /dev/null @@ -1,14 +0,0 @@ -cff-version: 1.2.0 -message: "If you use this software, please cite it as below." -authors: - - family-names: "Vernon" - given-names: "Chris R." - orcid: "https://orcid.org/0000-0002-3406-6214" - - 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/LICENSE b/LICENSE deleted file mode 100644 index 4889972..0000000 --- a/LICENSE +++ /dev/null @@ -1,25 +0,0 @@ -BSD 2-Clause License - -Copyright (c) 2020-current, Battelle Memorial Institute -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md deleted file mode 100644 index 72b081f..0000000 --- a/README.md +++ /dev/null @@ -1,88 +0,0 @@ -[![DOI](https://zenodo.org/badge/265254045.svg)](https://zenodo.org/doi/10.5281/zenodo.10442485) - -# 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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..3521fe2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,27 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'metarepo' +copyright = '2024, Chris Vernon, Em Rexer' +author = 'Chris Vernon, Em Rexer' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..eb2afae --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. metarepo documentation master file, created by + sphinx-quickstart on Fri May 17 09:15:34 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to metarepo's documentation! +==================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/figures/README.md b/figures/README.md deleted file mode 100644 index 75cb9e8..0000000 --- a/figures/README.md +++ /dev/null @@ -1 +0,0 @@ -## This is the directory to place your figures 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` | - diff --git a/scripts/README.md b/scripts/README.md deleted file mode 100644 index 74bee7b..0000000 --- a/scripts/README.md +++ /dev/null @@ -1 +0,0 @@ -## This is the directory for scripts to recreate your experiment