Merge branch 'release-0.1.0'

DESCRIPTION

@@ -1,10 +1,11 @@
 Package: philsfmisc
 Type: Package
-Title: philsf's misc functions
+Title: philsf's miscellaneous R functions
 Version: 0.1.0
-Author: Felipe Figueiredo
-Maintainer: Felipe Figueiredo <[email protected]>
-Description: philsf miscellaneous R functions
+Authors@R: person("Felipe", "Figueiredo", email = "[email protected]", role = c("aut", "cre"))
+Description: Miscellaneous R functions for convenient data analyses.
 License: GPL2
 Encoding: UTF-8
 LazyData: true
+URL: https://github.com/philsf/philsfmisc
+Depends: R (>= 3.3.0)

R/format.float.R

@@ -0,0 +1,5 @@
+format.float <- function(value, digits = 2) {
+  value <- suppressWarnings(as.numeric(value))
+  value <- formatC(value, format = "f", digits = digits)
+  value
+}

R/format.interval.R

@@ -0,0 +1,16 @@
+format.interval <- function(interval, digits = 2) {
+  if (is.null(interval)) return(NULL) # if no argument passed, return
+  if (anyNA(interval)) return(NA) # return NA in case of incomplete interval
+  stopifnot(length(interval) == 2) # require an interval as argument
+  LL <- format.float(interval[1], digits = digits)
+  UL <- format.float(interval[2], digits = digits)
+  LL.closure <- "["
+  UL.closure <- "]"
+  if (LL == -Inf) LL.closure <- "("
+  if (UL == Inf) UL.closure <- ")"
+  paste0(LL.closure,
+         LL,
+         ", ",
+         UL,
+         UL.closure)
+}

R/is.within.R

@@ -0,0 +1,4 @@
+is.within <- function(value, interval, open.interval = FALSE) {
+  if (open.interval) return( value > interval[1] & value < interval[2] )
+  value >= interval[1] & value <= interval[2]
+}

README.md

@@ -1,2 +1,19 @@
 # philsfmisc - philsf miscellaneous R functions
 
+## Installation instructions
+
+To install this package, you need to have the `devtools` package installed.
+
+To install the stable version, provided in the `master` branch, use the following command:
+
+    install_github("philsf/philsfmisc")
+
+To install the *development* version, use the following command:
+
+    install_github("philsf/philsfmisc", ref = "develop")
+
+## Functions provided
+
+- `format.float`
+- `format.interval`
+- `is.within`

man/format.float.Rd

@@ -0,0 +1,71 @@
+\name{format.float}
+\alias{format.float}
+\alias{format.double}
+%- Also NEED an '\alias' for EACH other topic documented here.
+\title{
+Format numbers for printing
+}
+\description{
+Format numbers, given a `digits` argument as significant decimal places.
+
+{Numbers are always assumed to be \code{\link[base]{double}}.}
+}
+\usage{
+format.float(x)
+}
+%- maybe also 'usage' for other objects documented here.
+\arguments{
+  \item{value}{
+  Value to be formatted.
+  Input can be a numeric or character value.
+  }
+  \item{digits}{
+  Number of fixed digits, after decimal point (default = 2)
+  }
+}
+\details{
+%%  ~~ If necessary, more details than the description above ~~
+}
+\value{
+Returns a character value.
+%%  ~Describe the value returned
+%%  If it is a LIST, use
+%%  \item{comp1 }{Description of 'comp1'}
+%%  \item{comp2 }{Description of 'comp2'}
+%% ...
+}
+\references{
+%% ~put references to the literature/web site here ~
+}
+\author{
+Felipe Figueiredo
+}
+\note{
+%%  ~~further notes~~
+\code{format.float} does NOT work with \code{factor} values.
+}
+
+%% ~Make other sections like Warning with \section{Warning }{....} ~
+
+\seealso{
+\code{\link[base]{numeric}}
+%% ~~objects to See Also as \code{\link{help}}, ~~~
+}
+\examples{
+format.float(0.5)
+format.float(0.672, 4)
+format.float(1.4927, 1)
+format.float(c(1.756, 1.823))
+
+# Input is character
+format.float("1.12543")
+format.float(c("1.756", "1.823"))
+
+# Useful for data frames
+DF <- data.frame(num = c(1.756, 1.823), char = c("1.756", "1.823"), stringsAsFactors = F)
+transform(DF, num = format.float(num), char = format.float(char))
+}
+% Add one or more standard keywords, see file 'KEYWORDS' in the
+% R documentation directory.
+\keyword{ ~kwd1 }% use one of  RShowDoc("KEYWORDS")
+\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line

