hegsrr/hegsrr-template

Template documents and packages for study pre-registration, reproductions, and replications

If you use this template for research, please cite it:

Kedron, P., & Holler, J. (2023). Template for Reproducible and Replicable Research in Human-Environment and Geographical Sciences. https://doi.org/10.17605/OSF.IO/W29MQ

Title of Study

Contributors

• First Name Last Name*, email address, @githubname, ORCID link, affiliated institution(s)
• First Name Last Name, email address, @githubname, ORCID link, affiliated institution(s)

* Corresponding author and creator

Abstract

Write a brief abstract about your research project. If the project is a reproduction or replication study, include the full citation with a statement This study is a reproduction/replication of:

citation to prior study

A graphical abstract of the study could also be included as an image here.

Study Metadata

• Key words: Comma-separated list of keywords (tags) for searchability. Geographers often use one or two keywords each for: theory, geographic context, and methods.
• Subject: select from the BePress Taxonomy
• Date created: date when project was started
• Date modified: date of most recent revision
• Spatial Coverage: Specify the geographic extent of your study. This may be a place name and link to a feature in a gazetteer like GeoNames or OpenStreetMap, or a well known text (WKT) representation of a bounding box.
• Spatial Resolution: Specify the spatial resolution as a scale factor, description of the level of detail of each unit of observation (including administrative level of administrative areas), and/or or distance of a raster GRID size
• Spatial Reference System: Specify the geographic or projected coordinate system for the study
• Temporal Coverage: Specify the temporal extent of your study---i.e. the range of time represented by the data observations.
• Temporal Resolution: Specify the temporal resolution of your study---i.e. the duration of time for which each observation represents or the revisit period for repeated observations
• Funding Name: name of funding for the project
• Funding Title: title of project grant
• Award info URI: web address for award information
• Award number: award number

Related to

• OSF Project:
• Pre-analysis Registration:
• Post-analysis Report Registration:
• Preprint:
• Conference Presentation:
• Publication:
• Prior Study:
• ...:

Metadata for access

• Rights: LICENSE: BSD 3-Clause "New" or "Revised"
• Resource type: Collection
• Resource language: English
• Conforms to: Template for Reproducible and Replicable Research in Human-Environment and Geographical Sciences version 1.0, DOI:10.17605/OSF.IO/W29MQ

Compendium structure and contents

This research compendium is structured with four main directories:

• data: contains subdirectories for raw data and derived data.
• docs: contains subdirectories for manuscript, presentation, and report
• procedure: contains subdirectories for code or software scripts, information about the computational environment in which the research was conducted, and non-code research protocols
• results: contains subdirectories for figures, formatted data tables, or other formats of research results.

The data, procedures, and results of this repository are outlined in three tables:

• Data: data/data_index.csv
• Procedures: procedure/procedure_index.csv
• Results: results/results_index.csv

Important local documents include:

• Pre-analysis plan: docs/report/preanalysis.pdf
• Study report: docs/report/report.pdf
• Manuscript: docs/manuscript/manuscript.pdf
• Presentation: docs/presentation/presentation.pdf

Compendium reference

The template_readme.md file contains more information on the design of this template and references used in the design. The Template_LICENSE file provides the BSD 3-Clause license for using this template. To cite the template, please use template_reference.bib or:

Kedron, P., & Holler, J. (2023). Template for Reproducible and Replicable Research in Human-Environment and Geographical Sciences. https://doi.org/10.17605/OSF.IO/W29MQ

hegsrr-template's Issues

consider the license to use

See note in the references at the end of the reproduction template. The ReScience article template is licensed under GNU General Public License Version 3, available at https://www.gnu.org/licenses/gpl-3.0.en.html , so technically if we build off of that, we have to license all derived works the same way.

That has significant implications, e.g. if anyone wanted to use this for a reproduction study, they'd have to fight with most journals over the copyright and licensing of the derived paper. It stakes out a strong "copyleft" position about the academic publishing business model. If the goal is to broadly diffuse r&r practices in HEGS, then I think copyleft licensing is not helpful. MIT License or creative commons with attribution (but not a commercial restriction) will be more flexible.

Version 2.0

This issue is a reminder to release a version 2.0 of this template prior to fall courses & workshops.

developing r&r compendium

I started mocking up directory structures with informational readme.md files in each under the Research-Repository directory.

It doesn't have the json files, makefiles and whatnot of the data carpentry mockup you had found, and modifies the repositories slightly to make more sense. e.g. figures not generated by analysis are included in doc and there's a structure and .gitignore file for handling private data situations.

Code Style

R should follow Tidyverse style: https://style.tidyverse.org/ and there are two great addins:

• stylr formats your code for you https://styler.r-lib.org/
• lintr checks your code formatting: https://github.com/jimhester/lintr

Python should follow PEP 8 Style: https://www.python.org/dev/peps/pep-0008/

Overarching updates

Short term modifications

• Dublin core on top-level readme
• Single instructions line about what to do if files are >100mb
• Move metadata readme information into HEGSRR-Manual
• Shift language away from R&R to research more broadly

Medium term modifications

• Convert pre-analysis plan .docx into .tex and .md files, and move instructions into HEGSRR-Manual

Revise template_readme.md

Most of the functions & content of this file will be replaced by the manual, and most of the content can move to the manual.

generating reports

We need to move toward having the pre-analysis plan, code, outputs, everything in the same R markdown file or Jupyter notebook.
For Markdown, use knitr to generate the report https://yihui.org/knitr/
For Jupyter, use stitch https://pystitch.github.io/

When knitr or stitch is run, the report can be saved to the reports folder. At that time, the researcher should commit a Version of the Git repository, and then continue revising the main notebook / rmarkdown. This will reduce redundancies while recording provenance of the data, research plan, and code.

License & Citation

Let's use BSD 3.0 for licenses on repositories.

The template itself can also use this license.

License information can be linked from the root readme.md

Also, suggested CITATION information can be embedded in repositories with a citation file! https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files

template code

• replace 01-r_script.r with a markdown template, or possibly include both by having a template that calls this helper R script.
• include here and functions to set up directory paths.
• include starter rmarkdown variables / setup
• create a python jupyter notebook version of the same

containers

Github just enhanced a feature for sharing Docker containers in an organization!
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry

sample preanalysis plan

I wrote up a preanalysis plan for the malcomb et al study.
Feel free to proofread / give feedback. Drew is the keeper of the repository for now:
https://github.com/daptx/RP-Malcomb/blob/main/docs/report/preanalysis.md

I was able to follow the template for the most part, with some comments:

1. add one letter to abbreviations to disambiguate: Rpr - reproduction; Rel - replication
2. add back in the researcher's experience in the region of study, if relevant, to sampling plan part 2
3. clarify that for data description, here we're really talking about database-level metadata, not particular indicators
4. I think there's a lot more to Variables section, specifically transformations. I think both geographic and attribute transformations of variables should go here, pulling the "adjustment" material out of Analyses -> data exclusion and adjustment and pulling any geographic pre-processing transformations out of Analyses.
5. in Analyses, I don't see the need for data "adjustment"... that seems like it should be part of the Variables transformations section.
6. I'm ok leaving a thorough description of the geographic structure & conceptualization in the Analyses section... with some guidance in an instruction document on how to avoid duplication of material between the various sections.
7. good stuff!

2 considerations: metadata standards and ROI/AOI data

two thoughts:

1. perhaps we should be adopting some generally accepted standards for spatial metadata, e.g. from OGC or the national infrastructure

2. I'd be ideal to have a GEOJSON file of the area of interest / ROI / study extent, because this can be automatically rendered on leaflet map while viewing the repository on GitHub