{"id":22852922,"url":"https://github.com/dipterix/rpyants","last_synced_at":"2026-05-14T21:36:45.772Z","repository":{"id":82704760,"uuid":"605771476","full_name":"dipterix/rpyANTs","owner":"dipterix","description":"An alternative R package for advanced normalization tools (ANTs)","archived":false,"fork":false,"pushed_at":"2025-07-21T02:48:35.000Z","size":9804,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-21T04:24:54.879Z","etag":null,"topics":["ants","brain","ieeg","mri","neuroimaging","normalization","python","r","registration"],"latest_commit_sha":null,"homepage":"http://dipterix.org/rpyANTs/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dipterix.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-23T21:39:18.000Z","updated_at":"2025-07-21T02:45:09.000Z","dependencies_parsed_at":"2024-11-08T19:22:49.810Z","dependency_job_id":"ca56cc13-6be3-4186-a3e6-0395793a592a","html_url":"https://github.com/dipterix/rpyANTs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dipterix/rpyANTs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FrpyANTs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FrpyANTs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FrpyANTs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FrpyANTs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dipterix","download_url":"https://codeload.github.com/dipterix/rpyANTs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FrpyANTs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278778974,"owners_count":26044259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ants","brain","ieeg","mri","neuroimaging","normalization","python","r","registration"],"created_at":"2024-12-13T06:09:56.566Z","updated_at":"2025-10-07T13:06:14.456Z","avatar_url":"https://github.com/dipterix.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"80%\",\n  cache = FALSE\n)\nlibrary(rpyANTs)\n```\n\n# rpyANTs\n\n\u003c!-- badges: start --\u003e\n[![CRAN status](https://www.r-pkg.org/badges/version/rpyANTs)](https://CRAN.R-project.org/package=rpyANTs)\n[![r-universe](https://rave-ieeg.r-universe.dev/badges/rpyANTs)](https://rave-ieeg.r-universe.dev/rpyANTs)\n[![R-check](https://github.com/dipterix/rpyANTs/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/dipterix/rpyANTs/actions/workflows/R-CMD-check.yaml)\n\u003c!-- badges: end --\u003e\n\n`rpyANTs` was detached from a `RAVE` ([Reproducible Analysis and Visualization of `iEEG`](https://rave.wiki)) module. It is now a standalone package that connects `ANTsPy` with R using seamless shared-memory. \n\nThis package was originally created for the following three purposes:\n\n* Portability\n  - Make `ANTs` easily accessible from the latest R and all major operating systems\n  - Allow `RAVE` or other code/scripts/frameworks to be reproducible since the code will be OS-invariant\n* Easy to install\n  - Automated installation that requires very little to no knowledge about compilers\n  - Installing `rpyANTs` takes less than 10 minutes\n  - The goal is to have minimum human intervention\n* Easy to embed\n  - Python scripts using `ANTsPy` can be executed from `rpyANTs` and R with no modification\n  - Built-in bilateral data conversions between Python and R allows image generated from Python to be analyzed/visualized in R and vice versa\n\n\n\u003e Disclaimer: This is a third-party maintained R package for `ANTs`. If you are looking for the `ANTsR` package by `B.B Avants`, please check [here](https://github.com/ANTsX/ANTsR).  \n\n\n## Installation\n\nThe installation requires one-line extra setup\n\n```r\n# Install from CRAN\ninstall.packages(\"rpyANTs\")\n\n# Install from nightly dev builder\n# install.packages(\"rpyANTs\", repos = \"https://dipterix.r-universe.dev\")\n\n\n# set up ANTs\nrpyANTs::install_ants()\n```\n\n`install_ants` creates an isolated `Python` environment managed by `RAVE`. This environment does not conflict nor affect your existing Python installations.\n\n### Upgrade `ANTs`\n\nTo upgrade `ANTs`, first update `rpyANTs`, then upgrade `ANTsPyx`\n\n```r\ninstall.packages(\"rpyANTs\")\nrpymat::add_packages(packages = \"antspyx\", pip = TRUE)\n```\n\n## How to use\n\nTo load `ANTs`\n\n```{r example1, eval = FALSE}\nlibrary(rpyANTs)\n\n# Whether ANTs is available\nants_available()\n\n# Load ANTs into R\nants\n```\n\nIn R, we use `$` to get module functions or class members. For example:\n\n```{r example2}\nants$add_noise_to_image\n```\n\nThe following R code translates Python code into R:\n\n```{r example3}\n# \u003e\u003e\u003e img = ants.image_read(ants.get_ants_data('r16'))\nimg \u003c- ants$image_read(ants$get_ants_data('r16'))\n\n# \u003e\u003e\u003e noise_image1 = ants.add_noise_to_image(img, 'additivegaussian', (0.0, 1.0))\nnoise_image1 \u003c- ants$add_noise_to_image(\n  img, 'additivegaussian', \n  noise_parameters = tuple(0.0, 1.0)\n)\n\n# \u003e\u003e\u003e noise_image2 = ants.add_noise_to_image(img, 'saltandpepper', (0.1, 0.0, 100.0))\nnoise_image2 \u003c- ants$add_noise_to_image(\n  img, 'saltandpepper', \n  noise_parameters = tuple(0.1, 0.0, 100.0)\n)\n\n# \u003e\u003e\u003e noise_image3 = ants.add_noise_to_image(img, 'shot', 1.0)\nnoise_image3 \u003c- ants$add_noise_to_image(\n  img, 'shot', \n  noise_parameters = 1.0\n)\n\n# \u003e\u003e\u003e noise_image4 = ants.add_noise_to_image(img, 'speckle', 1.0)\nnoise_image4 \u003c- ants$add_noise_to_image(\n  img, 'speckle', \n  noise_parameters = 1.0\n)\n\n# \u003e\u003e\u003e trans = ants.create_ants_transform(\n# \u003e\u003e\u003e   dimension=2, matrix=[[0.707, 0.707], [-.707, 0.707]],\n# \u003e\u003e\u003e   translation=[-53, 128])\ntrans \u003c- as_ANTsTransform(matrix(\n  c(0.707, 0.707, -53,\n    -0.707, 0.707, 128),\n  nrow = 2, byrow = TRUE\n), dimension = 2)\n\n\n# \u003e\u003e\u003e noise_image4 = trans.apply_to_image(noise_image4)\nnoise_image4 \u003c- trans$apply_to_image(noise_image4)\n\n```\n\nTo load imaging data into R\n\n```{r load-image-into-r, fig.width=6, fig.height=3}\n# Use [] to convert ANTsImage into R array\nis.array(img[])\n\n# plot via R\nlayout(matrix(c(1,1,2,3,1,1,4,5), nrow = 2, byrow = TRUE))\npar(mar = c(0.1, 0.1, 0.1, 0.1), bg = \"black\", fg = \"white\")\npal \u003c- grDevices::gray.colors(256, start = 0, end = 1)\n\nimage(img[], asp = 1, axes = FALSE, \n      col = pal, zlim = c(0, 255), ylim = c(1, 0))\nimage(noise_image1[], asp = 1, axes = FALSE, \n      col = pal, zlim = c(0, 255), ylim = c(1, 0))\nimage(noise_image2[], asp = 1, axes = FALSE, \n      col = pal, zlim = c(0, 255), ylim = c(1, 0))\nimage(noise_image3[], asp = 1, axes = FALSE, \n      col = pal, zlim = c(0, 255), ylim = c(1, 0))\nimage(noise_image4[], asp = 1, axes = FALSE, \n      col = pal, zlim = c(0, 255), ylim = c(1, 0))\n```\n\n## Advanced use case\n\n### Run/Debug `Python` scripts\n\n`rpyANTs` ports functions that allows to run `Python` scripts. For example:\n\n\n```{r}\nlibrary(rpyANTs)\n\nscript_path \u003c- tempfile(fileext = \".py\")\nwriteLines(con = script_path, text = r\"(\n\n# This is Python script\nimport ants\nprint(ants.__version__)\n\n)\")\n\nrun_script(script_path)\n```\n\nYou can also run `Python` interactive in R (yes, you are correct). Simply run\n\n```r\nrpyANTs::repl_python()\n```\n\nThe console prefix will change from `\u003e` to `\u003e\u003e\u003e`, meaning you are in `Python` mode:\n\n```\n\u003e rpyANTs::repl_python()\nPython 3.8.16 (/Users/dipterix/Library/r-rpymat/miniconda/envs/rpymat-conda-env/bin/python3.8)\nReticulate 1.26 REPL -- A Python interpreter in R.\nEnter 'exit' or 'quit' to exit the REPL and return to R.\n\u003e\u003e\u003e \n```\n\nTry some Python code!\n\n```\n\u003e\u003e\u003e import ants\n\u003e\u003e\u003e help(ants.registration)\n```\n\nTo exit Python mode, type `exit` (no parenthesis) and hit enter key\n\n```\n\u003e\u003e\u003e exit\n\u003e \n```\n\n\n### Data conversions\n\nNative R variables can be easily converted to `Python` and back via `r_to_py` and `py_to_r`.\n\nFor example\n\n```{r}\n# R to Python\nr_to_py(1)\nr_to_py(1L)\n\n# Python to R\npy_obj \u003c- py_list(1:3)\nclass(py_obj)  # \u003c- this is a python object\n\npy_to_r(py_obj)\n```\n\nYou can also use variables created in R from Python or vice versa:\n\nIn the following example, an R object `object_r` is created. In Python, it can be accessed (read-only) via `r.object_r`\n\n\n```\n\u003e object_r \u003c- c(1,2,3)\n\u003e repl_python()\nPython 3.8.16 (/Users/dipterix/Library/r-rpymat/miniconda/envs/rpymat-conda-env/bin/python3.8)\nReticulate 1.26 REPL -- A Python interpreter in R.\nEnter 'exit' or 'quit' to exit the REPL and return to R.\n\u003e\u003e\u003e r.object_r\n[1.0, 2.0, 3.0]\n```\n\nSimilarly, a Python object `object_py` is created, and it can be read from `py$object_py`:\n\n```\n\u003e\u003e\u003e import numpy as np\n\u003e\u003e\u003e object_py = np.array([2,3,4])\n\u003e\u003e\u003e exit\n\u003e py$object_py\n[1] 2 3 4\n```\n\n## Known issues\n\n### Variable types\n\nR is not a type-rigid language. Some functions in `ANTsPy` require specific variable types that are often vague in R. For example the `dimension` argument in function `ants$create_ants_transform` needs to be an integer, but R's default numerical values are `double`. In this case, variable formats need to be explicitly given.\n\nHere are several examples\n\n1. Explicit integers\n\n```r\n# ants$create_ants_transform(dimension = 3)     # \u003c- error\nants$create_ants_transform(dimension = 3L)      # \u003c XXXL is an explicit integer\n```\n\n2. `Tuple`, `list`, and `dictionary`\n\nA Python `tuple` is a vector that cannot alter lengths. \n\n```r\n# Wrong as `aff_iterations` needs to be a tuple\n# ants$registration(fixed, moving, ..., aff_iterations = c(6L, 4L, 2L, 1L))\n\nants$registration(fixed, moving, ..., aff_iterations = tuple(6L, 4L, 2L, 1L))\n```\n\nSimilar conversions can be done via `py_list`, `py_dict`.\n\n3. Convert `TRUE` vs. `FALSE`\n\nA Python module can be imported with auto-conversion (argument `convert`) set to `TRUE` or `FALSE`. When auto-conversion is on, the Python function results will be converted to R objects automatically. For example,\n\n```{r}\nnp \u003c- import(\"numpy\", convert = TRUE)\nnp$eye(4L)\n```\n\nThe `numpy` array is automatically translated as an R matrix. While this is convenient, this automated conversion could cause some issues when the function results are further passed into another Python function. For example, the following code will raise errors. \n\n```r\n\u003e np \u003c- import(\"numpy\", convert = TRUE) \n\u003e ants \u003c- load_ants()\n\u003e \n\u003e image \u003c- ants$image_read(ants$get_ants_data('mni'))\n\u003e image_array \u003c- np$asarray(list(image, image))\n\u003e \n\u003e ants$plot_grid(image_array, slices = 100L)\n\nError in py_call_impl(callable, dots$args, dots$keywords) :\nMatrix type cannot be converted to python (only integer, numeric, complex, logical, and character matrixes can be converted\n```\n\nThe error is raised because `numpy` has `convert=TRUE`, hence `image_array` is converted to an R list with each element being a `ANTsImage` instance. Calling `ants$plot_grid` needs R-to-Python conversion for all input variables, including `image_array`. However this conversion makes `image_array` a Python list instead of `numpy` array, violating the input format.\n\nA safer way is to keep in the Python format, i.e. `convert=FALSE`. In this mode, function results will not be converted back to R (you need to manually make conversion by yourself via `py_to_r`). Now the following example works.\n\n```r\n\u003e np \u003c- import(\"numpy\", convert = TRUE) \n\u003e ants \u003c- load_ants()\n\u003e \n\u003e image \u003c- ants$image_read(ants$get_ants_data('mni'))\n\u003e image_array \u003c- np$asarray(list(image, image))\n\u003e \n\u003e ants$plot_grid(image_array, slices = 100L)\n```\n\n\u003e Object `ants` in `rpyANTs` is a non-conversion Python module. Object `py` is a auto-conversion Python module\n\n\n### Operators\n\nIn Python, operators on `ANTsImage`, such as `img \u003e 5` are defined. Such operators is being supported in R as `S3` generic functions. Don't worry if you don't know what is `S3` generic, see the following examples:\n\n\n```r\nlibrary(rpyANTs)\nimage \u003c- ants$image_read(ants$get_ants_data('mni'))\nprint(image)\ndim(image)\nrange(image)\n\ny1 \u003c- (image \u003e 10) * 8000\n\ny2 \u003c- image\ny2[y2 \u003c 10] \u003c- 4000\n\ny3 \u003c- log(image + 1000)\ny3 \u003c- (y3 - min(y3)) / (max(y3) - min(y3)) * 8000\n\nants_plot_grid(\n  list(image, y1, y2, y3),\n  slices = 100, shape = c(1, 4),\n  vmin = 0, vmax = 8000\n)\n```\n\n\u003cimg src=\"man/figures/README-s3-generic-showcase-1.png\" width=\"100%\" /\u003e\n\n\nAlthough the operator generics have been implemented for common classes such as `ANTsImage` and `ANTsTransform`. Many  are still under development and not supported. In this case, you might want to use the following workaround methods. You are more than welcome to post a wish-list or issue ticket to the [`Github` repository](https://github.com/dipterix/rpyANTs/issues)\n\nAlternative version 1: call operators directly\n\n```r\nlibrary(rpyANTs)\nimage \u003c- ants$image_read(ants$get_ants_data('r16'))\n\n# The followings are the same\n# threshold \u003c- image \u003e 10\nthreshold \u003c- image$`__gt__`(10)\nants$plot(threshold)\n```\n\nWork-around version 2: If you don't know how Python operators work, use Python directly\n\n```r\nlibrary(rpyANTs)\nimage \u003c- ants$image_read(ants$get_ants_data('r16'))\n\n# Create an R variable from Python!\npy_run_string(\"r.threshold = r.image \u003e 10\", local = TRUE, convert = FALSE)\nants$plot(threshold)\n```\n\n\n## Citation\n\nThis is a general citation for `ANTs`:\n\n\u003e Avants, B.B., Tustison, N. and Song, G., 2009. Advanced normalization tools (ANTS). The Insight Journal, 2(365), pp.1-35.\n\nIf you are using `rpyANTs` through `RAVE` or `YAEL`, please also cite:\n\n\u003e Magnotti, J.F., Wang, Z. and Beauchamp, M.S., 2020. RAVE: Comprehensive open-source software for reproducible analysis and visualization of intracranial EEG data. NeuroImage, 223, p.117341.\n\n## License\n\nThis package `rpyANTs` is released under Apache-2.0 license (Copyright: Zhengjia Wang). \nThe underlying `ANTsPy` is released under Apache-2.0 license (Copyright: ANTs contributors). \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdipterix%2Frpyants","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdipterix%2Frpyants","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdipterix%2Frpyants/lists"}