Site icon R-bloggers

Making of elliplot package

tomizono

[This article was first published on ЯтомизоnoR » R, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

The elliplot package is my first package for R.  So I want to write down details of making that, both for myself and for people following.

original source

The ellipseplot sources before packaging is available at the following svn host.

package source

The elliplot package source is available at the following svn host.

making

1. source the original ellipseplot and midpoints.

Because the package.skeleton() function generates help files for specified objects, I sourced the scripts first.

source('/source/location/midpoints.R')
source('/source/location/ellipseplot.R')

2. make a skeleton of elliplot.

The package.skeleton() function does everything.  Of course, I checked the name "elliplot" was not used by existing packages and the function names did not override base R functions.

package.skeleton(name='elliplot',
                 list=c('ellipseplot', 'midpoint', 'midpoints', 
                        'ninenum', 'seventeennum')

Give the function names to have public scopes.  Actually I did not list all of public names.  The ellipseplot() is an S3 method and there are ellipseplot.* functions, such as ellipseplot.default, that I want to make public.  Because I planned to make a single help document for these S3 methods, I simply specify only one "ellipseplot" here.  The package.skeleton() function generates help documents in man folder for each names specified at list parameter.

3. edit elliplot files.

3-1. sources in R folder

The package.skeleton() function generates source files in R folder.  But I removed them, and then replaced with the existing original sources of ellipseplot and midpoints.  That is because I didn’t specify all names required, and because I chose using same sources with the originals to make things easy.

3-2. NAMESPACE

The file NAMESPACE controls the scope.  The default one uses a regular expression on exportPattern to put all available names into public scopes.

exportPattern("^[[:alpha:]]+")

I replaced this with the next one.

export('midpoint','midpoints','ninenum','seventeennum')
exportPattern('^ellipseplot[.a-z]*')

The 1st line contains each names of public functions.  The 2nd line is for all names beginning with ellipseplot.   This puts all functions for the S3 method ellipseplot into public scopes.

3-3. DESCRIPTION

The file DESCRIPTION has properties for management of the package, including name and email of the package maintainer.  I didn’t chose major licenses such as GNU, so I had to write the followings.

License: file LICENSE
License_is_FOSS: yes
License_restricts_use: no

The keyword "file LICENSE" means that I put a file "LICENSE" in a root folder of the package to specify the detail of the license applied on this package.  The license is Free Open Source and does not restrict the use.

3-4 LICENSE

I added a file LICENSE in the root of the package.  This file has the following text.

paid4e - co-wares license - Fortitudinous, Free, Fair

1. NO WARRANTY (be Fortitudinous)

Everything is published ‘as-is’ with all faults known and
unknown.  You are responsible to judge the quality and the
accuracy by yourself.  You are responsible to all losses
caused by use.

2. FREE

Free to everyone.  No charges.  No limits.  For every purpose.
No registrations.  No approvals.  Free to commercial use.
Free to redistribute.  You can mix it with your own works.

3. PLAY FAIR

Write clearly the original is available freely and is
independent from your works.  Make an honest distinction
between the original work and your works.  Respect the
original copyright and license.

See http://paidforeveryone.wordpress.com/ or

http://cowares.nobody.jp/

for detail of the license.

Because this license is not famous, I put this file instead of specifying just the name of it.

3-5. help files

Help files are placed in a man folder.  As a default, Rd files for each of the specified list parameter in the package.skeleton() function are generated.   Additionally, an Rd file for the package itself, namely elliplot-package.Rd, is found.

Editing these manual files will be the heaviest and the most important task on making packages.  Writing good examples can help both of users and developers.

I added many aliases to ellipseplot.Rd, because it should have every function name called by the S3 method.

¥alias{ellipseplot}
¥alias{ellipseplot.default}
¥alias{ellipseplot.data.frame}
¥alias{ellipseplot.numeric}
¥alias{ellipseplot.matrix}
¥alias{ellipseplot.list}

I also added another alias to ninenum.Rd.  This was because it should be shown by a common name in the Statistics.

¥alias{ninenum}
¥alias{octile}

3-6. done.

Files created by the package.skeleton() function are committed to my svn at revision 953.

Files on the release of elliplot package 1.1.0 are commited upto revision 973.

Because the later only have a file changed at revision 973, you may want to check all revisions between 953 and 973, or dig by file tree at the current revision.

Here is a complete list of files.  The first letter indicates the status of each file.

Fig. 1. File tree in package source

D indicate deleteted files generated by the package.skeleton() function.
A indicates a file I created.
M and MM indicate files modified from the skeleton.  The two MM files are actually replaced rather than editing by hands.

Everyone can see the changes of each file on the project svn page. So, for the manual file for ellipseplot, namely ellipseplot.Rd, changes between the revision 953 (the skeleton) and the revision 971 (the latest at 1.1 release) are shown at the following.

Of course, you can get the entire sources into your local svn repository by svn checkout, and then use svn diff to see arbitrary changes.

4. build

Build and check are performed outside the R console, using R CMD in the OS terminal.

R CMD build /path/to/skeleton/elliplot

The elliplot_1.1.0.tar.gz file is created in current folder.  The version number 1.1.0 comes from the Version written in the DESCRIPTION file.  If an error is shown, you must follow the message to fix the mistake, and then try the build again.

5. check

R CMD check ./elliplot_1.1.0.tar.gz

The elliplot.Rcheck folder is created in current folder by R CMD to check the package. Many useful files are found in this folder. Logs, output of example codes, pdf manual file, and installed package folder. The last one has a name "elliplot" in this case, and this can be used to load the package by library() function.

This check may show some warnings and some notes. Follow the message to fix them.

6. check the help pdf

The generated manual pdf file, elliplot-manual.pdf, is useful to check the Rd files in the man folder.  Unless you are the specialist of Rd format, you may want to fix many unexpected visuals.  Mathematical formulae written with TeX notations will be beautifully shown.

7. test the package using library() function

After the check is done, the new package can be loaded from the check folder without installation.

library(elliplot, lib.loc='/path/to/checked/elliplot.Rcheck')

8. test the package using install.package() function

Before the release, we want to install the package to perform the final check.

install.packages('/path/to/checked/elliplot_1.1.0.tar.gz', 
                 repos=NULL, type='source')
library(elliplot)

Do same things to install a downloaded package file directly.  Because the CRAN do not favor too frequent updates, the way to get a package of development version directly without using CRAN and to install it is still important.

9. check as cran

/my/R-devel/R.framework/Resources/R CMD check --as-cran 
                                  ./elliplot_1.1.0.tar.gz

This procedure connects to CRAN to perform additional checks. I also used the latest R-devel. Because I am a new comer to CRAN submission, a note is displayed to tell that my name is a new maintainer.

10. submit to CRAN

The following is the submission form to CRAN.

11. confirm email

Because this was my first submission to CRAN, my email address was confirmed during the submission.  Including this confirmation, the entire submission process is easy and quick.

According CRAN policy, 1-2 months are expected until the completion after submission.

Related articles

  1. elliplot 1.1.0 package released
  2. Building R-devel on Mac OS X (mountain lion)
  3. Control the Function Scope by the R Package Namescope
  4. Where to begin MacTeX
  5. Make an R package – Hello, world
  6. Draw an Ellipse Summary Plot in R
  7. Quantiles: median, quartiles, octiles, hexadeciles, …

To leave a comment for the author, please follow the link and comment on their blog: ЯтомизоnoR » R.
R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.