EJAM is not only a web app, it is also an R package you can install. This is useful if you want to use the full set of EJAM R functions, many of which do things not available in the web app, to do customized analysis, to explore the datasets, or to reuse data or code in other applications.
This assumes you have installed and know how to use R and RStudio (some functions assume you have RStudio), and git. You might also want GitHub Desktop for convenience.
Options
The package is on GitHub.com, not CRAN (so
install.packages('EJAM') would not work).
To use EJAM in RStudio, you have two options:
- You can clone (or fork) the repo as a new RStudio Project, and then install from that source. Cloning (or forking) is easy and allows you to explore or contribute to source code. This is the recommended option.
- Option 2 is to avoid cloning. That is easier if you only want to run the web app locally, but may not work if you want to use certain R functions directly.
Option 1. Install with cloning (preferred approach)
Step 1. Clone EJAM & create a Project in RStudio
Here are three ways, but any of them should work – The first one is probably the simplest:
method A. start in RStudio: Click
File, New Project, Version
Control, Git, and for the repository URL,
enter https://github.com/ejanalysis/EJAM. For help: How to create a
new RStudio project by cloning a remote Git repo. Then add it to
GitHub Desktop if that is a tool you use.
method B. start in GitHub Desktop: Click
File, Clone, URL, and
for the repository URL, enter
https://github.com/ejanalysis/EJAM. For help: How to clone a
repo using GitHub Desktop. Then in RStudio: Click
File, New Project, Existing
Directory, and specify the folder you just cloned into.
method C. start at GitHub.com: Go to the EJAM repository page, click the green Code button, Download Zip, then unzip the zip file that contains the package. For help: How to clone a repo from GitHub.com. Then in RStudio: Click File, New Project, Existing Directory, and specify the folder you just cloned into.
Configure Build Tools in RStudio (optional)
You can click Build, Configure Build Tools, and change settings. For example, try these settings:
- Project build tools: Package
- Package directory: (Project Root)
- Always use –preclean : checked (yes)
- Use devtools : checked (yes)
- Generate documentation with Roxygen: checked (yes)
- Configure Roxygen options: all checked/yes, except for Vignettes and Build/Install
- Install package R CMD check: –no-multiarch –with-keep.source
- Build source & Build binary: leave both blank
For help: How to configure build tools in RStudio.
Step 2. Install (after Cloning)
You can use the Build menu in RStudio, or just run the following (which installs all the Suggests, not just Imports)
if (!require(devtools)) {install.packages("devtools")}
# To do install() below, you have to say where the cloned package was saved:
# ejamroot = the root directory into which you cloned!
## If you used the RStudio default, this may be where you cloned to:
parentfolder <- rstudioapi::readRStudioPreference(
"default_open_project_location", ".")
ejamroot <- file.path(parentfolder, "EJAM")
if (!(basename(ejamroot) == "EJAM" &&
file.exists(file.path(ejamroot, "DESCRIPTION")))) {
stop("must set ejamroot to root folder of EJAM source package")}
devtools::install(pkg = ejamroot, dependencies=T, upgrade="always", build=F)Option 2. Install without cloning (not the preferred approach)
You may be able to install the package to just run the web app locally in RStudio without cloning, but some of the code assumes a local source code copy is available (especially functions or scripts related to analysis the web app cannot do, or for package development).
Using install_github()
If you do have a PAT set up, you can use
remotes::install_github(). (For help on PAT setup, see the
last section of this article).
options(timeout=300); if (!require(devtools)) {install.packages("devtools")}
ref = github_release() # specifies you want the latest released version
#ref = "development" # development branch version
#ref = "HEAD" # main branch
#ref = "EJAM-v2.32.6.002" # a specific branch
#ref = "v2.32.6.002" # a specific tag as the way to identify a specific release
remotes::install_github(
repo = "ejanalysis/EJAM", ref = ref,
dependencies=T, upgrade="always", build=F)
library(EJAM)Using install_url() or install_local()
If you don’t have a personal access
token (PAT) and don’t want to set one up, you could check the
github repository for the latest release and may be able to use
remotes::install_url() something like this:
options(timeout=300); if (!require(devtools)) {install.packages("devtools")}
zipname = "v2.32.6.002.zip" # or whatever the latest release is - update as needed
remote_zip = paste0(
"https://github.com/ejanalysis/EJAM/archive/refs/tags/", zipname)
remotes::install_url(url = remote_zip,
dependencies=T, upgrade='always', build=F)
library(EJAM)or download the .zip file as a separate step, and install from that saved file:
options(timeout=300); if (!require(devtools)) {install.packages("devtools")}
zipname = "v2.32.6.002.zip" # or whatever the latest release is - update as needed
remote_zip = paste0(
"https://github.com/ejanalysis/EJAM/archive/refs/tags/", zipname)
local_zip = file.path(tempdir(), zipname)
download.file(remote_zip, destfile = local_zip)
remotes::install_local(path = local_zip,
dependencies=T, upgrade="always", build=F)
library(EJAM)Other Technical Details
Just in case you need more details on how installing and attaching the package works, the following describes the package dependencies and code used by the package to get the data and build an index.
Setting up Personal Access Tokens (PATs)
You may need to set up a personal access token (PAT) for authentication to work when using a repository on GitHub.com. See more about git credentials and the credential store. Note Windows takes care of most of this now, in conjunction with GitHub.
## To check for existing PATs:
usethis::gh_token_help() # or
usethis::git_sitrep() # git situation report
# To make a new PAT:
usethis::create_github_token()
# To register a PAT:
credentials::set_github_pat()Tests of installation on various platforms and R versions
The package has tests of whether it can be installed on Windows,
MacOS, and Ubuntu, with various R versions and with
remotes::url_install() and
remotes::github_install(). When a pull request or push to
the main branch of EJAM occurs, those tests run automatically as github
actions in a workflow at https://github.com/ejanalysis/EJAM/blob/main/.github/workflows
and logs of the results of those tests are here: https://github.com/ejanalysis/EJAM/actions. The same
sort of tests could be set up to be triggered by pushes to the
development branch, but just note a set of installation tests like these
can take well over an hour to run on github.
Details on CRAN packages needed (dependencies)
You should not have to do anything other than the instructions above,
to handle package dependencies. EJAM needs dozens of other packages to
be installed that are (almost all) available from CRAN. Installing the EJAM package
as explained above (with dependencies=TRUE, upgrade=“always”) will
handle obtaining those other packages. Cloning and building/installing
and then trying to load/attach EJAM will also alert you to those other
packages you need to install if you don’t already have them. In case it
is of interest, a list of packages needed is in the
DESCRIPTION file in the R package source code root folder
(as can be found in the code repository). Note some are in Suggests and
you probably want to install those as well since some of them were
actually used in some less-often-used features or functions. Using
dependencies=T in remotes::install_github(),
remotes::install_url(), install(), etc. will make sure they
are all installed. Each of those packages in turn requires other
packages that also get installed as needed. Future work may reduce the
number of package dependencies to a more typical number.
Details on the automatic data downloads
To work in the RStudio console, EJAM needs some datasets not stored as part of the package. However, they already should be downloaded (right after you first install the package) and loaded into memory automatically (or be ready for lazy-loading or otherwise loading as needed) as soon as you do require(EJAM) or library(EJAM).
On first use, the package should automatically download some data
files from a related repository. Each time the package is attached via
library() or require(), .onAttach() will check for updates
and also will build a spatial index of Census block points called
?localtree, via indexblocks().
Typically you would not need to download any datasets yourself, because EJAM just downloads these when the app starts (technically, when the R package is attached) (or only as needed in the case of certain datasets that are not always needed). Some datasets are installed along with the package, such as the blockgroupstats data. But large files like blockpoints are stored in a separate data repo, and EJAM downloads them from there. You might want your own local copies, though, for these reasons:
Attaching the package actually checks (using internal function
dataload_dynamic()) for copies in memory first (e.g.,
exists("quaddata", envir = globalenv())), then local disk
(using dataload_from_local() looking in the data folder of
the (source or installed) package, as defined by app_sys()
which is just a wrapper for system.file()), then finally
tries to download any still needed, using internal functions.