enhancement:support 'cite' command for packages

[jakobkroeker]

Hans-Christian (https://github.com/bothmer) suggested that M2 packages could support a cite command like cite $package showing how to cite a package when its computation results were used in a publication

[DanGrayson]

Making it easy to cite packages would be a good idea. The return value should be a string containing the appropriate bibtex entry. And then it could be a "Command", so without an argument, it would show how to cite Macaulay2 itself.

[DanGrayson]

By the way, anyone who wants to work on one of these issues should get "assigned" to it.

[jakobkroeker]

By the way, anyone who wants to work on one of these issues should get "assigned" to it.

Maybe in 6 months or so I will have some spare time to work on M2 issues.

[aarondall]

I have a modest little package that does exactly that. It pools information from the options table of any given package and prints a first attempt at a bibtex string mimicking the style of the recommended M2 citation.

I'm rather new around here so my two questions are: (1) How do I become an assignee? and (2) Is it better form to send a pull request for a one-method package or is there a way to just share the method?

[DanGrayson]

I've invited you to join the team. If it works well, we might preload the package. I assume it will export just one symbol: "cite" or "citation" or some such.

[aarondall]

Exactly. There is one exported symbol: cite. There is also the option Citation so one can, in the case of certified packages, get the reference to the journal article. As proof of concept, here are two examples:

@Misc{Dmodules,
  author = {Anton Leykin and Harrison Tsai},
  title = {Dmodules: functions for computations with D-modules},
  howpublished = {Available at \url{http://people.math.gatech.edu/~aleykin3/Dmodules}}
}

@Misc{EdgeIdeals,
  author = {Chris Francisco and Andrew Hoefel and Adam Van Tuyl},
  title = {EdgeIdeals: a package for edge ideals.},
  howpublished = {Available at \url{http://www.math.uiuc.edu/Macaulay2/Packages/}}
}

[DanGrayson]

The link to gatech.edu, even though it's listed as the home page of the package, is not the way it's published-- rather, it is published as part of M2. So one may consider providing a link to Macaulay2.com, since the package is part of that. And one may consider providing a link to the the source code tree in github : https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages

The link you give for EdgeIdeals is also not how it's published, but points just to the documentation.

Do you code for distinguishing a package that is part of Macaulay2 from one that is not? For one that is not, then one could use the HomePage entry.

Even for a package which is part of Macaulay2, the package loaded into memory might have the same name but come from a source file outside of Macaulay2, in which case we should regard it as external.

[aarondall]

I was only vaguely aware of the internal/external distinction and thought, naively it turns out, that the package homepage would be, at a minimum, where the source code could be found. To clear up my confusion let me ask a couple of questions:

1. What should the working definition of how published be? If the source code of a packages is available in multiple locations, what should the hierarchy be?

2. How does one test if a package is part of Macaulay2? Is that determined by querying the github M2 packages [repository][rep]?

3. Is the following partition of the packages a reasonable place from which to start?

   • Internal packages with external source code
   • Internal packages with internal source code
   • External packages

4. For certified packages is it best to use the value of the repository code URI in the options table for the package?

At the moment my code does not distinguish between packages that are a part of Macaulay2 and those that are not as this information is typically not deducible from the option table of the package. Moreover, it blindly builds the 'title' keys as an amalgam of the package title and headline in the simplest way, allowing for the following kind of unwanted results.

i1 : loadPackage "PackageCitations";

i2 : cite SimplicialComplexes

o2 = @Misc{SimplicialComplexes,
       author = {Sorin Popescu and Gregory G. Smith and Mike Stillman},
       title = {SimplicialComplexes: simplicial complexes},
       howpublished = {Available at \url{http://www.math.uiuc.edu/Macaulay2/Packages/}}
     }

So there is still quite a bit do be done to get cite to output a desirable citation for every package. But with answers to some of the questions above, I am quite happy to plug away towards that goal.

[DanGrayson]

Probably the journal publication, if there is one, should take precedence, so the link should be to the article in the journal, as you suggest.

To find get the names of Macaulay2 packages, use this:

separate (" ", version#"packages")

Don't query github -- let's try to avoid accessing the network behind the user's back.

To see whether a package was loaded from its location inside a Macaulay2 distribution, do a comparison of these:

i11 : prefixDirectory | currentLayout#"packages"

o11 = /Applications/Macaulay2-1.9.2/share/Macaulay2/

i12 : TangentCone#"source directory"

o12 = /Applications/Macaulay2-1.9.2/share/Macaulay2/

Instead of using the headline, which might also be too long, you could just make the title "Foo : A Macaulay2 package". Can we use italics in titles?

[aarondall]

I managed to sneak some more time in on the citation code using your helpful hints. Given a package P the code firsts tests if P is certified. If so it uses the certification data to produce a citation similar to the following for EdgeIdeals.

i1 : cite EdgeIdeals

o1 = @article{EdgeIdeals,
       title = {EdgeIdeals: a package for (hyper)graphs},
       author = {Chris Francisco and Andrew Hoefel and Adam Van Tuyl},
       journal = {The Journal of Software for Algebra and Geometry: Macaulay2}
       volume = {1},
       year = {2009},
     }

If the package is not certified but is both internal to Macaulay2 and being run from source code internal to M2 then it builds a reasonable title (more on this below) and points to the source code tree in github. For the Dmodules we get the following citation.

i2 : cite Dmodules

o2 = @misc{Dmodules,
       title = {{Dmodules: functions for computations with D-modules}},
       author = {Anton Leykin and Harrison Tsai},
       howpublished = {Available at \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages}}
     }

The Headline for Dmodules is sufficiently nice that it appears after the colon in the title tag of the bibtex entries. More precisely, sufficiently nice means that it is short (no more than ten words), is not the title of the package (or some minor variant thereof), and does not contain a colon :. If the Headline of a given package does not satisfy all of these properties then the default A Macaulay2 package is used. For example the headline of the Macaulay2Doc package is Macaulay2 documentation and the code judges this headline to be too similar to the title.

i3 : cite Macaulay2Doc

o3 = @misc{Macaulay2Doc,
       author = {Daniel R. Grayson and Michael E. Stillman},
       title = {{Macaulay2Doc: A \emph{Macaulay2} package}},
       howpublished = {Available at \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages}}
     }

Note that Macaulay2 will be italicized in the Tex output and that the extra braces are present to preserve capitalization.

For packages being run from source code external to M2 the code looks for the HomePage of the package. For example, we can get a citation for the package PackageCitations whose only method is cite.

i4 : cite PackageCitations

o4 = @misc{PackageCitations,
       title = {{PackageCitations: A \emph{Macaulay2} software package facilitating citation of \emph{Macaulay2} packages}},
       author = {Aaron Dall},
       howpublished = {Available at \url{https://github.com/aarondall/PackageCitations-M2}}
     }

These examples all look good to my eyes but there are examples with anomalous entries in their option tables that, in turn, yield strange citations. The Graphs package is one such package because its headline contains parentheses and its author list contains a list of contributors.

i5 : cite Graphs

o5 = @misc{Graphs,
       title = {{Graphs: Package for processing graphs and directed graphs (digraphs)}},
       author = {Jack Burkart and David Cook II and Caroline Jansen and Amelia Taylor and Augustine O'Keefe and Contributers of note: Alex Diaz, Luis Garcia, Shaowei Lin, Sonja Mapes, Mike Stillman, Doug Torrance},
       howpublished = {Available at \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages}}

As a last example, a citation for Macaulay2 itself is obtained in the obvious way.

i6 : cite M2

o6 = @misc{M2,
       title = {Macaulay2, a software system for research in algebraic geometry},
       author = {Grayson, Daniel R. and Stillman, Michael E.},
       howpublished = {Available at \url{http://www.math.uiuc.edu/Macaulay2/}}
     }

My remaining questions are

1. Are there any suggestions for improving the citations given in the examples above?
2. How should the method handle anomalous option table entries?

[DanGrayson]

Thanks!

To see whether those bibtex entries are good enough, TeX them and see how they look in the bibliography. Will the authors for Graphs look good enough? I'm suspicious.

Make "cite" into a Command so that instead of "cite M2" one can type just "cite". Unless you've already done that.

Make sure "cite" takes either a string or an object of type Package, loading the package if necessary, but not if it's already loaded.

Perhaps modify our "help" command so that it also says:

• cite -- show bibtex entry for citing Macaulay2
• cite "Foo" -- show bibtex entry for citing the package Foo

When you're ready, we'll welcome a pull request. We're trying to release 1.9.3 in not too much longer.

[aarondall]

The cite command is now behaving rather well. A bibliography containing a citation for every internal Macaulay2 package as well as a few external packages that I use is available here. The linked document also contains a list of caveats, exceptions, and bugs. Any suggestions are most welcome.

Also, I do not understand what you mean by "modify the help command". Is that simply a line or two that I add in the package source?

[DanGrayson]

Thanks, how about submitting a pull request?

Maybe modifying the "help" command is not the right thing to do -- I can think about that later.

[aarondall]

Done. The pull request is here.

[DanGrayson]

Thanks, it's quite good.

I've made your headline briefer, to fit the headlines of the other packages. Headlines implicitly describe Macaulay2 packages, so they don't have to say that.