Package 'ravemanager'

Title: Manage 'RAVE' Packages
Description: Manages installation, upgrade, and removal of packages and corresponding dependence for the project 'RAVE' (R Analysis and Visualization for 'iEEG').
Authors: Zhengjia Wang [aut, cre]
Maintainer: Zhengjia Wang <[email protected]>
License: MIT + file LICENSE
Version: 1.0.72
Built: 2026-10-08 22:22:07 UTC
Source: https://github.com/dipterix/ravemanager

Help Index

Install & Configure 'python' environment for 'RAVE'

Description

Installs 'python' environment for 'RAVE'

Usage

validate_python(verbose = TRUE, env_name = NA)

configure_antspynet()

configure_python(python_ver = "3.11", verbose = TRUE)

remove_conda(ask = TRUE)

ensure_rpymat(env_name = NA)

Arguments

verbose

whether to verbose messages
env_name

'conda' environment to use; set to NA to verify the default environment
python_ver

python version; default is automatically determined. If a specific python version is needed, please specify explicitly, for example, python_ver='3.8'
ask

whether to ask before resetting the 'python' environment

Details

Use ravemanager::configure_python() to install and configure python environment using miniconda. The conda binary and environment will be completely isolated. This means the installation will be safe and it will not affect any existing configurations on the computer.

In this isolated environment, the following packages will be installed: numpy, scipy, pandas, h5py, jupyterlab, pynwb, mat73, mne. You can always add more conda packages via rpymat::add_packages(...) or pip packages via rpymat::add_packages(..., pip = TRUE).

To use the 'python' environment, please run rpymat::ensure_rpymat() to activate in your current session. If you are running via 'RStudio', open any 'python' script and use 'ctrl/cmd+enter' to run line-by-line. To switch from R to python mode, using command rpymat::repl_python()

A jupyterlab will be automatically installed during the configuration. To launch the jupyterlab, use rpymat::jupyter_launch()

If you want to remove this conda environment, use R command rpymat::remove_conda(). This procedure is absolutely safe and will not affect your other installations.

Examples

## Not run: 

# -------- Install & Configure python environment for RAVE --------
ravemanager::configure_python()

# Add conda packages
rpymat::add_packages("numpy")

# Add pip packages
rpymat::add_packages("nipy", pip = TRUE)

# -------- Activate RAVE-python environment --------
rpymat::ensure_rpymat()

# run script from a temporary file
f <- tempfile(fileext = ".py")
writeLines(c(
  "import numpy",
  "print(f'numpy installed: {numpy.__version__}')"
), f)
rpymat::run_script(f)

# run terminal command within the environment
rpymat::run_command("pip list")

# run python interactively, remember to use `exit` to exit
# python mode
rpymat::repl_python()




## End(Not run)

Print 'RAVE' debugging information

Description

This function will generate a report. Please include the report when you file an issue. Useful for reporting issues to 'RAVE' developers.

Usage

debug_info(max_lines)

Arguments

max_lines

maximum number of log entries to print

Print out 'RAVE' session log

Description

Print out 'RAVE' session log

Usage

export_logs(
  session = NULL,
  modules = NULL,
  max_lines = Sys.getenv("RAVEMANAGER_BUGREPORT_MAX", "200"),
  verbose = TRUE
)

Arguments

session

'RAVE' session string; default is the most recent (active) session
modules

which module to read; default is all
max_lines

maximum number of lines to read; default is 200
verbose

whether to print out the log; default is true

Value

characters of log

Find packages with empty files

Description

Check whether packages are installed correctly. In rare cases (possibly network issues), packages downloaded contain empty files. This function provides a method to check empty files in packages.

Usage

find_packages_with_empty_files(lib = get_libpaths(check = TRUE))

Arguments

lib

library path where packages are installed; default is set to user library path.

Value

A list of packages (and files) containing empty files.

Examples

find_packages_with_empty_files()

Install/Update R or Python packages to RAVE environment

Description

Install/Update R or Python packages to RAVE environment

Usage

add_r_package(
  pkg,
  lib = get_libpaths(check = TRUE),
  repos = get_mirror(),
  type = getOption("pkgType"),
  ...,
  INSTALL_opts = "--no-lock"
)

add_py_package(pkg, method = c("pip", "conda"))

Arguments

pkg

name of the package
repos, lib, type, INSTALL_opts, ...

internally used
method

whether to use 'pip' or 'conda'; default is 'pip'

Value

Nothing

Examples

## Not run: 


# ---- R --------------------------------------------------------
# Install R packages (CRAN, BioC, or RAVE's repository)
add_r_package("ravebuiltins")
add_r_package("rhdf5")

# Install from Github (github.com/dipterix/threeBrain)
add_r_package("dipterix/threeBrain")

# Install Github branch
add_r_package("dipterix/threeBrain@custom-electrode-geom")

# ---- Python ----------------------------------------------------

