README.Rmd

---
output:
  github_document
---

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/"
)
```

# MNE-R: fast acccess to MNE-Python from within R 

<img src="man/figures/mne_logo.png" align="right" alt="" width="160" />

The [MNE-Python](https://mne-tools.github.io/stable/index.html) project provides a full tool stack for processing and visualizing electrophysiology data. That is, electroencephalography (EEG), magnetoencephalography but also intracranial EEG.
[MNE-R](https://mne-tools.github.io/mne-r/index.html) facilitates integrating this mature and extensive functionality into R-based data processing, visualization and statisticasl modeling.
This is made possible through the [reticulate](https://rstudio.github.io/reticulate/) package, which enables seamless integration of Python into R.

Currently, MNE-R is focussing on documenting how to use MNE-Python through R, based on familiar [MNE-examples](https://mne-tools.github.io/stable/auto_examples/index.html) while also showcasing what R can add to the game in terms of statistics and visualization functionality.

In the future, more R-functions may be added that facilitate the interaction with MNE-Python or implement complementary functionality.

The project is open to contributions.

## Getting Started

In order to use MNE-R, MNE-Python has to be installed with all its dependencies. Some configuration may be needed to make sure `reticulate` knows which Python installation to use. Please consider the [reticulate](https://rstudio.github.io/reticulate/articles/calling_python.html) and the [MNE](https://mne-tools.github.io/stable/getting_started.html) documentation. We generally recommend using the [Anaconda](https://www.anaconda.com) Python distribution and Python 3 instead of Python 2.

For seamlessly combining R and Python code in one Rmarkdown script, currently [Rstudio 1.2 preview](https://blog.rstudio.com/2018/10/09/rstudio-1-2-preview-reticulated-python/) is needed.

Currently, MNE-R can be installed from github.


```{r, eval = FALSE}
library(devtools)
devtools::install_github("mne-tools/mne-r")
```


To get started, simply laod the mne library

```{r}
library(mne)  # load mne and get the mne object

# the mne object wraps the loaded mne module inside Python
print(names(mne)[1:10])

# use dollar signs to access MNE modules, functions and objects
cat(mne$datasets$sample$data_path$`__doc__`)
```
## Known issues

- Currently, when making matplotlib figures from within R, the resulting image will not be rendered inside the Rstudio Rmarkdown chunk.
You will need to save, load and display the figure or explicitly, write Python code in a Python chunk, or explicitly make maptlotlib open a window:

```{r, eval=FALSE}
library(mne)
plt <- import("matplotlib.pyplot")  # get matplotlib handle

data_path <- mne$datasets$sample$data_path()
raw_fname <- paste(data_path,
                   'MEG', 
                   'samlpe',
                   'sample_audvis_filt-0-40_raw.fif',
                   sep = '/')
raw <- mne$io$read_raw_fif(raw_fname)
raw$plot()  # plot it!
plt$show()  # show the figure, then search for the window popping up.
```

- Some of the examples may depend on the latest MNE-Python code. We will try to provide patches little by little in MNE-Python or here.

## Roadmap

1. Add many vignettes and examples
2. Find common inconvenient steps and add convenience R functions
3. Motivate contributed examples and code from the R-EEG community
4. Add advanced content that leverages functionality unique to R