Stdpopsim: Improve citation rendering in CLI

[jeromekelleher]

Outputing citation information is an important part of stdpopsim. Currently, the rendering of citations in our output is crude, partial and ugly. We should be able to make a text rendering that's much prettier.

This would be a good first issue for someone looking to do some coding on the internals of stdpopsim. The code for rendering is in cli.py.

$ python3 -m stdpopsim homsap -m ooa_3 -l 0.01 10 tmp.trees
If you use this simulation in published work, please cite the following papers:
******************
Simulation engine:
******************
        msprime: Kelleher et al. 2016: https://doi.org/10.1371/journal.pcbi.1004842
******************
Genetic map:
******************
        TODO
Simulation model: Three population out-of-Africa
        Gutenkunst et al., 2009: https://doi.org/10.1371/journal.pgen.1000695

[agladstein]

How would you like it to look prettier?
If I were using it, I would love a plain text output that I could copy and also a latex citation in bib format.
I suppose you could have a cli citation option to output an actual .bib file 😃
Maybe that would be too much. But, if I were a user, I would love it.

[jeromekelleher]

How would you like it to look prettier?

I don't know really, I was hoping someone would be creative and come up with a nice pretty way of rendering this!

BibTex output would be awesome, but would require a fair bit more infrastructure (well, we'd need to store valid bibtex records for each paper). Not that big a deal, we could just copy in the Bibtex records from Google Scholar, but a bit of work all the same.

If this is something you're interested in doing, please open an issue to track it!

[agladstein]

I see. I don't really have ideas on how to make it prettier either...

For BibTex output, I created the issue https://github.com/popgensims/stdpopsim/issues/157

[Chris1221]

BibTex output would be awesome, but would require a fair bit more infrastructure.

If it's reasonable to assume that the user has an internet connection when using the CLI, it could be done on the fly through crossref with the DOIs we already store. (e.g.)

curl -LH "Accept: text/bibliography; style=bibtex" https://doi.org/10.1371/journal.pcbi.1004842

returns

@article{Kelleher_2016, title={Efficient Coalescent Simulation and Genealogical Analysis for Large Sample Sizes}, volume={12}, ISSN={1553-7358}, url={http://dx.doi.org/10.1371/journal.pcbi.1004842}, DOI={10.1371/journal.pcbi.1004842}, number={5}, journal={PLOS Computational Biology}, publisher={Public Library of Science (PLoS)}, author={Kelleher, Jerome and Etheridge, Alison M and McVean, Gilean}, editor={Song, Yun S.Editor}, year={2016}, month={May}, pages={e1004842}}

[jeromekelleher]

OMFG that's the coolest thing I've seen in ages, thanks @Chris1221!

We can easily replicate the curl call internally. I don't think we want to download these everytime, but perhaps we could add an option --bibtex to additionally output the BibTex by making these calls? Or write them to a .bib file, so the user can just copy this file right into their bibtex DB?

I guess we could also just copy the records into the code, but it seems like something that would drift out of date over time.

[agladstein]

That seems like a good option!
Do you know if it's possible to have it return a formatted version?
e.g.

@article{Kelleher_2016, 
     title={Efficient Coalescent Simulation and Genealogical Analysis for Large Sample Sizes}, 
     volume={12}, ISSN={1553-7358}, 
     url={http://dx.doi.org/10.1371/journal.pcbi.1004842}, 
     DOI={10.1371/journal.pcbi.1004842}, 
     number={5}, 
     journal={PLOS Computational Biology}, 
     publisher={Public Library of Science (PLoS)}, 
     author={Kelleher, Jerome and Etheridge, Alison M and McVean, Gilean}, 
     editor={Song, Yun S.Editor}, 
     year={2016}, 
     month={May}, 
     pages={e1004842}
}

Yes, I think adding a --bibtex option is a good idea. Not everyone wants to see a bib output.
Ooh, writing all the citations used to a .bib file would also be great! Maybe --bibtex could print to screen and write to a file, or there could be a seperate --bibtexfile option.

[jeromekelleher]

Let's move the discussion of bibtex to #157 @agladstein --- I think it's a separate issue. I don't think we want to write out bibtex records inline with the text summary here, it would just end up looking like a mess.

[jeromekelleher]

One thing we could do to prettify the current output is to use some box drawing characters to separate the sections rather than the current ascii *s. This would probably make things a bit nicer to look at.

[agladstein]

hmm... but, what if the user wants to copy paste into word/text editor and then format? If it's not simple text, it will be hard to copy paste.
This is thinking of the user who is not going to use bibtex, and just going to do their references by hand. Do people still do that? Should we care about helping those people?

[jeromekelleher]

Well just rendering the banners as unicode won't hurt anyone. The main thing is to write the Author, Year and DOI out for each one. I don't think we can do any more for users of [insert reference non bibtex reference manager] after that. The actual text will still be there for copy-paste purposes.,

[agladstein]

I'm having trouble picturing what using box drawing characters in the current output would look like?
A little example?

[jeromekelleher]

I dunno really, my ideas are pretty vague! I guess I should just play with it.

[jeromekelleher]

Closed in #219.

[agladstein]

So, it doesn't look like anything has changed for the citation rendering in the CLI. Are we just going with the bibtex option is good enough on top of how citations are printed in CLI?

[jeromekelleher]

Yeah, @grahamgower deleted some banners which I think made it look better. We can always revisit.