# Normal pypi packages
add_py_package("threebrainpy")

# Add through conda
add_py_package("fftw", method = "conda")



## End(Not run)

Alternative graphics device for RStudio

Description

Replaces the default RStudio graphics device with a light-weight shiny application that renders plots as SVG images in the viewer pane. This is useful when the built-in device is unavailable or misbehaves, for example on remote or containerized RStudio servers.

pv_init starts the viewer and installs the hooks, pv_off removes them and shuts the viewer down, pv_show sends the current plot to the viewer manually, and pv_dims reports the viewer size in pixels.

pv_off also closes the off-screen devices that pv_init opened. Since graphics::par() settings belong to a device, this resets them: the next plot starts on a fresh device with the defaults. Devices opened by anything else are left untouched.

Usage

pv_init(...)

pv_off(...)

pv_show(...)

pv_dims(...)

Arguments

...

passed to the internal handlers; pv_init accepts hooks, a character vector of new-page hook names to watch, plus watch and format, see 'Details'

Details

pv_init only takes effect in interactive RStudio sessions, and requires the packages svglite, rstudioapi, callr, httpuv, and shiny to be installed; otherwise the call is a no-op. When enabled, the graphics device option is redirected to an off-screen pdf device with the display list enabled, a top-level task callback named tools:plotview re-renders the recorded plot whenever a new page is drawn, and helper functions (.pv_show, .pv_dims, .pv_start, .pv_stop) are attached to the search path under tools:plotview.

Incremental drawing such as points(), lines(), or legend() runs no hook, so the hooks alone would miss it. Instead the callback compares the length of the device display list with the length at the last render, and re-renders when it differs; the plot.new hook still covers the case of a new page that happens to have the same length. This means the display list is recorded once per top-level command, which is the cost of the feature; pass watch = FALSE to pv_init to disable it and fall back to the hooks alone.

While a shiny application is running in the current session (that is, shiny::isRunning() is TRUE or a reactive domain is active), the hooks step aside: new devices are opened with the original device and plots are not captured, so shiny renders as usual. Normal behavior resumes once the application stops. The viewer's own application does not count, as it runs in a separate process.

The viewer runs in a background R process and reports its own width, height, and device pixel ratio back to the main session, so plots are re-drawn at the size of the viewer pane and stay sharp on high-density displays. Only the 20 most recent pages are kept on disk.

Pages are written as PNG using ragg when it is installed, falling back to grDevices::png() with the cairo back end and then to whatever png() offers. PNG keeps the cost of a render bounded: SVG is faster for simple line art, but a scatter plot of 100000 points or a raster image takes several times longer to write and produces a file in the tens of megabytes, which the browser then has to parse. Pass format = "svg" to pv_init for vector output instead, which additionally requires svglite. The raster output is re-rendered whenever the viewer changes size, so it is never scaled up.

The history holds one entry per page: plot() and friends start a new one, while incremental drawing, a refresh, and a resize re-render the current entry in place instead of appending a copy of it. Three buttons in the top-right corner of the viewer navigate that history: previous steps back one page (and does nothing at the oldest one still on disk), next steps forward one page, and the last button jumps to the newest page. Stepping forward from the newest image, or pressing the last button, also asks the main session to re-render the current plot, the same as calling pv_show(). Such a request is passed back through the viewer configuration file, which the main session polls once per second using later::later while registered; resizing the viewer is picked up the same way. The polling stops on pv_off().

Value

pv_init, pv_off, and pv_show invisibly return a logical value indicating whether the corresponding action succeeded. pv_dims returns an integer vector of length two: the viewer width and height in pixels, defaulting to c(1000L, 700L) when the viewer has not reported its size.

Examples

## Not run: 

# Start the alternative graphics device
ravemanager::pv_init()

plot(1:10)

# Query the viewer size
ravemanager::pv_dims()

# Re-send the current plot, e.g. after resizing the viewer
ravemanager::pv_show()

# Restore the default device
ravemanager::pv_off()


## End(Not run)

Install or upgrade 'RAVE'

Description

Installs the newest version of 'RAVE' and its dependence packages; executes the scripts to finalize installation to update configuration files.

Usage

add_shortcuts()

finalize_installation(
  packages = NULL,
  upgrade = c("config-only", "ask", "always", "never", "data-only"),
  async = FALSE,
  ...
)

clear_cache()

install(
  allow_cache = FALSE,
  upgrade_manager = FALSE,
  finalize = TRUE,
  force = FALSE,
  python = FALSE,
  migrate_packages = FALSE,
  lib_path = NA,
  ...
)

install_dev(branch_name)

update_rave(
  allow_cache = FALSE,
  upgrade_manager = FALSE,
  finalize = TRUE,
  force = FALSE,
  python = FALSE,
  migrate_packages = FALSE,
  lib_path = NA,
  ...
)

upgrade_installer(reload = TRUE)

Arguments

packages

