The BasePlus package [ver. 0.993]

The BasePlus package [ver. 0.993]:

- New macro `%rainCloudPlot()` added to the package.
- Doc. updated.

README.md

@@ -144,7 +144,7 @@ SHA256 digest for macroArray: 849629D3AF3FE3AB45D86990E303F1D5E4D5F9F31C8ED6864C
 [Documentation for macroArray](https://github.com/yabwon/SAS_PACKAGES/blob/main/packages/macroarray.md "Documentation for macroArray")
 
 
-- **BasePlus**\[0.992\] adds a bunch of functionalities I am missing in BASE SAS, such as:
+- **BasePlus**\[0.993\] adds a bunch of functionalities I am missing in BASE SAS, such as:
 ```sas
 call arrMissToRight(myArray); 
 call arrFillMiss(17, myArray); 
@@ -158,7 +158,7 @@ format x bool.;
 
 %put %getVars(sashelp.class, pattern = ght$, sep = +, varRange = _numeric_);
 ```
-SHA256 digest for BasePlus: C9D26CAC2504634EF25F02B5BD04596B2F873E3C25E8CEDDD7F496A78B184E9F
+SHA256 digest for BasePlus: 5EAEF846754F19759C0492308478417C9667C9651F1EF14F70E4FF8AB4C857F6
 
 [Documentation for BasePlus](https://github.com/yabwon/SAS_PACKAGES/blob/main/packages/baseplus.md "Documentation for BasePlus")
 

packages/README.md

@@ -90,7 +90,7 @@ SHA256 digest for macroArray: 849629D3AF3FE3AB45D86990E303F1D5E4D5F9F31C8ED6864C
 
 ---
 
-- **BasePlus**\[0.992\] adds a bunch of functionalities I am missing in BASE SAS, such as: 
+- **BasePlus**\[0.993\] adds a bunch of functionalities I am missing in BASE SAS, such as: 
 ```sas
 call arrMissToRight(myArray); 
 call arrFillMiss(17, myArray); 
@@ -104,7 +104,7 @@ format x bool.;
 
 %put %getVars(sashelp.class, pattern = ght$, sep = +, varRange = _numeric_);
 ```
-SHA256 digest for BasePlus: C9D26CAC2504634EF25F02B5BD04596B2F873E3C25E8CEDDD7F496A78B184E9F
+SHA256 digest for BasePlus: 5EAEF846754F19759C0492308478417C9667C9651F1EF14F70E4FF8AB4C857F6
 
 [Documentation for BasePlus](https://github.com/yabwon/SAS_PACKAGES/blob/main/packages/baseplus.md "Documentation for BasePlus")
 

packages/SHA256_for_packages.txt

@@ -1,3 +1,6 @@
+/* 20211001 */
+BasePlus: 5EAEF846754F19759C0492308478417C9667C9651F1EF14F70E4FF8AB4C857F6
+
 /* 20210908 */
 GSM: 93D88D4465B68984E938212241DE55C7B12EBC20601538553AC9E1AC0628C006
 

packages/baseplus.md

@@ -42,12 +42,14 @@
   * [`%zipEvalf()` macro](#zipevalf-macro) 
   * [`%QzipEvalf()` macro](#qzipevalf-macro) 
   * [`%functionExists()` macro](#functionexists-macro)
+  * [`%RainCloudPlot()` macro](#raincloudplot-macro)
+
 
   * [License](#license)
   
 ---
 
-# The BasePlus package [ver. 0.992] <a name="baseplus-package"></a> ###############################################
+# The BasePlus package [ver. 0.993] <a name="baseplus-package"></a> ###############################################
 
 The **BasePlus** package implements useful
 functions and functionalities I miss in the BASE SAS.
@@ -178,6 +180,14 @@ Kudos to all who inspired me to generate this package:
 %put &=x;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**Example 9**: Simple Rain Cloud plot.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%rainCloudPlot(sashelp.cars,DriveTrain,Invoice)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+![Rain Cloud Plot](./baseplus_RainCloudPlot_Ex0_9.png)
+
+
 ---
 
 Package contains: 
@@ -190,45 +200,46 @@ Package contains:
 7.  macro     qdeduplistx
 8.  macro     qgetvars
 9.  macro     qzipevalf
-10. macro     symdelglobal
+10. macro     raincloudplot
-11. macro     zipevalf
+11. macro     symdelglobal
-12. format    bool
+12. macro     zipevalf
-13. format    boolz
+13. format    bool
-14. format    ceil
+14. format    boolz
-15. format    floor
+15. format    ceil
-16. format    int
+16. format    floor
-17. functions arrfill
+17. format    int
-18. functions arrfillc
+18. functions arrfill
-19. functions arrmissfill
+19. functions arrfillc
-20. functions arrmissfillc
+20. functions arrmissfill
-21. functions arrmisstoleft
+21. functions arrmissfillc
-22. functions arrmisstoleftc
+22. functions arrmisstoleft
-23. functions arrmisstoright
+23. functions arrmisstoleftc
-24. functions arrmisstorightc
+24. functions arrmisstoright
-25. functions bracketsc
+25. functions arrmisstorightc
-26. functions bracketsn
+26. functions bracketsc
-27. functions catxfc
+27. functions bracketsn
-28. functions catxfi
+28. functions catxfc
-29. functions catxfj
+29. functions catxfi
-30. functions catxfn
+30. functions catxfj
-31. functions deldataset
+31. functions catxfn
-32. functions semicolonc
+32. functions deldataset
-33. functions semicolonn
+33. functions semicolonc
-34. format    brackets
+34. functions semicolonn
-35. format    semicolon
+35. format    brackets
-36. proto     qsortincbyprocproto
+36. format    semicolon
-37. functions frommissingtonumberbs
+37. proto     qsortincbyprocproto
-38. functions fromnumbertomissing
+38. functions frommissingtonumberbs
-39. functions quicksort4notmiss
+39. functions fromnumbertomissing
-40. functions quicksorthash
+40. functions quicksort4notmiss
-41. functions quicksorthashsddv
+41. functions quicksorthash
-42. functions quicksortlight
+42. functions quicksorthashsddv
+43. functions quicksortlight
 
 
-*SAS package generated by generatePackage, version 20210109*
+*SAS package generated by generatePackage, version 20210528*
 
 The SHA256 hash digest for package BasePlus: 
-`C9D26CAC2504634EF25F02B5BD04596B2F873E3C25E8CEDDD7F496A78B184E9F` 
+`5EAEF846754F19759C0492308478417C9667C9651F1EF14F70E4FF8AB4C857F6` 
 
 ---
 # Content description ############################################################################################
@@ -2970,6 +2981,255 @@ The basic syntax is the following, the `<...>` means optional parameters:
 
 ---
 
+## >>> `%RainCloudPlot()` macro: <<< <a name="raincloudplot-macro"></a> #######################  
+
+The RainCloudPlot() macro allow to plot Rain Cloud plots, i.e. pots of 
+kernel density estimates, jitter data values, and box-and-whiskers plot.
+
+See examples below for the details.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%RainCloudPlot(
+   DS
+  ,gr
+  ,vars
+
+ <,WidthPX=>
+ <,HeightPX=>
+ <,boxPlot=>
+ <,roundFactor=>
+ <,rainDropSize=>
+ <,boxPlotSymbolSize=>
+ <,colorsList=>
+ <,monochrome=>
+ <,antialiasMax=>
+ <,title=>
+ <,footnote=>
+ <,catLabels=>
+ <,xLabels=>
+ <,catLabelPos=> 
+ <,xLabelPos=>
+ <,formated=>
+ <,y2axis=>
+ <,y2axisLevels=>
+ 
+ <,VSCALE=>
+ <,KERNEL_K=>
+ <,KERNEL_C=>
+
+ <,cleanTempData=> 
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `DS`                - *Required*, name of the dataset from 
+                         which variables are to be taken.
+
+2. `gr`                - *Required*, name of the grouping variable. 
+                         When more than one variable is specified 
+                         separate plots are rendered.
+                         Can be numeric or character.
+
+3. `vars`              - *Required*, name of the aggregated numeric variable.
+                         When more than one variable is specified 
+                         separate plots are rendered.
+
+***Plot related options***:
+
+* `WidthPX`            - *Optional*, default value `1200`. 
+                         Total width of the plot in pixels. 
+
+* `HeightPX`           - *Optional*, default value `220`. 
+                         Partial height of the plot in pixels.
+                         Total height is calculated as `#GROUPS x HeightPX`.
+
+* `boxPlot`            - *Optional*, default value `1`.
+                         Indicates if the Box Plot should be added. 
+                          
+* `roundFactor`        - *Optional*, default value `0.000001`.
+                         Rounding level when calculating maximum value 
+                         of the cloud chart. Should be adjusted to data
+                         granularity level, e.g. for data with value 
+                         around `1e-8` should be decreased. 
+
+* `rainDropSiz`        - *Optional*, default value `5px`.
+                         Size of data points in the "rain" plot.
+
+* `boxPlotSymbolSize`  - *Optional*, default value `8px`.
+                         Size of symbols on the box plot.
+
+* `colorsList`         - *Optional*, default value is empty.
+                         List of colours for plotting.
+                         Empty indicates that the default list will be used.
+
+* `monochrome`         - *Optional*, default value `0`.
+                         Indicates if the default list of colours should be gray-scale.
+
+* `antialiasMax`       - *Optional*, default value is empty.
+                         Sets a value to the ODS graphics `ANTIALIASMAX` option.
+                         When empty the value is calculated from data.
+
+* `title`              - *Optional*, default value - see notes below.
+                         Provides a list of titles printed on the plot.
+                         For details see notes below.
+
+* `footnote`           - *Optional*, default value - see notes below.
+                         Provides a list of titles printed on the plot.
+                         For details see notes below.
+
+* `catLabels`          - *Optional*, default value is empty. 
+                         List of values for group axix labels (vertical).
+                         When empty a grouping variable name is used.
+                         For details see notes below.
+
+* `xLabels`            - *Optional*, default value is empty. 
+                         List of values for data variable axix labels (horizontal).
+                         When empty a data variable name is used.
+                         For details see notes below.
+
+* `catLabelPos`        - *Optional*, default value `DATACENTER`.
+                         Indicates position of the label on group axix (vertical).
+                         Allowed values are `BOTTOM`, `CENTER`, `DATACENTER`, and `TOP`.
+
+* `xLabelPos`          - *Optional*, default value `DATACENTER`.
+                         Indicates position of the label on data axix (horizontal).
+                         Allowed values are `LEFT`, `CENTER`, `DATACENTER`, and `RIGHT`.
+
+* `formated`           - *Optional*, default value `0`.
+                         Indicates if values of the grouping variable should be formated.
+
+* `y2axis`             - *Optional*, default value `1`.
+                         Indicates if the righ vertical axix should be displayed.
+
+* `y2axisLevels`       - *Optional*, default value `4`.
+                         Indicates if the number of expected levels of values printed 
+                         on the right vertical axix.
+
+***Stat related options***:
+
+* `VSCALE`             - *Optional*, default value `Proportion`.
+                         Specifies the scale of the vertical axis.
+                         Allowed values are `PROPORTION`, `PERCENT`, and `COUNT`.
+                         `PROPORTION` scales the data in units of proportion of observations per data unit. 
+                         `PERCENT` scales the data in units of percent of observations per data unit. 
+                         `COUNT` scales the data in units of the number of observations per data unit.
+
+* `KERNEL_K`           - *Optional*, default value `NORMAL`. 
+                         Specifies type of kernel function to compute kernel density estimates.
+                         Allowed values are `NORMAL`, `QUADRATIC`, and `TRIANGULAR`. 
+
+
+* `KERNEL_C`           - *Optional*, default value `1`.
+                         Specifies standardized bandwidth parameter *C* to compute kernel density estimates.
+                         Allowed values are between `0` and `1`,
+
+***Other options***:
+
+* `cleanTempData`      - *Optional*, default value `1`.
+                         Indicates if temporary data sets should be deleted.
+
+**NOTES:**
+
+* Default value of the `title` option is:
+  `%nrstr(title1 JUSTIFY=C "Rain Cloud plot for &list_g. by "  %unquote(&xLabel.);)`
+  Use the `%str()` or `%nrstr()` macro-function to handle special characters.
+  The `%unquote()` is used when resolving the parameter.
+
+* Default value of the `footnote` option is:
+  `%nrstr(footnote1 JUSTIFY=L COLOR=lightGray HEIGHT=1 "by RainCloudPlot macro from the BasePlus package";)`
+  Use the `%str()` or `%nrstr()` macro-function to handle special characters.
+  The `%unquote()` is used when resolving the parameter.
+
+* The `catLabels` and `xLabels` should be quoted comma separated lists enclosed with brackets, 
+  e.g. `catLabels=("Continent of Origin", "Car Type")`, see Example below.
+
+* Kernel density estimates and basic statistics are calculated with `PROC UNIVARIATE`.
+
+* Plot is generated by `PROC SGPLOT` with `BAND`, `SCATTE`, and `POLYGON` plots.
+
+* After execution the ODS graphics dimension parameters are set to `800px` by `600px`.
+
+* SAS notes (`NOTE:`) are disabled for the execution time.
+
+* List of predefined colours is: 
+  `BlueViolet`, `RoyalBlue`, `OliveDrab`, `Gold`, `HotPink`, `Crimson`,  
+  `MediumPurple`, `CornflowerBlue`, `YellowGreen`, `Goldenrod`, `Orchid`, `IndianRed`.
+
+* The box-plot has the following interpretation: 
+  - left vertical bar indicates the minimum,
+  - left whisker line starts at `max(Q1 - 1.5IQR, minimum)` and ends at lower quartile (Q1),
+  - diamond indicates mean,
+  - vertical bar inside of the box indicates median.
+  - right whisker line starts at upper quartile (Q3) and ends at `min(Q3 + 1.5IQR, maximum)`,
+  - right vertical bar indicates the maximum.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Simple Rain Cloud Plot for a `have` dataset:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+
+  data have;
+    g = "Aaa";
+    do _N_ = 1 to 50;
+      x = rannor(42);
+      output;
+    end;
+
+    g = "Bb";
+    do _N_ = 1 to 120;
+      select (mod(_N_,9)); 
+        when(1,2,3,4,5) x = 0.5*rannor(42)+1;
+        when(6,7,8)   x = 0.5*rannor(42)+3;
+        otherwise   x = 0.5*rannor(42)+5;
+      end; 
+      output;
+    end;
+
+    g = "C";
+    do _N_ = 1 to 60;
+      x = 3*rannor(42)+7;
+      output;
+    end;
+  run;
+
+  %RainCloudPlot(have, g, x)
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The output:
+![Example 1](./baseplus_RainCloudPlot_Ex1.png)
+
+
+
+**EXAMPLE 2.** Rain Cloud plot for `sashelp.cars` dataset
+               with groups by Origin or Type 
+               for Invoice variables:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+
+  %RainCloudPlot(
+    sashelp.cars(where=(Type ne "Hybrid"))
+  , Origin Type
+  , Invoice 
+  , HeightPX=300 
+  , y2axisLevels=3
+  , catLabels=("Continent of Origin", "Car Type")
+  , xLabels="Invoice, [$]"
+  )
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The output:
+![Example 2a](./baseplus_RainCloudPlot_Ex2a.png)
+![Example 2b](./baseplus_RainCloudPlot_Ex2b.png)
+
+
+---
 
 ## License ####################################################################