Skip to content

Commit

Permalink
Merge pull request #4 from IMMM-SFA/dev
Browse files Browse the repository at this point in the history
rehaul
  • Loading branch information
erexer authored Jun 18, 2024
2 parents ab3b3b6 + 06666eb commit 00c7358
Show file tree
Hide file tree
Showing 6 changed files with 96 additions and 111 deletions.
8 changes: 7 additions & 1 deletion CITATION.cff
Original file line number Diff line number Diff line change
Expand Up @@ -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

123 changes: 87 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,92 @@
[![DOI](https://zenodo.org/badge/265254045.svg)](https://zenodo.org/doi/10.5281/zenodo.10442485)

<!-- Get rid of the metarepo instructions (the two sections below this) once you're done. -->

# metarepo
Template repository for a single point of access meta-repository to reproduce an experiment
## [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 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`)

## 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 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 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
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.

<!-- Get rid of the metarepo instructions (the two sections above this) once you're done. -->

# lastname-etal_year_journal

**your Paper Title here (once published, include a link to the text)**

First Last<sup>1\*</sup>, First Last<sup>1</sup>, and First Last<sup>1, 2</sup>

<sup>1 </sup>Pacific Northwest National Laboratory, Richland, WA, USA.

<sup>2 </sup> 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 `.<shortname>` 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` |

2 changes: 1 addition & 1 deletion figures/README.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
## This is the directory to place scripts or instructions in for recreating the figures that are represented in your publication
## This directory contains figures and the code to create those figures
72 changes: 0 additions & 72 deletions metarepo_template.md

This file was deleted.

1 change: 1 addition & 0 deletions scripts/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
## This directory contains scripts to recreate your experiment and results
1 change: 0 additions & 1 deletion workflow/README.md

This file was deleted.

0 comments on commit 00c7358

Please # to comment.