packages to run finalizing installation scripts
upgrade

upgrade type
async

whether to execute finalizing installation scripts in other processes
...

passed to internal functions
allow_cache

whether to allow cache; default is true
upgrade_manager

whether to upgrade the installer (ravemanager) before updating other packages
finalize

whether to run finalizing installation scripts
force

whether to force updating packages even the installed have the latest versions
python

whether to install python; default is false
migrate_packages

whether to migrate (copy) packages installed in the system path to the user library; used as alternative option when there are existing packages installed in the system library path that could be hard to resolve or out-dated; default is FALSE
lib_path

library path where 'RAVE' should be installed; default is automatically determined.
branch_name

for 'RAVE' developers, development branch to install
reload

whether to reload ravemanager after installation; default is true. This tries to load the upgraded ravemanager without restarting the R session; however, this solution not always works. In such case, restarting R session is always the solution.

Value

Nothing

Make a profile allowing portable RAVE configurations

Description

Make a profile allowing portable RAVE configurations

Usage

make_profile(profile = shared_profile(), profile_name = "default")

use_profile(profile_name = "default", auto_install = TRUE)

Arguments

profile

profile configurations
profile_name

name of the profile
auto_install

whether to automatically install RAVE with the profile; default is TRUE

Examples

## Not run: 

# Make a template profile first. You may edit this profile
# to redirect paths to shared drive, SSD etc.
# Make sure you have the write permissions

make_profile()

# Test and install the profile
use_profile()

# Edit in your .Rprofile via `usethis::edit_r_profile()`
# add this line
ravemanager::use_profile(auto_install = FALSE)


## End(Not run)

Get current 'RAVE' installer's version

Description

Get current 'RAVE' installer's version

Usage

ravemanager_version()

Value

Returns the ravemanager version

Run tutorials

Description

Run tutorials

Usage

run_tutorials(topic = NULL, ...)

Arguments

topic

integers of which topic to launch, leave it blank, then 'RAVE' will ask you to select a topic
...

other parameters to pass to shiny::runApp()

Examples

## Not run: 

ravemanager::run_tutorials()


## End(Not run)

Get system requirements for 'RAVE'

Description

Get system requirements for 'RAVE'

Usage

system_requirements(
  os = NULL,
  os_release = NULL,
  curl = Sys.which("curl"),
  sudo = FALSE,
  ...
)

Arguments

os, os_release

operating system and release version, currently only supports 'ubuntu', 'centos', 'redhat', 'opensuse', and 'sle'; see https://github.com/rstudio/r-system-requirements#operating-systems
curl

the location of the curl binary on your system
sudo

whether to pre-pend 'sudo' to the commands
...

reserved for future use

Examples

if("remotes" %in% loadedNamespaces()) {
# Please check your operating system & version!!!

# =============== On Ubuntu Linux ===============

# Ubuntu 20
ravemanager::system_requirements("ubuntu", "20")

# Ubuntu 18
ravemanager::system_requirements("ubuntu", "18")

# Ubuntu 16
ravemanager::system_requirements("ubuntu", "16")

# =============== On Red Hat Enterprise Linux ===============

# Red Hat Enterprise Linux 8
ravemanager::system_requirements("redhat", "8")

# Red Hat Enterprise Linux 7
ravemanager::system_requirements("redhat", "7")

# =============== On CentOS ===============

# Red Hat Enterprise Linux 8
ravemanager::system_requirements("centos", "8")

# Red Hat Enterprise Linux 7
ravemanager::system_requirements("centos", "7")

# =============== On OpenSUSE ===============

# openSUSE 42.3
ravemanager::system_requirements("opensuse", "42")

# =============== On SUSE Linux Enterprise ===============

# SUSE Linux Enterprise 12.3
ravemanager::system_requirements("sle", "12")

}

Uninstall RAVE components

Description

Remove cache, python, and/or all settings. Please be aware that R, 'RStudio', and already installed R packages will not be uninstalled. Please carefully read printed messages.

Usage

uninstall(components = c("cache", "python", "all"))

Arguments

components

which component to remove, see example for choices.

Examples

if ( FALSE ) {

  # remove cache only
  ravemanager::uninstall("cache")

  # remove python environment
  ravemanager::uninstall("python")

  # remove all sample data, settings files
  ravemanager::uninstall("all")

}

Print out 'RAVE' version information

Description

Print out 'RAVE' version information

Usage

version_info(vanilla = FALSE, auto_restart = !get_os() %in% "windows", ...)

Arguments

vanilla

whether to use vanilla packages in this function
auto_restart

whether to automatically install ravemanager if an update is available and apply restart; default is true on non-Windows machine
...

reserved for future use

Helper function to view 'htmlwidgets' in 'WebAssembly'

Description

Helper function to view 'htmlwidgets' in 'WebAssembly'

Usage

webr_view(widget)

Arguments

widget

'htmlwidgets' widget

Value

nothing