Skip to content

first pass at documentation update #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
loganjohnson0 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

first pass at documentation update #17

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
951cc67
first pass at documentation update
loganjohnson0 Aug 27, 2025
f7a93c4
typos and clarifications
loganjohnson0 Aug 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 74 additions & 44 deletions vignettes/configuration.rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,21 +16,32 @@ knitr::opts_chunk$set(

## General configuration

`sasquatch` works by utilizing the [`SASPy`](https://sassoftware.github.io/saspy/) python package, similar to packages like [`sasr`](https://github.com/insightsengineering/sasr) or [configSAS](https://github.com/baselr/configSAS). This means everything we do to connect R and SAS, needs to go through `SASPy`.
`sasquatch` works by utilizing the [`SASPy`](https://sassoftware.github.io/saspy/) python package, an open source package created by the [developers of SAS](https://support.sas.com/en/software/saspy.html). There are some configuration steps necessary by you the user to get `SASPy` ready to work with `sasquatch`.

Configuration steps for `SASPy` can vary greatly depending on the SAS client, but all configuration is specified within the `sascfg_personal.py` file inside of the `SASPy` package.
### Initial python environment setup

### Setting up
After downloading `sasquatch`, your next step will be to either create a python environment or associate an existing environment to work with `sasquatch` and `SASPy`.

Use the following function to create a `sascfg_personal.py` templated file.
If you do not have a python environment, you will need the `reticulate` package and can run `reticulate::use_virtualenv("r-saspy")`, which will create a new python virtual environment named "r-saspy".

Next, you will configure your python environment to work with `SASPy`. `sasquatch` has a convenient function `sasquatch::install_saspy()` to install `SASPy` and the required python packages. If you manually created the "r-saspy" python environment with `reticulate`, you shouldn't have to specify other options in `sasquatch::install_saspy()`. If you have an existing python environment, you can specify the path to your python environment:

```{r, eval = FALSE}
sasquatch::configure_saspy()
sasquatch::install_saspy(
envname = "NAME/OR/FULL/PATH/TO/PYTHON/ENV",
new_env = FALSE
)
```

**Note**: `sasquatch::configure_saspy()` will configure `reticulate`'s current python version. You may have to run `reticulate::use_virtualenv("r-saspy")` in order to specify that you want to configure that python environment.
### Initial `SASPy` setup

After setting up your python environment and installing `SASPy`, you next need to configure a `sascfg_personal.py` file. With `sasquatch` you can set this up by running:

```{r, eval = FALSE}
sasquatch::configure_saspy()
```

This will create a file like the following:
Within your python environment, you should find within the `saspy` library folder a file named `sascfg_personal.py` with the basic structure:

```{python, eval = FALSE}
SAS_config_names = ['config_name']
Expand All @@ -40,19 +51,43 @@ config_name = {
}
```

`SAS_config_names` should contain a string list of the variable names of all configurations. Configurations are specified as dictionaries, and configuration parameters depend on the access method.
::: callout-important
It is important to understand that this is a basic template that needs to be further modified for your specific environment.
:::

### Configuring `SASPy` to your system {#basic-saspy}

The `config_name` placeholders should be replaced with options, such as `winlocal`, `ssh`, or other options listed on the [`SASPy` page](https://sassoftware.github.io/saspy/configuration.html) for `SAS_config_names` that best suit your computer system and SAS setup.

There are other required configuration options for `SASPy`, which vary depending on 1) what type of SAS instance you are connecting to, and 2) whether you are connecting to SAS locally on your machine or via a remote connection. Understanding your system setup will be important in defining the configuration options for your specific `sascfg_personal.py` file. See the [Access methods section](#access-methods) for the various deployments and possible configurations and refer to the [`SASPy` configuration page](https://sassoftware.github.io/saspy/configuration.html) for other required options.

Additionally, some access methods will require an additional authentication file (`.authinfo` for Linux and Mac, `_authinfo` for Windows) stored in the user's home directory, which are constructed as follows:
For example, if you have SAS installed locally on a Windows machine, you will edit your `sascfg_personal.py` file to define `winlocal` in place of `conf_name`. You will also include the path to a Java executable, which is frequently shipped with SAS and can be found often at the path shown below. `SASPy` requires one additional option with [Windows local](https://sassoftware.github.io/saspy/configuration.html#local), which is to include the `sspiauth.dll` file in your PATH; however, `SASPy` only recommends listing the path to the directory, not the path to the `sspiauth.dll` file itself. All together, your `sascfg_personal.py` file could end up looking like:

```{python, eval = FALSE}
import os

os.environ["PATH"] += ";C:\\Program Files\\SASHome\\SASFoundation\\9.4\\core\\sasext"

SAS_config_names = ["winlocal"]

winlocal = {
"java": "C:\\Program Files\\SASHome\\SASPrivateJavaRuntimeEnvironment\\9.4\\jre\\bin\\java"
}
```

::: callout-caution
Again, remember that your computer system and SAS instance may differ drastically from this specific example. You may have additional requirements distinct from this example of Windows and local SAS. Please refer to the [`SASPy` configuration page](https://sassoftware.github.io/saspy/configuration.html) for requirements and support for your specific setup.
:::

#### Further configuration

Some access methods will require an additional authentication file (`.authinfo` for Linux and Mac, `_authinfo` for Windows) stored in the user's home directory, which are constructed as follows:

```
config_name user {your username} password {your password}
```

### Access methods

From here, you will need to fill out the `config_name` dictionary with your
configuration definition. The required definition fields will depend on the
access method required to connect to your SAS client.
### Access methods {#access-methods}

The following is a breakdown of the access method by SAS deployment:

Expand Down Expand Up @@ -83,10 +118,7 @@ The following is a breakdown of the access method by SAS deployment:
* On Windows
* HTTP - must have compute service configured and running (Viya V3.5 and V4)

### More information

Further documentation and examples for each access type can be found within the
[`SASPy` configuration documentation](https://sassoftware.github.io/saspy/configuration.html)
There is a file called `sascfg.py`, located in the same folder as the `sascfg_personal.py` file, that outlines further configuration options and details for numerous computer and software setups. This `sascfg.py` file can be a good short summary of various configuration options in a shorter and more succinct form. However, many of these options are not necessary to configure and are advised against configuring, unless you have experience with these options and understand their use. Most users should be able to configure basic options, like in [the example above](#basic-saspy) and follow and modify the requirements for their system based on the [`SASPy` configuration documentation](https://sassoftware.github.io/saspy/configuration.html).

## SAS On Demand for Academics configuration

Expand All @@ -100,11 +132,9 @@ Once you have set up your account, log in and note the ODA server (in the pictur

### Java installation

ODA relies on the IOM access method, which requires Java. Make sure Java is installed on your system. You can download Java from [their website](https://www.java.com/en/download/).
ODA also requires you to install [additional encryption jars](https://support.sas.com/downloads/package.htm?pid=2494) within the `java/iomclient` folder inside of your `SASPy` installation.
ODA relies on the IOM access method, which requires Java. Make sure Java is installed on your system. You can download Java from [their website](https://www.java.com/en/download/). ODA also requires you to install [additional encryption jars](https://support.sas.com/downloads/package.htm?pid=2494) within the `java/iomclient` folder inside of your `SASPy` installation.

**Note:** Adding your java installation to path will help `sasquatch::configure_saspy()` find your Java installation path. Otherwise, note the path so that you can manually enter it
within your `sascfg_personal.py` file.
**Note:** Adding your java installation to path will help `sasquatch::configure_saspy()` find your Java installation path. Otherwise, note the path so that you can manually enter it within your `sascfg_personal.py` file.

### Configuration

Expand All @@ -121,30 +151,30 @@ sasquatch::configure_saspy(template = "oda")
- Create a `sascfg_personal.py` file with all the relevant configuration information.
Generally, your `sascfg_personal.py` will look something like:
```python
SAS_config_names=['oda']
oda = {
'java' : 'path_to_java', # replace with your java path
# Uncomment the one for your region
#US Home Region 1
# 'iomhost' : ['odaws01-usw2.oda.sas.com','odaws02-usw2.oda.sas.com','odaws03-usw2.oda.sas.com','odaws04-usw2.oda.sas.com'],
#US Home Region 2
#'iomhost' : ['odaws01-usw2-2.oda.sas.com','odaws02-usw2-2.oda.sas.com'],
#European Home Region 1
#'iomhost' : ['odaws01-euw1.oda.sas.com','odaws02-euw1.oda.sas.com'],
#Asia Pacific Home Region 1
#'iomhost' : ['odaws01-apse1.oda.sas.com','odaws02-apse1.oda.sas.com'],
#Asia Pacific Home Region 2
#'iomhost' : ['odaws01-apse1-2.oda.sas.com','odaws02-apse1-2.oda.sas.com'],
'iomport' : 8591,
'authkey' : 'oda',
'encoding' : 'utf-8'
}
```
SAS_config_names=['oda']
oda = {
'java' : 'path_to_java', # replace with your java path
# Uncomment the one for your region
#US Home Region 1
# 'iomhost' : ['odaws01-usw2.oda.sas.com','odaws02-usw2.oda.sas.com','odaws03-usw2.oda.sas.com','odaws04-usw2.oda.sas.com'],
#US Home Region 2
#'iomhost' : ['odaws01-usw2-2.oda.sas.com','odaws02-usw2-2.oda.sas.com'],
#European Home Region 1
#'iomhost' : ['odaws01-euw1.oda.sas.com','odaws02-euw1.oda.sas.com'],
#Asia Pacific Home Region 1
#'iomhost' : ['odaws01-apse1.oda.sas.com','odaws02-apse1.oda.sas.com'],
#Asia Pacific Home Region 2
#'iomhost' : ['odaws01-apse1-2.oda.sas.com','odaws02-apse1-2.oda.sas.com'],
'iomport' : 8591,
'authkey' : 'oda',
'encoding' : 'utf-8'
}
```
- Create an `authinfo` file, which you will be able to write your ODA credentials into.
Generally, your `authinfo` file will look something like:
```
oda user {your username} password {your password}
```
```
oda user {your username} password {your password}
```
- Request that you download the [SAS ODA encryption jars](https://support.sas.com/downloads/package.htm?pid=2494) into the `SASPy` package's `java/iomclient/` folder.

More information about ODA configuration can be found in the [ODA section of `SASPy` configuration documentation](https://sassoftware.github.io/saspy/configuration.html#iom).