Table of Content

Intro

This page is the official/public wiki of Varhandle R package repository. In order to have control over this project and also protect my personal ideas, I develop the package in a private fork of this repository and update this public repo accordingly. This repository only contains the working non-beta branch of the code including nightly builds in case of minor changes due to malfunction or possible bug.

The best place to follow the package is here and the best place to get the package is from CRAN. But the package is also available in the following repositories:

Packaging status

About this package

This package is a collection of functions with the goal to help R users work with variables easier safer and faster. All functions that are present in this package are written due to the needs my colleagues and/or I felt while coding in R and working on their projects, or they are some of my best practices that I wanted others to use in a systematic form.

List of functions in this package (Alphabetical order)

Detail of each function can be found in the package's official documentation

Release notes of the package can be found in the following link: https://codeberg.org/mehrad/varhandle/src/branch/master/NEWS.md

Installation

At every moment there can be at least one and at most two versions available. One version is the one that is in CRAN repository and the other one is the nightly-builds. The CRAN is always available and nightly-builds are only generated in case of an update that can not wait until the next CRAN publication date (You can not update your package very frequently due to CRAN regulations and the reviewers are sometimes cranky about some minor NOTEs during the package build).

Installation from CRAN

Simply go to your R environment and run the code below:

install.packages("varhandle")

Installation of the nightly-builds

First you should get the package file (.tar.gz) from this repository by navigating to the address below: https://codeberg.org/mehrad/varhandle/releases

Then there are two simple ways, either you prefer to install the package in the R environment:

install.packages(path_to_file, repos = NULL, type="source")

or you prefer to install it just through your terminal without entering R environment (just replace the_package_file.tar.gz with the file you downloaded):

R CMD INSTALL the_package_file.tar.gz

Reporting issues/errors/mistakes

Please report the issues you encounter in the issues section of this repository. But before posting, please check if the issue is not already among the open issues.

For reporting an issue, please make sure to provide the following, and if you cannot, please briefly mention why:

  1. R session info as I proposed here: https://stackoverflow.com/a/37992312/1613005
  2. Operating system
  3. Function name
  4. An example to demonstrate the issue
  5. What you expect to happen
  6. What actually happens

If you have any idea on how the issue should be solved, please mention it.

Contribution

Any sort of contribution is highly welcome and it can be done in one of the following ways:

  1. By suggesting feature and reporting errors through the ticketing system of this repository (You will be named in the changelog and a record of your suggestion/bug report will obviously remain on this repository).

If you are choosing to go with this approach, please provide enough examples and explanation so that I can either replicate the issue if it is a bug or understand the importance of your suggestion. You can do this by writing text, recording Gifs, recording a video, make a small presentation, basically any form of communication that you would feel comfortable with.

  1. By forking/cloning this repo, make your desire changes and send me a "merge request" so that I merge that feature in the package if it fits CRAN standards and my package's internal standards which are described below. In this case your name and your contribution type will be mentioned in the package.
git clone https://gitlab.com/mehrad/varhandle.git
  1. By forking/cloning this repo (as explained above) and improve the text, examples and etc. (Detail info can be found blow in the corresponding section).

Internal Standards of this package

  1. The functions should be user friendly, meaning they should generate proper error, messages or plots
  2. User should have maximum control over the output
  3. Minimum usage of external packages (Base package and thin package are totally fine). For packages like stats and ggplot2 there should be a good reasoning why we need that since user should not be forced to install third-party package for utilizing this package.
  4. Code should be clear, meaning it should be properly commented and have proper (self explanatory) variable names should be used.
  5. The git commits' messages are better to follow simple instructions discussed in the following post to maintain git flow clarity: https://github.com/erlang/otp/wiki/Writing-good-commit-messages

Build package from source

This repo comes with a good makefile. This is there for you to use, and to study. Use it to your advantage while you are working on this project. To learn how to use the makefile, simply go to the project folder and do:

make help

When you change the code and made sure it works try building it normally without CRAN standards to see if there are anything that R has problem with:

make all

Then when there was no ERRORS, WARNINGS, or NOTES, then try the following to make sure it is up to CRAN standards as well:

make all-cran