man/format.interval.Rd

@@ -0,0 +1,65 @@
+\name{format.interval}
+\alias{format.interval}
+%- Also NEED an '\alias' for EACH other topic documented here.
+\title{
+Format intervals for printing
+}
+\description{
+Format intervals, given a `digits` argument as significant decimal places.
+}
+\usage{
+format.interval(interval, digits = 2)
+}
+%- maybe also 'usage' for other objects documented here.
+\arguments{
+  \item{interval}{
+%%     ~~Describe \code{interval} here~~
+  Must be a vector of two values.
+
+  Values can be either numeric or character.
+}
+  \item{digits}{
+  Number of fixed digits, after decimal point. (default = 2)
+}
+}
+\details{
+%%  ~~ If necessary, more details than the description above ~~
+
+This uses \code{\link{format.float}} for formatting each of the limits of the interval.
+}
+\value{
+%%  ~Describe the value returned
+%%  If it is a LIST, use
+%%  \item{comp1 }{Description of 'comp1'}
+%%  \item{comp2 }{Description of 'comp2'}
+%% ...
+Returns a character value.
+}
+\references{
+%% ~put references to the literature/web site here ~
+}
+\author{
+Felipe Figueiredo
+}
+\note{
+%%  ~~further notes~~
+}
+
+%% ~Make other sections like Warning with \section{Warning }{....} ~
+
+\seealso{
+%% ~~objects to See Also as \code{\link{help}}, ~~~
+}
+\examples{
+format.interval(c(1.756, 1.823))
+
+format.interval(1.5, 1) # error: 1.5 is not an interval
+
+# Input is character
+format.interval(c("1.756", "1.823"))
+
+}
+% Add one or more standard keywords, see file 'KEYWORDS' in the
+% R documentation directory.
+\keyword{ ~kwd1 }% use one of  RShowDoc("KEYWORDS")
+\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line

man/is.within.Rd

@@ -0,0 +1,63 @@
+\name{is.within}
+\alias{is.within}
+%- Also NEED an '\alias' for EACH other topic documented here.
+\title{
+Check if number is within given interval
+}
+\description{
+%%  ~~ A concise (1-5 lines) description of what the function does. ~~
+}
+\usage{
+is.within(value, interval, open.interval = FALSE)
+}
+%- maybe also 'usage' for other objects documented here.
+\arguments{
+  \item{value}{
+A numeric value, vector or list.
+}
+  \item{interval}{
+%%     ~~Describe \code{interval} here~~
+The (numeric) interval within which \code{value} is being tested.
+}
+  \item{open.interval}{
+%%     ~~Describe \code{open.interval} here~~
+logical: should \code{interval} be regarded as an open interval?
+}
+}
+\details{
+%%  ~~ If necessary, more details than the description above ~~
+}
+\value{
+%%  ~Describe the value returned
+%%  If it is a LIST, use
+%%  \item{comp1 }{Description of 'comp1'}
+%%  \item{comp2 }{Description of 'comp2'}
+%% ...
+The default method for \code{is.within} applied to an atomic vector returns a logical vector of the same length as its argument x, containing TRUE for those elements contained within \code{interval}, and FALSE otherwise.
+}
+\references{
+%% ~put references to the literature/web site here ~
+}
+\author{
+Felipe Figueiredo
+}
+\note{
+%%  ~~further notes~~
+}
+
+%% ~Make other sections like Warning with \section{Warning }{....} ~
+
+\seealso{
+%% ~~objects to See Also as \code{\link{help}}, ~~~
+}
+\examples{
+is.within(1.5, c(0,5)) # TRUE
+is.within(6, c(0,5)) # FALSE
+
+is.within(c(1.5, 6), c(0,5)) # vector: TRUE, TRUE
+is.within(list(1.5, 6), c(0,5)) # list: TRUE, FALSE
+}
+% Add one or more standard keywords, see file 'KEYWORDS' in the
+% R documentation directory.
+\keyword{ ~kwd1 }% use one of  RShowDoc("KEYWORDS")
+\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line