R devel - Nov 2010 - R package BibTex entries: looking for a more general solution

== Summary =* Problem: BibTeX entries extracted from R packages via citation() 
require too much manual editing to be
of general use.
* Proposal: Date: fields should be made mandatory in package DESCRIPTION 
files, perhaps
beginning with warnings from R CMD check
* Proposal: Package authors should be encouraged to use a (new) 
Contributors: field in the DESCRIPTION file
rather than packing all information into the Author: field, which at 
present cannot often be parsed by BibTeX.
* Files: All test files referred to here can be found at

http://euclid.psych.yorku.ca/SCS/Private/Rbibs/

== Details =Around 16 Dec. 2009, I queried R-help about automating the
extraction of
citation()s from R packages. The stimulus
was that some journals, notably JSS, now require a reference and 
citation of every R package mentioned,
and it is a pain to create these manually, no less maintain them for 
current versions.

The result of that query was a function, Rpackage.bibs() by Achim 
Zeileis that I have been using ever since.
Code in: http://euclid.psych.yorku.ca/SCS/Private/Rbibs/Rpackages.bib.R
On one current system I get the following:

 > Rpackage.bibs(file="Rpackages-R.2.11.1.bib")
Converted 230 of 230 package citations to BibTex
Results written to file Rpackages-R.2.11.1.bib
Warning messages:
1: In citation(x) :
no date field in DESCRIPTION file of package 'codetools'
2: In citation(x) :
no date field in DESCRIPTION file of package 'gridBase'
3: In citation(x) : no date field in DESCRIPTION file of package
'iplots'
 >
See:
http://euclid.psych.yorku.ca/SCS/Private/Rbibs/Rpkg-test.pdf
for the result of processing this .bib file with latex/bibtex using the 
jss.bst bibliography style

I'm writing to R-Devel because the DESCRIPTION and inst/CITATION files 
in R packages provide the
basic data used in citation() and any methods based on this, and yet the 
information in these files is
often insufficient to generate well-formed BibTeX entries for use in 
vignettes and publications.

One easy case is illustrated above, where 3 packages have no Date: field 
so the BibTeX gets no
year = {},
and references get printed as Murrell, P (????) for gridBase. (In my 
original test under R 2.9.1, there where
~ 20 such warnings.) Thus, I propose that Date: be a required field in 
DESCRIPTION files, and
R CMD check complain if this is not found.

The more difficult case has to do with the Author: field in the 
DESCRIPTION file (when no CITATION file is present)
People can write whatever they want here, and the result looks sort of 
OK when printed by citation(), but confuses
BibTeX mightly. One example:

 > citation("akima")
To cite package ?akima? in publications use:

Fortran code by H. Akima R port by Albrecht Gebhardt aspline function
by Thomas Petzoldt <petzoldt at rcs.urz.tu-dresden.de> enhancements and
corrections by Martin Maechler (2009). akima: Interpolation of
irregularly spaced data. R package version 0.5-4.
http://CRAN.R-project.org/package=akima

A BibTeX entry for LaTeX users is

