Making of elliplot package
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.
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
- elliplot 1.1.0 package released
- Building R-devel on Mac OS X (mountain lion)
- Control the Function Scope by the R Package Namescope
- Where to begin MacTeX
- Make an R package – Hello, world
- Draw an Ellipse Summary Plot in R
- Quantiles: median, quartiles, octiles, hexadeciles, …
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.