Scope

This PR changes the way we present citations in pyDARN. I've removed the citations banner that is printed each time pyDARN is imported (very highly requested by users).

The information about citations is all now contained in the citations module, you can print a list of citations and a list of acknowledgement information from this class. All this information has been updated and is available in the documentation.

Developers are encouraged to include any citations in their code in the doc strings for their methods, and add to the documentation where necessary.

Some general thoughts from me: So, users don't want to have things pop up in command line, so we can't just print citations when used to command line. As a general rule, pyDARN itself does not create files, so I'm not going to start making bibtex files (especially because we only have ~5 journal citations for the whole code and the full citations are all available in the documentation). The user needs to actually print it or look in the documentation.

Adding a citation keyword to all plotting methods to collect citations used and print is doable, but is also far more work than you might think, and I can't put that time aside for pyDARN right now. It is something we might want to look at again in the future if this is still an issue. (Still requires user to choose the option though). The citations module has been written with this in mind for the future.

I'm of the opinion that we have given all required information in an accessible format, whilst also trying to limit what we print to command line, it is ultimately up to the user themselves to provide correct citations in their publications, along with the reviewers and editors of the journals to enforce and check this. This is a community wide problem, and is out of scope for pyDARN alone to solve.

Obviously all thoughts and feelings on this topic are welcome for discussion in the issue, there was no movement on there so I went ahead and did what I thought was best for now

issue: to close #318

Approval

Number of approvals: 1 for code review, DVWG agrees that the full solution for enforcing citations is not for us at pyDARN to solve.

Test

matplotlib version: 3.7.1 Note testers: please indicate what version of matplotlib you are using Not required here.

import pydarn

You should get nothing printed to the command line.

pydarn.Citations.print_citations()
pydarn.Citations.print_acknowledgements()

will return:

If using pyDARN produced plots in publications please be aware of the following citations that may have been used to produce your plot and should be included in your publication:

 Ground Scatter Mapped Range:  Bristow, W. A. et al, 1994, 10.1029/93JA01470 
 AACGMv2 Wrapper:              Burrell, A. G. et al, 2023, 10.5281/zenodo.7621545 
 Chisham Virtual Height Model: Chisham, G. 2008, 10.5194/angeo-26-823-2008 
 pyDARN Software:              DVWG, 2023, 10.5281/zenodo.3727269 
 pyDARNio Software:            DVWG, 2023, 10.5281/zenodo.4009470 
 Cartopy:                      Met Office, 2010-2015, scitools.org.uk/cartopy 
 AACGMv2 article:              Shepherd, S. G., 2014, 10.1002/2014JA020264 
 Elevation Angle Calculations: Shepherd, S. G., 2017, 10.1002/2017RS006348 
 Ground Scatter Mapped Range:  Thomas, E. G. et al, 2022, 10.1029/2022RS007429 

Further information can be found at https://pydarn.readthedocs.io/en/main/user/citing/

Acknowledgement required for SuperDARN data use:

The authors acknowledge the use of SuperDARN data. SuperDARN is a collection of radars funded by national scientific funding agencies of Australia, Canada, China, France, Italy, Japan, Norway, South Africa, United Kingdom and the United States of America. 

During your study, if using data from individual radars only, please contact the Principal Investigator (PI) of that radar about potential co-authorship or appropriate acknowledgments.

SuperDARN / pydarn

EHN: Citations Module #342

Scope

Approval

Test