SAS in Quarto

[loganjohnson0]

This is an alternative to #462 .

Discussion

With this example structure, I think the ability to run SAS in Quarto documents is the most feasible. However, there are some things to think about.

Details

Specifically, you'll notice that all of the sas code blocks are now replaced with r. Now, sasquatch::sas_run_string() is used, and the SAS code is inside the string. Using sasquatch::sas_run_string(capture = "listing"), only the final output is kept; otherwise, a "log" tab panel also appears. This "log" tab may be useful for diagnosing errors, of which I noticed some syntax errors in this specific document. By actually having this SAS code now run and evaluated, these errors can be caught and corrected, so users know the code actually runs.

Other changes include the SAS outputs being saved as a .rds object. This way, the SAS code isn't being evaluated with each new render, and only R is used to load the html widgets/the .rds objects. Then, if specific changes to the SAS code are needed, one only needs to turn the yaml header option eval: to true. The actual SAS code has been placed in a text, txt block. All of these ideas came from discussions with the author of sasquatch in this thread.

Drawbacks to this Approach

1. sasquatch isn't added to the repository, so to get the SAS code to run, setup of sasquatch at a local level is required. This may be somewhat challenging/annoying to get everyone set up. I have a PR in sasquatch to propose some better documentation for getting it all set up. I've also made a PR to improve the downloading experience. Really, once one has it all configured, it is very easy to use.
   • It just needs to be noted that sasquatch and any related dependencies cannot be added, otherwise they will fail to run and render.
2. The results of running each sas code block with sasquatch::sas_run_string() have to be saved as separate .rds objects. In documents that are long with many sas examples, this may become cumbersome. I haven't figured out a good naming scheme, and if one adds an example to the beginning of a document, that would alter the numbering scheme. There may be programmatic ways to edit the names, but I haven't figured that out.

Advantages to this Approach

1. Screenshots do not have to be embedded into the documents manually anymore as everything is run and updated in the document itself. Huge plus!
   • Many images in the images/ folder can likely be removed as documents are updated. On the flip side, many more .rds objects will be added. In this specific SAS/rounding.qmd file, there are now 4 .rds objects when there were 0 screenshots before this change.
2. Better-looking code and outputs of SAS. Specifically, background text with the txt SAS code and the actual SAS outputs.
3. Being able to run the code to evaluate any errors. Now, errors can be avoided, and any updates to the code will be captured in the .rds objects. No more "I updated the code in the qmd file, but did I make a new screenshot and update it?".
4. Overall, I think this is a more positive user experience for people making the examples in SAS. And I think the documents will be much better too for readers.

Other Changes

• I had to update reticulate to 1.41.0, because that version introduced a specific function that sasquatch uses.

Things I didn't Change

• No changes related to installing sasquatch were pushed to the repository. This is because the dependencies of sasquatch don't seem to play nicely with the CI systems. And specific sasquatch configuration settings are likely to be specific to every contributor of this repository. Therefore, each time someone wants to update and run these SAS code chunks, they will have to launch sasquatch locally, connect to their local SAS session, and then evaluate the SAS Quarto code chunks. As long as new and updated documents follow the types of yaml and code chunk options I've defined, it should be as simple as turning the document yaml eval parameter to true and rendering the document locally and only pushing changes to that document.

Things to Get Feedback On

• Is making a folder inside the SAS/ folder called rds a good approach? Then, inside that folder, one would make an additional folder that is the same as the document name they are editing. That way, any SAS .rds objects they create can be organized. This is similar to the images/ folder, but it is just placed within the SAS/ folder.
• Is this approach feasible? Do those who contribute to the SAS documentation find this approach appealing?
• What sort of documentation or help guide would be useful?

This got long, but I think this is really a good first step towards having SAS running in Quarto documents.

[loganjohnson0]

I really think this is the better option of the two. Again, it takes some setting up, but it really isn't too bad. I think the documents look nicer when they are rendered as well. @statasaurus if you and the leadership team wouldn't mind looking at this and discussing at the next meeting, that would be great. No rush for this really. I have enjoyed working on this.