getting-started.Rmd

---
title: "Getting Started with pythonR"
author: "Kyle Barrett"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{getting-started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(eval = FALSE)
```


```{r load package, eval = FALSE}
library(pythonR)
```

## Setting up your environment

You begin by setting up a python environment (conda or virtual) with the required imports you will need:
```{r, eval = FALSE}
## With a conda environment (the default) ##
py_env <- setup_py_env(py_pkgs = c("pandas", "numpy", "scipy"))
py_env

# Specify a specific conda environment and conda installation path
conda_envs <- reticulate::conda_list()
conda_paths <- pythonR::get_conda_paths()

py_env <- setup_py_env(
  py_pkgs = c("pandas", "numpy", "scipy", "tiktoken"),
  conda_path = conda_paths[1],
  conda_env = conda_envs$python[1],
  update = TRUE,
  pip = TRUE
)

## Using a virtual environment ##
py_env <- setup_py_env(py_pkgs = c("pandas", "numpy", "scipy"), py_env = "virtual")
py_env

# shutdown virtual environment
shutdown_virtual_env(py_env$env_name)
```


Note that you can always install packages to the environment you created at a later time:
```{r, eval = FALSE}
# Installing a package after setup (works with both environment types)
py_env <- pythonR::setup_py_env(py_pkgs = c("pandas", "numpy"))
pythonR::install_py_pkgs(py_pkgs = c('scipy'), env_name = py_env$env_name)

# View currently installed packages using reticulate
reticulate::py_list_packages(py_env$env_path)

# confirm that installed packages can be imported
required_py_pkgs <- c('pandas', 'scipy', 'numpy')
pythonR::check_py_pkgs_installed(required_py_pkgs)
```


## Create a python-based function

Additional helper functions are provided for ensuring required python packages are installed or importing them at various stages within an R function/script. A simple example is provided below, but see `?pythonR_examples` for fully fleshed out examples and more details. Note that some python modules may not be able to be installed/imported this way, and may require a more custom installation.


```{r}
my_py_function <- function(){
  # Check that python packages are installed
  required_py_pkgs <- c('pandas', 'scipy', 'numpy')
  pythonR::check_py_pkgs_installed(required_py_pkgs)
  
  # import main python modules
  pythonR::import_main_py()
  
  # import required python packages
  pythonR::import_py_pkgs(py_pkgs = required_py_pkgs)
  
  # source python script or load python functions into R
  
  # do something...
}
```


```{r, eval = FALSE}
# Set up a python environment once per R session
py_env <- pythonR::setup_py_env(
  py_pkgs = c("pandas", "numpy", "scipy"),
  py_env = "conda"
)

# Use any python functions coded in R
my_py_function()
```

## Provided python-based functions
`pythonR` comes with some example functions you can reference when developing your own:

```{r, eval = FALSE}
# Get list of available examples.
ls(pythonR_examples)
#> [1] "py_add"        "py_array"      "py_check_path"
```


```{r, eval = FALSE}
# View the functions
get("py_add", envir = pythonR_examples)
#> expression({
#> # Simple python function
#> #
#> # @param x a number
#> # @param y a number
#> #
#> # @details
#> # This function does not require imports or virtual environment (much faster)
#> py_add <- function(
#>     x = 5,
#>     y = 10
#> ){
#> 
#>   # source specific python script
#>   py_script <- file.path(EXAMPLE_PYTHON_DIR, 'script-add.py')
#> 
#>   # Source python script if python is installed
#>   if(isTRUE(python_is_installed())){
#>    reticulate::source_python(py_script)
#>   }
#> 
#>   # `py_add` is a function defined in `py_script`
#>   sum <- py_add(x, y)
#> 
#>   return(sum)
#> }
#> })
```


```{r, eval = FALSE}
# Assign the function to use it
py_add <- get_py_example("py_add")
py_add(3, 4)
#> [1] 7
```