@Manual{,
title = {akima: Interpolation of irregularly spaced data},
author = {Fortran code by H. Akima R port by Albrecht Gebhardt aspline 
function by Thomas Petzoldt <petzoldt at rcs.urz.tu-dresden.de> 
enhancements and corrections by Martin Maechler},
year = {2009},
note = {R package version 0.5-4},
url = {http://CRAN.R-project.org/package=akima},
}

ATTENTION: This citation information has been auto-generated from the
package DESCRIPTION file and may need manual editing, see
?help("citation")? .
 >

Yes, the ATTENTION note does say that manual editing may be necessary, 
but I think a worthy goal would be
to try to reduce the need for this.

One simple way to do that would be to support an extra Contributions: 
field in the DESCRIPTION file,
so that Authors: can be more cleanly separated for the purpose of 
creating well-structured BibTeX.
Perhaps others have better ideas.

-Michael

-- 
Michael Friendly     Email: friendly AT yorku DOT ca
Professor, Psychology Dept.
York University      Voice: 416 736-5115 x66249 Fax: 416 736-5814
4700 Keele Street    Web:http://www.datavis.ca
Toronto, ONT  M3J 1P3 CANADA

I strongly support this proposal! I also find it inconvenient to cite
some R packages and really do not like edit the BibTeX entries
manually.

Regards,
Yihui
--
Yihui Xie <xieyihui at gmail.com>
Phone: 515-294-2465 Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA



On Wed, Nov 3, 2010 at 8:44 AM, Michael Friendly <friendly at yorku.ca>
wrote:
> == Summary => * Problem: BibTeX entries extracted from R packages via
citation() require
> too much manual editing to be
> of general use.
> * Proposal: Date: fields should be made mandatory in package DESCRIPTION
> files, perhaps
> beginning with warnings from R CMD check
> * Proposal: Package authors should be encouraged to use a (new)
> Contributors: field in the DESCRIPTION file
> rather than packing all information into the Author: field, which at
present
> cannot often be parsed by BibTeX.
> * Files: All test files referred to here can be found at
>
> http://euclid.psych.yorku.ca/SCS/Private/Rbibs/
>
> == Details => Around 16 Dec. 2009, I queried R-help about automating the
extraction of
> citation()s from R packages. The stimulus
> was that some journals, notably JSS, now require a reference and citation
of
> every R package mentioned,
> and it is a pain to create these manually, no less maintain them for
current
> versions.
>
> The result of that query was a function, Rpackage.bibs() by Achim Zeileis
> that I have been using ever since.
> Code in: http://euclid.psych.yorku.ca/SCS/Private/Rbibs/Rpackages.bib.R
> On one current system I get the following:
>
>> Rpackage.bibs(file="Rpackages-R.2.11.1.bib")
> Converted 230 of 230 package citations to BibTex
> Results written to file Rpackages-R.2.11.1.bib
> Warning messages:
> 1: In citation(x) :
> no date field in DESCRIPTION file of package 'codetools'
> 2: In citation(x) :
> no date field in DESCRIPTION file of package 'gridBase'
> 3: In citation(x) : no date field in DESCRIPTION file of package
'iplots'
>>
> See:
> http://euclid.psych.yorku.ca/SCS/Private/Rbibs/Rpkg-test.pdf
> for the result of processing this .bib file with latex/bibtex using the
> jss.bst bibliography style
>
> I'm writing to R-Devel because the DESCRIPTION and inst/CITATION files
in R
> packages provide the
> basic data used in citation() and any methods based on this, and yet the
> information in these files is
> often insufficient to generate well-formed BibTeX entries for use in
> vignettes and publications.
>
> One easy case is illustrated above, where 3 packages have no Date: field so
> the BibTeX gets no
> year = {},
> and references get printed as Murrell, P (????) for gridBase. (In my
> original test under R 2.9.1, there where
> ~ 20 such warnings.) Thus, I propose that Date: be a required field in
> DESCRIPTION files, and
> R CMD check complain if this is not found.
>
> The more difficult case has to do with the Author: field in the DESCRIPTION
> file (when no CITATION file is present)
> People can write whatever they want here, and the result looks sort of OK
> when printed by citation(), but confuses
> BibTeX mightly. One example:
>
>> citation("akima")
> To cite package ?akima? in publications use:
>
> Fortran code by H. Akima R port by Albrecht Gebhardt aspline function
> by Thomas Petzoldt <petzoldt at rcs.urz.tu-dresden.de> enhancements
and
> corrections by Martin Maechler (2009). akima: Interpolation of
> irregularly spaced data. R package version 0.5-4.
> http://CRAN.R-project.org/package=akima
>
> A BibTeX entry for LaTeX users is
>
> @Manual{,
> title = {akima: Interpolation of irregularly spaced data},
> author = {Fortran code by H. Akima R port by Albrecht Gebhardt aspline
> function by Thomas Petzoldt <petzoldt at rcs.urz.tu-dresden.de>
enhancements
> and corrections by Martin Maechler},
> year = {2009},
> note = {R package version 0.5-4},
> url = {http://CRAN.R-project.org/package=akima},
> }
>
> ATTENTION: This citation information has been auto-generated from the
> package DESCRIPTION file and may need manual editing, see
> ?help("citation")? .
>>
>
> Yes, the ATTENTION note does say that manual editing may be necessary, but
I
> think a worthy goal would be
> to try to reduce the need for this.
>
> One simple way to do that would be to support an extra Contributions: field
> in the DESCRIPTION file,
> so that Authors: can be more cleanly separated for the purpose of creating
> well-structured BibTeX.
> Perhaps others have better ideas.
>
> -Michael
>
> --
> Michael Friendly ? ? Email: friendly AT yorku DOT ca
> Professor, Psychology Dept.
> York University ? ? ?Voice: 416 736-5115 x66249 Fax: 416 736-5814
> 4700 Keele Street ? ?Web:http://www.datavis.ca
> Toronto, ONT ?M3J 1P3 CANADA
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

On 11/3/2010 10:42 AM, John Fox wrote:
> Hi Michael,
>
> FWIW, I've added a CITATION file to the car package on R-Forge.
>
When I composed a CITATION file for the heplots package, I had to root 
around in R/library to find something to
use as a template.  The main reason for doing this was to have 
citation("heplots") also provide a reference to
the theory paper on which this was based, and which should also be cited 
by users of the package.

  "Writing R Extensions", 1.10 gives a simple example of a CITATION 
file, but even this is somewhat daunting for a
package author, and thus is generally ignored.

This would all be easier, and could evolve over time if there was a 
function, e.g., prompt.citation(package)
in utils that would write a basic CITATION file from a package 
DESCRIPTION, that a package author could
easily edit and then include in the package.

I can imagine it working something like:

 > prompt.citation("fubar")
A CITATION file for the fubar package was automatically generated from 
the package DESCRIPTION
file.  Please edit this file and move it to the appropriate directory, 
inst/ in the package tree.
Warning: no Date: field provided in the package DESCRIPTION
Warning: Authors: field does not appear to be a list of names joined 
with 'and'

Providing something like this would obviate my suggestions to impose 
restrictions on DESCRIPTION
files, and seems more in line with the way R packages and documentation 
have developed.

-Michael



-- 
Michael Friendly     Email: friendly AT yorku DOT ca
Professor, Psychology Dept.
York University      Voice: 416 736-5115 x66249 Fax: 416 736-5814
4700 Keele Street    Web:   http://www.datavis.ca
Toronto, ONT  M3J 1P3 CANADA

>>>>> Michael Friendly writes:
Thanks for the suggestions. In fact, we are currently working on this
issue. A lot of improvements have already been done, see ?person and
?bibentry for R 2.12.0 or later, especially the details and examples
sections. Some more work still needs to be done, though. We will write a
primer that introduces the new features when all of them are available.

Best
-k
> == Summary => * Problem: BibTeX entries extracted from R packages via
citation()
> require too much manual editing to be
> of general use.
> * Proposal: Date: fields should be made mandatory in package DESCRIPTION 
> files, perhaps
> beginning with warnings from R CMD check
> * Proposal: Package authors should be encouraged to use a (new) 
> Contributors: field in the DESCRIPTION file
> rather than packing all information into the Author: field, which at 
> present cannot often be parsed by BibTeX.
> * Files: All test files referred to here can be found at
> http://euclid.psych.yorku.ca/SCS/Private/Rbibs/
> == Details => Around 16 Dec. 2009, I queried R-help about automating the
extraction of
> citation()s from R packages. The stimulus
> was that some journals, notably JSS, now require a reference and 
> citation of every R package mentioned,
> and it is a pain to create these manually, no less maintain them for 
> current versions.
> The result of that query was a function, Rpackage.bibs() by Achim 
> Zeileis that I have been using ever since.
> Code in: http://euclid.psych.yorku.ca/SCS/Private/Rbibs/Rpackages.bib.R
> On one current system I get the following:
>> Rpackage.bibs(file="Rpackages-R.2.11.1.bib")
> Converted 230 of 230 package citations to BibTex
> Results written to file Rpackages-R.2.11.1.bib
> Warning messages:
> 1: In citation(x) :
> no date field in DESCRIPTION file of package 'codetools'
> 2: In citation(x) :
> no date field in DESCRIPTION file of package 'gridBase'
> 3: In citation(x) : no date field in DESCRIPTION file of package
'iplots'
>> 
> See:
> http://euclid.psych.yorku.ca/SCS/Private/Rbibs/Rpkg-test.pdf
> for the result of processing this .bib file with latex/bibtex using the 
> jss.bst bibliography style
> I'm writing to R-Devel because the DESCRIPTION and inst/CITATION files 
> in R packages provide the
> basic data used in citation() and any methods based on this, and yet the 
> information in these files is
> often insufficient to generate well-formed BibTeX entries for use in 
> vignettes and publications.
> One easy case is illustrated above, where 3 packages have no Date: field 
> so the BibTeX gets no
> year = {},
> and references get printed as Murrell, P (????) for gridBase. (In my 
> original test under R 2.9.1, there where
> ~ 20 such warnings.) Thus, I propose that Date: be a required field in 
> DESCRIPTION files, and
> R CMD check complain if this is not found.
> The more difficult case has to do with the Author: field in the 
> DESCRIPTION file (when no CITATION file is present)
> People can write whatever they want here, and the result looks sort of 
> OK when printed by citation(), but confuses
> BibTeX mightly. One example:
>> citation("akima")
> To cite package ?akima? in publications use:
> Fortran code by H. Akima R port by Albrecht Gebhardt aspline function
> by Thomas Petzoldt <petzoldt at rcs.urz.tu-dresden.de> enhancements
and
> corrections by Martin Maechler (2009). akima: Interpolation of
> irregularly spaced data. R package version 0.5-4.
> http://CRAN.R-project.org/package=akima
> A BibTeX entry for LaTeX users is
> @Manual{,
> title = {akima: Interpolation of irregularly spaced data},
> author = {Fortran code by H. Akima R port by Albrecht Gebhardt aspline 
> function by Thomas Petzoldt <petzoldt at rcs.urz.tu-dresden.de> 
> enhancements and corrections by Martin Maechler},
> year = {2009},
> note = {R package version 0.5-4},
> url = {http://CRAN.R-project.org/package=akima},
> }
> ATTENTION: This citation information has been auto-generated from the
> package DESCRIPTION file and may need manual editing, see
> ?help("citation")? .
>> 
> Yes, the ATTENTION note does say that manual editing may be necessary, 
> but I think a worthy goal would be
> to try to reduce the need for this.
> One simple way to do that would be to support an extra Contributions: 
> field in the DESCRIPTION file,
> so that Authors: can be more cleanly separated for the purpose of 
> creating well-structured BibTeX.
> Perhaps others have better ideas.
> -Michael
> -- 
> Michael Friendly     Email: friendly AT yorku DOT ca
> Professor, Psychology Dept.
> York University      Voice: 416 736-5115 x66249 Fax: 416 736-5814
> 4700 Keele Street    Web:http://www.datavis.ca
> Toronto, ONT  M3J 1P3 CANADA
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel