Add citation method to ImageJPython class

[elevans]

This PR addresses issue #263 and adds a citation method that generates PyImageJ's citation reference and collects the current instance's Python and Java versions.

Running ij.py.cite() produces this citation string:

>>> ij.py.cite()
Rueden, C.T., Hiner, M.C., Evans, E.L. et al.
PyImageJ: A library for integrating ImageJ and Python.
Nat Methods 19, 1326–1327 (2022).
https://doi.org/10.1038/s41592-022-01655-4
-----------------------
Python version: 3.11.11
Java version: 11.0.26

@ctrueden @hinerm @gselzer thoughts?

P.S. I didn't specifically select the first 3 names for the citation, its what Nature methods generates.

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 8.33333% with 11 lines in your changes missing coverage. Please review.

Project coverage is 76.52%. Comparing base (73f4c35) to head (c071d1d). Report is 29 commits behind head on main.

Files with missing lines	Patch %	Lines
src/imagej/__init__.py	8.33%	11 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #325      +/-   ##
==========================================
- Coverage   77.30%   76.52%   -0.79%     
==========================================
  Files          17       17              
  Lines        2036     2100      +64     
==========================================
+ Hits         1574     1607      +33     
- Misses        462      493      +31     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ctrueden]

This is great! 🌟

Do you think we should include any Python package versions? The versions of pyimagej, scyjava, imglyb, jgo, and jpype all affect behavior pretty substantially. I know it might be a slippery slope, but those in particular are most relevant. I'm dine with leaving them out if y'all feel it would be too much, though.

[elevans]

I was thinking the same thing honestly. What do you think about collecting versions for pyimagej, scyjava, imglyb, jgo, jpype, imglib2, scijava-common and then also toss in or parse the output of ij.getVersion() for the ImageJ2 and ImageJ version numbers?

I'll also add in a test so codecov will be happy.

[gselzer]

This is super cool, and would be a great addition to the RTD ala "if you found our work useful, please cite the paper!"

What do you think about collecting versions for pyimagej, scyjava, imglyb, jgo, jpype, imglib2, scijava-common and then also toss in or parse the output of ij.getVersion() for the ImageJ2 and ImageJ version numbers?

The goal of #263 is to aid reproducibility. In other words, we want to be able to reproduce bugs reported by users in addition to being able to reproduce results found from workflows. In pursuit of that goal, I'd lean towards adding more over adding less.

This might mean we need an additional utility, maybe an ij.py.reproduce() or ij.py.about() which lists:

• Maven endpoints
• Relevant python packages
• JVM arguments, maybe?

[ctrueden]

On the Java side, the SystemInformation command gives many details about the Java environment. Maybe we should move this logic into scijava-common, and make the command simply invoke the static method? That way, we'd have access to it in any scyjava-based environment that includes scijava-common on the classpath?

Regarding requirements for this feature: to best foster reproducibility, we may need to dump a large amount of information, which would then obfuscate the actual citation to use... should we make two separate functions? I ask with no clear opinion in either direction.

[gselzer]

Regarding requirements for this feature: to best foster reproducibility, we may need to dump a large amount of information, which would then obfuscate the actual citation to use... should we make two separate functions? I ask with no clear opinion in either direction.

I would think so, this is what I intended when I referenced a second ij.py.reproduce function!

[elevans]

Thanks for the feedback! I totally agree it sounds like we want two different functions here. I'll re-work this to split the citation string method into its own thing and add a ij.py.reproduce function (name TBD).

[elevans]

Okay I made some changes and split ij.py.cite() into ij.py.cite_publication() and ij.py.cite_versions(). Hopefully these method names are self explanatory. Here's what the output looks like:

>>> ij.py.cite_publication()
=====PyImageJ Citation=====
Rueden, C.T., Hiner, M.C., Evans, E.L. et al.
PyImageJ: A library for integrating ImageJ and Python.
Nat Methods 19, 1326–1327 (2022).
https://doi.org/10.1038/s41592-022-01655-4
>>> ij.py.cite_versions()
=====Environment package versions=====
Python:   3.11.11
Java:     11.0.26
pyimagej: 1.6.1.dev0
scyjava:  1.10.2
imglyb:   2.1.0
jgo:      1.0.6
jpype:    1.5.2
>>> 

Both these methods by default print to the console, but you can optionally pass False to the show parameter and get the string returned instead. I figured there might be instances that a user might want the string.

@ctrueden do you want to see more packages listed?