Skip to contents

Install the Package

Use devtools or remotes to install the package:

library(devtools)
install_github("psysciacc/psaverse")

Load the Library

Setting up a PSA Project Package

First, you would need to run the psa_create_project() function including the path you want to start the folder on your computer and the name of the project. After you run this function, the new package R project will open automatically for you (unless you change open to FALSE). Use that R project to complete the rest of the steps below to ensure files/folders go into the correct directories.

psa_create_project(
  path = "~/Github", # path you want this on your computer
  psa_name = "PSA007-spaml", # name of the project 
  open = TRUE
)

Create/Update Descriptions

You can update the description of the package using the psa_update_description() function. Here are the license options:

  • MIT License: “MIT”
  • Apache License 2.0: “Apache”
  • GNU General Public License: “GPLv2” or “GPLv3”
  • GNU Affero General Public License, version 3: “AGPLv3”
  • GNU Lesser General Public License: “LGPLv2.1” or “LGPLv3”
  • Creative Commons CC0 Public Domain Dedication: “CC0”
  • Creative Commons Attribution 4.0 International: “CC-BY”
  • Proprietary license: “Proprietary”

Note: say yes when it asks if you want to overwrite the license!

library(psaverse) # since you are in a new project
psa_update_description(
  package_title = "SPAML IS GREAT",
  description = "Here's a serious description of the project.",
  version = "0.0.1",
  license = "GPLv3"
)

You can add authors to the package for other project monitors or the lead author of the paper.

Each author can have one or more roles, indicated by a character string. Common roles include:

  • “cre”: The “creator” or maintainer of the package. This is required and only one person can be designated with this role.
  • “aut”: Authors who contributed to the package (other than the maintainer).
  • “cph”: Contributors who hold copyright on the package.
  • “ctb”: Contributors who helped but are not full authors (e.g., provided bug fixes, advice, or minor contributions).
  • “rev”: Reviewers.
  • “trl”: Translator(s).
psa_add_author(
  given = "Lucy",
  family = "van Pelt",
  role = c("aut", "cre"),
  email = "lucy@example.com",
  ORCID_number = "LUCY-ORCID-ID")

If you check the description file, you will now see that it has the new author and description:

Package: PSA007-spaml
Title: SPAML IS GREAT
Version: 0.0.1
Authors@R: 
    person("Lucy", "van Pelt", , "lucy@example.com", role = c("aut", "cre"),
           comment = c(ORCID = "LUCY-ORCID-ID"))
Description: Here's a serious description of the project.
License: GPL (>= 3)
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.2

If you want to add more, you can use this function, but if you want to delete people, you will need to manually edit the description file. It’s a text file that can be opened with RStudio or a text editor.

Create Folder Structure

psa_create_folder("all") will create the entire folder structure for the package, while you can also add one at a time.

Other options:

  • “ethics”: creates the “01_Ethics” folder.
  • “power”: creates the “02_Power” folder.
  • “materials”: creates the “03_Materials” folder.
  • “procedure”: creates the “04_Procedure” folder.
  • “data”: creates the “05_Data” folder.
  • “analysis”: creates the “06_Analysis” folder.
  • “communication”: creates the “07_Communication folder.
  • “all”: creates all eight main folders.
  • Any other parameter option will be added into the 08_Other folder.
# will create all folders 
psa_create_folder("all")

# this will put a new folder in the other folder
psa_create_folder("cheese")

Add Documents

You can then manually move the files you need into the folder structure or use the psa_add_documents() function to add individual files or entire folders.

psa_add_documents(
  folder = "ethics", # where should it go
  path = "~/Downloads", # to a single file or directory
  should_replace = FALSE, # overwrite existing files?
  recursive = FALSE # move all subfolders as well 
)

This function will print out a list of files moved for you, and you can see that it copied the files over into your folder.

Add R Package Dependencies

After you add your R scripts in .R or .Rmd format, you can use a convenience function to add all libraries that can be found in those scripts. The default is to examine all files in the inst folder and add those packages.

psa_dependencies(
    scan_folder = "inst",
    add_package = NULL 
    )

Create Metadata for Each Folder

We want to make sure people can use these files. Use the psa_create_metadata() function to create a metadata csv file. You will then need to manually edit that file. Folder options are the same as above.

psa_create_metadata("ethics", 
                    overwrite = FALSE)

The function creates a README.md or adds to the bottom of your current readme. You will see output like this:

(FOLDER NAME) documentation


(SHORT DESCRIPTION)


File information:

|name                                          |isdir |descriptions            |
|:---------------------------------------------|:-----|:-----------------------|
|Roles_Data.csv                                |FALSE |INSERT FILE DESCRIPTION |
|supplementary data and codes.zip              |FALSE |INSERT FILE DESCRIPTION |

You should fill information that is IN CAPS, such as the folder name, description of the folder, and the description of the files. Note that the structure of the file information folder is a markdown table, so do not delete the | or --- to ensure that the table renders correctly.

View Folder Information

The user of your package will then be able to view the folder contents in a dataframe using psa_view_folder():

psa_view_folder(folder = "ethics")

Add this Package to PSA GitHub

First, you should confirm you have the ability to push to the PsySciAcc github organization at https://github.com/psysciacc. Please ask to be added to the team.

Second, you can use the psa_git() function to initialize your new project as a github repository associated with the PsySciAcc organization. You can then use your favorite way to github to push and pull to update the package. The default is to create a private repository until you are ready to release the project.

If you see this message:

ℹ Defaulting to "https" Git protocol.
Error in `check_uses_git()`:
✖ Cannot detect that project is already a
  Git repository.
ℹ Do you need to run usethis::use_git()?

Simply click on usethis::use_git to set up your folder as a GitHub repository. Then rerun psa_git().

Check Package Folders

This function will check that you meet the minimum requires for documentation and files for the PSA folder structure. You will receive information on what you are missing.

Options: “ethics”, “power”, “materials”, “procedure”, “data”, “analysis”, “communication”, “all”.

psa_check_folder(folder = "ethics")

You will then get feedback about how your project should be organized:

ℹ Checking O1_Ethics folder...
• You need to include: 
  - README.md
  - lab_ethics_summary.csv
  - Collaboration Agreement
  - PI_IRB
  - Local_IRB
  - No_Ethics
  - Rely_PI
✔ Checking finished.

You can fix these issues and rerun the function until no messages remain.

Citation

If you want to add a citation for the project, which can be separate than the citation for the package, you can use psa_citation(). You can add any features that are allowable in bibentry().

psa_citation(
  bibtype = "Article", # default
    title = "SPAML Greatness Achieved!",
    author = "Buchanan, E.M.",
    journal = "The Magical Journal of Cognition",
    year = 2025,
    url = "https://osf.io",
    volume = 12,
    number = 3,
    pages = "45-67",
    doi = "10.1234/example.doi"
)

This function creates a CITATION file, which will look like this:

bibentry(bibtype = "Article",
         title = "SPAML Greatness Achieved!",
         author = c(person(family = "Buchanan"),
                    person(family = "E.M.")),
         journal = "The Magical Journal of Cognition",
         year = "2025",
         url = "https://osf.io",
         volume = "12",
         number = "3",
         pages = "45-67",
         doi = "10.1234/example.doi")

And when the package is built, you can use the citation() function in base R to view the citation for the project.