| 1 |
Metadata-Version: 2.4 |
| 2 |
Name: duecredit |
| 3 |
Version: 0.11.2 |
| 4 |
Summary: Publications (and donations) tracer |
| 5 |
Author: Matteo Visconti di Oleggio Castello |
| 6 |
Author-email: Yaroslav Halchenko <[email protected]> |
| 7 |
License-Expression: BSD-2-Clause |
| 8 |
Project-URL: Homepage, https://github.com/duecredit/duecredit |
| 9 |
Keywords: citation tracing |
| 10 |
Classifier: Development Status :: 4 - Beta |
| 11 |
Classifier: Environment :: Console |
| 12 |
Classifier: Environment :: Other Environment |
| 13 |
Classifier: Environment :: Web Environment |
| 14 |
Classifier: Intended Audience :: Developers |
| 15 |
Classifier: Intended Audience :: Education |
| 16 |
Classifier: Intended Audience :: End Users/Desktop |
| 17 |
Classifier: Intended Audience :: Legal Industry |
| 18 |
Classifier: Intended Audience :: Other Audience |
| 19 |
Classifier: Intended Audience :: Science/Research |
| 20 |
Classifier: Operating System :: OS Independent |
| 21 |
Classifier: Programming Language :: Python |
| 22 |
Classifier: Programming Language :: Python :: 3 |
| 23 |
Classifier: Topic :: Documentation |
| 24 |
Classifier: Topic :: Software Development :: Documentation |
| 25 |
Classifier: Topic :: Software Development :: Libraries :: Python Modules |
| 26 |
Requires-Python: >=3.9 |
| 27 |
Description-Content-Type: text/markdown |
| 28 |
License-File: LICENSE |
| 29 |
Requires-Dist: citeproc-py>=0.5 |
| 30 |
Requires-Dist: looseversion |
| 31 |
Requires-Dist: packaging |
| 32 |
Requires-Dist: requests |
| 33 |
Provides-Extra: tests |
| 34 |
Requires-Dist: pytest; extra == "tests" |
| 35 |
Requires-Dist: pytest-cov; extra == "tests" |
| 36 |
Requires-Dist: vcrpy; extra == "tests" |
| 37 |
Dynamic: license-file |
| 38 |
|
| 39 |
# duecredit |
| 40 |
|
| 41 |
|
| 42 |
[](https://coveralls.io/r/duecredit/duecredit) |
| 43 |
[](https://doi.org/10.5281/zenodo.3376260) |
| 44 |
[](https://pypi.python.org/pypi/duecredit/) |
| 45 |
|
| 46 |
duecredit is being conceived to address the problem of inadequate |
| 47 |
citation of scientific software and methods, and limited visibility of |
| 48 |
donation requests for open-source software. |
| 49 |
|
| 50 |
It provides a simple framework (at the moment for Python only) to |
| 51 |
embed publication or other references in the original code so they are |
| 52 |
automatically collected and reported to the user at the necessary |
| 53 |
level of reference detail, i.e. only references for actually used |
| 54 |
functionality will be presented back if software provides multiple |
| 55 |
citeable implementations. |
| 56 |
|
| 57 |
## Installation |
| 58 |
|
| 59 |
Duecredit is easy to install via pip, simply type: |
| 60 |
|
| 61 |
`pip install duecredit` |
| 62 |
|
| 63 |
## Examples |
| 64 |
|
| 65 |
### To cite the modules and methods you are using |
| 66 |
|
| 67 |
You can already start "registering" citations using duecredit in your |
| 68 |
Python modules and even registering citations (we call this approach "injections") |
| 69 |
for modules that do not (yet) use duecredit. duecredit will remain an optional |
| 70 |
dependency, i.e. your software will work correctly even without duecredit installed. |
| 71 |
|
| 72 |
For example, list citations of the modules and methods `yourproject` uses with a few simple commands: |
| 73 |
```bash |
| 74 |
cd /path/to/yourmodule # for ~/yourproject |
| 75 |
cd yourproject # change directory into where the main code base is |
| 76 |
python -m duecredit yourproject.py |
| 77 |
``` |
| 78 |
Or you can also display them in BibTex format, using: |
| 79 |
```bash |
| 80 |
duecredit summary --format=bibtex |
| 81 |
``` |
| 82 |
See this gif animation for a better illustration: |
| 83 |
 |
| 84 |
|
| 85 |
|
| 86 |
### To let others cite your software |
| 87 |
|
| 88 |
|
| 89 |
For using duecredit in your software |
| 90 |
|
| 91 |
1. Copy `duecredit/stub.py` to your codebase, e.g. |
| 92 |
|
| 93 |
wget -q -O /path/tomodule/yourmodule/due.py \ |
| 94 |
https://raw.githubusercontent.com/duecredit/duecredit/master/duecredit/stub.py |
| 95 |
|
| 96 |
|
| 97 |
**Note** that it might be better to avoid naming it duecredit.py to avoid shadowing |
| 98 |
installed duecredit. |
| 99 |
|
| 100 |
2. Then use `duecredit` import due and necessary entries in your code as |
| 101 |
|
| 102 |
from .due import due, Doi, BibTeX |
| 103 |
|
| 104 |
To provide a generic reference for the entire module just use e.g. |
| 105 |
|
| 106 |
due.cite(Doi("1.2.3/x.y.z"), description="Solves all your problems", path="magicpy") |
| 107 |
|
| 108 |
By default, the added reference does not show up in the summary report (but see the |
| 109 |
`User-view` section below). If your reference is to a core package and you find that it |
| 110 |
should be listed in the summary then set `cite_module=True` (see [here](https://github.com/duecredit/duecredit/blob/master/duecredit/collector.py#L35) for a complete |
| 111 |
description of the arguments) |
| 112 |
|
| 113 |
due.cite(Doi("1.2.3/x.y.z"), description="The Answer to Everything", path="magicpy", cite_module=True) |
| 114 |
|
| 115 |
Similarly, to provide a direct reference for a function or a method, use the `dcite` decorator (by default |
| 116 |
this decorator sets cite_module=True) |
| 117 |
|
| 118 |
@due.dcite(Doi("1.2.3/x.y.z"), description="Resolves constipation issue") |
| 119 |
def pushit(): |
| 120 |
... |
| 121 |
|
| 122 |
You can easily obtain a DOI for your software using Zenodo.org and a few other DOI providers. |
| 123 |
|
| 124 |
References can also be entered as BibTeX entries |
| 125 |
|
| 126 |
due.cite(BibTeX(""" |
| 127 |
@article{mynicearticle, |
| 128 |
title={A very cool paper}, |
| 129 |
author={Happy, Author and Lucky, Author}, |
| 130 |
journal={The Journal of Serendipitous Discoveries} |
| 131 |
} |
| 132 |
"""), |
| 133 |
description="Solves all your problems", path="magicpy") |
| 134 |
|
| 135 |
## Now what |
| 136 |
|
| 137 |
### Do the due |
| 138 |
|
| 139 |
Once you obtained the references in the duecredit output, include them in in the references section of your paper or software. |
| 140 |
|
| 141 |
### Add injections for other existing modules |
| 142 |
|
| 143 |
We hope that eventually this somewhat cruel approach will not be necessary. But |
| 144 |
until other packages support duecredit "natively" we have provided a way to "inject" |
| 145 |
citations for modules and/or functions and methods via injections: citations will be |
| 146 |
added to the corresponding functionality upon those modules import. |
| 147 |
|
| 148 |
All injections are collected under |
| 149 |
[duecredit/injections](https://github.com/duecredit/duecredit/tree/master/duecredit/injections). |
| 150 |
See any file there with `mod_` prefix for a complete example. But |
| 151 |
overall it is just a regular Python module defining a function |
| 152 |
`inject(injector)` which will then add new entries to the injector, |
| 153 |
which will in turn add those entries to the duecredit whenever the |
| 154 |
corresponding module gets imported. |
| 155 |
|
| 156 |
|
| 157 |
## User-view |
| 158 |
|
| 159 |
|
| 160 |
By default `duecredit` does exactly nothing -- all decorators do not |
| 161 |
decorate, all `cite` functions just return, so there should be no fear |
| 162 |
that it would break anything. Then whenever anyone runs their analysis |
| 163 |
which uses your code and sets `DUECREDIT_ENABLE=yes` environment |
| 164 |
variable or uses `python -m duecredit`, and invokes any of the cited |
| 165 |
function/methods, at the end of the run all collected bibliography |
| 166 |
will be presented to the screen and pickled into `.duecredit.p` file |
| 167 |
in the current directory or to your `DUECREDIT_FILE` environment setting: |
| 168 |
|
| 169 |
$> python -m duecredit examples/example_scipy.py |
| 170 |
I: Simulating 4 blobs |
| 171 |
I: Done clustering 4 blobs |
| 172 |
|
| 173 |
DueCredit Report: |
| 174 |
- Scientific tools library / numpy (v 1.10.4) [1] |
| 175 |
- Scientific tools library / scipy (v 0.14) [2] |
| 176 |
- Single linkage hierarchical clustering / scipy.cluster.hierarchy:linkage (v 0.14) [3] |
| 177 |
|
| 178 |
2 packages cited |
| 179 |
0 modules cited |
| 180 |
1 function cited |
| 181 |
|
| 182 |
References |
| 183 |
---------- |
| 184 |
|
| 185 |
[1] Van Der Walt, S., Colbert, S.C. & Varoquaux, G., 2011. The NumPy array: a structure for efficient numerical computation. Computing in Science & Engineering, 13(2), pp.22–30. |
| 186 |
[2] Jones, E. et al., 2001. SciPy: Open source scientific tools for Python. |
| 187 |
[3] Sibson, R., 1973. SLINK: an optimally efficient algorithm for the single-link cluster method. The Computer Journal, 16(1), pp.30–34. |
| 188 |
|
| 189 |
|
| 190 |
Incremental runs of various software would keep enriching that file. |
| 191 |
Then you can use `duecredit summary` command to show that information |
| 192 |
again (stored in `.duecredit.p` file) or export it as a BibTeX file |
| 193 |
ready for reuse, e.g.: |
| 194 |
|
| 195 |
$> duecredit summary --format=bibtex |
| 196 |
@article{van2011numpy, |
| 197 |
title={The NumPy array: a structure for efficient numerical computation}, |
| 198 |
author={Van Der Walt, Stefan and Colbert, S Chris and Varoquaux, Gael}, |
| 199 |
journal={Computing in Science \& Engineering}, |
| 200 |
volume={13}, |
| 201 |
number={2}, |
| 202 |
pages={22--30}, |
| 203 |
year={2011}, |
| 204 |
publisher={AIP Publishing} |
| 205 |
} |
| 206 |
@Misc{JOP+01, |
| 207 |
author = {Eric Jones and Travis Oliphant and Pearu Peterson and others}, |
| 208 |
title = {{SciPy}: Open source scientific tools for {Python}}, |
| 209 |
year = {2001--}, |
| 210 |
url = "http://www.scipy.org/", |
| 211 |
note = {[Online; accessed 2015-07-13]} |
| 212 |
} |
| 213 |
@article{sibson1973slink, |
| 214 |
title={SLINK: an optimally efficient algorithm for the single-link cluster method}, |
| 215 |
author={Sibson, Robin}, |
| 216 |
journal={The Computer Journal}, |
| 217 |
volume={16}, |
| 218 |
number={1}, |
| 219 |
pages={30--34}, |
| 220 |
year={1973}, |
| 221 |
publisher={Br Computer Soc} |
| 222 |
} |
| 223 |
|
| 224 |
|
| 225 |
and if by default only references for "implementation" are listed, we |
| 226 |
can enable listing of references for other tags as well (e.g. "edu" |
| 227 |
depicting instructional materials -- textbooks etc. on the topic): |
| 228 |
|
| 229 |
$> DUECREDIT_REPORT_TAGS=* duecredit summary |
| 230 |
|
| 231 |
DueCredit Report: |
| 232 |
- Scientific tools library / numpy (v 1.10.4) [1] |
| 233 |
- Scientific tools library / scipy (v 0.14) [2] |
| 234 |
- Hierarchical clustering / scipy.cluster.hierarchy (v 0.14) [3, 4, 5, 6, 7, 8, 9] |
| 235 |
- Single linkage hierarchical clustering / scipy.cluster.hierarchy:linkage (v 0.14) [10, 11] |
| 236 |
|
| 237 |
2 packages cited |
| 238 |
1 module cited |
| 239 |
1 function cited |
| 240 |
|
| 241 |
References |
| 242 |
---------- |
| 243 |
|
| 244 |
[1] Van Der Walt, S., Colbert, S.C. & Varoquaux, G., 2011. The NumPy array: a structure for efficient numerical computation. Computing in Science & Engineering, 13(2), pp.22–30. |
| 245 |
[2] Jones, E. et al., 2001. SciPy: Open source scientific tools for Python. |
| 246 |
[3] Sneath, P.H. & Sokal, R.R., 1962. Numerical taxonomy. Nature, 193(4818), pp.855–860. |
| 247 |
[4] Batagelj, V. & Bren, M., 1995. Comparing resemblance measures. Journal of classification, 12(1), pp.73–90. |
| 248 |
[5] Sokal, R.R., Michener, C.D. & University of Kansas, 1958. A Statistical Method for Evaluating Systematic Relationships, University of Kansas. |
| 249 |
[6] Jain, A.K. & Dubes, R.C., 1988. Algorithms for clustering data, Prentice-Hall, Inc.. |
| 250 |
[7] Johnson, S.C., 1967. Hierarchical clustering schemes. Psychometrika, 32(3), pp.241–254. |
| 251 |
[8] Edelbrock, C., 1979. Mixture model tests of hierarchical clustering algorithms: the problem of classifying everybody. Multivariate Behavioral Research, 14(3), pp.367–384. |
| 252 |
[9] Fisher, R.A., 1936. The use of multiple measurements in taxonomic problems. Annals of eugenics, 7(2), pp.179–188. |
| 253 |
[10] Gower, J.C. & Ross, G., 1969. Minimum spanning trees and single linkage cluster analysis. Applied statistics, pp.54–64. |
| 254 |
[11] Sibson, R., 1973. SLINK: an optimally efficient algorithm for the single-link cluster method. The Computer Journal, 16(1), pp.30–34. |
| 255 |
|
| 256 |
The `DUECREDIT_REPORT_ALL` flag allows one to output all the references |
| 257 |
for the modules that lack objects or functions with citations. |
| 258 |
Compared to the previous example, the following output additionally |
| 259 |
shows a reference for scikit-learn since `example_scipy.py` uses |
| 260 |
an uncited function from that package. |
| 261 |
|
| 262 |
$> DUECREDIT_REPORT_TAGS=* DUECREDIT_REPORT_ALL=1 duecredit summary |
| 263 |
|
| 264 |
DueCredit Report: |
| 265 |
- Scientific tools library / numpy (v 1.10.4) [1] |
| 266 |
- Scientific tools library / scipy (v 0.14) [2] |
| 267 |
- Hierarchical clustering / scipy.cluster.hierarchy (v 0.14) [3, 4, 5, 6, 7, 8, 9] |
| 268 |
- Single linkage hierarchical clustering / scipy.cluster.hierarchy:linkage (v 0.14) [10, 11] |
| 269 |
- Machine Learning library / sklearn (v 0.15.2) [12] |
| 270 |
|
| 271 |
3 packages cited |
| 272 |
1 module cited |
| 273 |
1 function cited |
| 274 |
|
| 275 |
References |
| 276 |
---------- |
| 277 |
|
| 278 |
[1] Van Der Walt, S., Colbert, S.C. & Varoquaux, G., 2011. The NumPy array: a structure for efficient numerical computation. Computing in Science & Engineering, 13(2), pp.22–30. |
| 279 |
[2] Jones, E. et al., 2001. SciPy: Open source scientific tools for Python. |
| 280 |
[3] Sneath, P.H. & Sokal, R.R., 1962. Numerical taxonomy. Nature, 193(4818), pp.855–860. |
| 281 |
... |
| 282 |
|
| 283 |
## Tags |
| 284 |
|
| 285 |
|
| 286 |
You are welcome to introduce new tags specific to your citations but we hope |
| 287 |
that for consistency across projects, you would use the following tags |
| 288 |
|
| 289 |
- `implementation` (default) — an implementation of the cited method |
| 290 |
- `reference-implementation` — the original implementation (ideally by |
| 291 |
the authors of the paper) of the cited method |
| 292 |
- `another-implementation` — some other implementation of |
| 293 |
the method, e.g. if you would like to provide a citation for another |
| 294 |
implementation of the method you have implemented in your code and for |
| 295 |
which you have already provided `implementation` or |
| 296 |
`reference-implementation` tag |
| 297 |
- `use` — publications demonstrating a worthwhile noting use of the |
| 298 |
method |
| 299 |
- `edu` — tutorials, textbooks and other materials useful to learn |
| 300 |
more about cited functionality |
| 301 |
- `donate` — should be commonly used with URL entries to point to the |
| 302 |
websites describing how to contribute some funds to the referenced |
| 303 |
project |
| 304 |
- `funding` — to point to the sources of funding which provided support |
| 305 |
for a given functionality implementation and/or method development |
| 306 |
- `dataset` - for datasets |
| 307 |
|
| 308 |
## Ultimate goals |
| 309 |
|
| 310 |
|
| 311 |
### Reduce demand for prima ballerina projects |
| 312 |
|
| 313 |
**Problem**: Scientific software is often developed to gain citations for |
| 314 |
original publication through the use of the software implementing it. |
| 315 |
Unfortunately, such an established procedure discourages contributions |
| 316 |
to existing projects and fosters new projects to be developed from |
| 317 |
scratch. |
| 318 |
|
| 319 |
**Solution**: With easy ways to provide all-and-only relevant references |
| 320 |
for used functionality within a large(r) framework, scientific |
| 321 |
developers will prefer to contribute to already existing projects. |
| 322 |
|
| 323 |
**Benefits**: As a result, scientific developers will immediately benefit |
| 324 |
from adhering to proper development procedures (codebase structuring, |
| 325 |
testing, etc) and already established delivery and deployment channels |
| 326 |
existing projects already have. This will increase efficiency and |
| 327 |
standardization of scientific software development, thus addressing |
| 328 |
many (if not all) core problems with scientific software development |
| 329 |
everyone likes to bash about (reproducibility, longevity, etc.). |
| 330 |
|
| 331 |
### Adequately reference core libraries |
| 332 |
|
| 333 |
**Problem**: Scientific software often, if not always, uses 3rd party |
| 334 |
libraries (e.g., NumPy, SciPy, atlas) which might not even be visible |
| 335 |
at the user level. Therefore they are rarely referenced in the |
| 336 |
publications despite providing the fundamental core for solving a |
| 337 |
scientific problem at hand. |
| 338 |
|
| 339 |
**Solution**: With automated bibliography compilation for all used |
| 340 |
libraries, such projects and their authors would get a chance to |
| 341 |
receive adequate citability. |
| 342 |
|
| 343 |
**Benefits**: Adequate appreciation of the scientific software |
| 344 |
developments. Coupled with a solution for "prima ballerina" problem, |
| 345 |
more contributions will flow into the core/foundational projects |
| 346 |
making new methodological developments readily available to even wider |
| 347 |
audiences without proliferation of the low quality scientific software. |
| 348 |
|
| 349 |
|
| 350 |
## Similar/related projects |
| 351 |
|
| 352 |
[sempervirens](https://github.com/njsmith/sempervirens) -- *an |
| 353 |
experimental prototype for gathering anonymous, opt-in usage data for |
| 354 |
open scientific software*. Eventually, in duecredit we aim either to |
| 355 |
provide similar functionality (since we are collecting such |
| 356 |
information as well) or just interface/report to sempervirens. |
| 357 |
|
| 358 |
[citepy](https://github.com/clbarnes/citepy) -- Easily cite software libraries using information from automatically gathered from their package repository. |
| 359 |
|
| 360 |
## Currently used by |
| 361 |
|
| 362 |
This is a running list of projects that use DueCredit natively. If you |
| 363 |
are using DueCredit, or plan to use it, please consider sending a pull |
| 364 |
request and add your project to this list. Thanks to |
| 365 |
[@fedorov](https://github.com/fedorov) for the idea. |
| 366 |
|
| 367 |
- [PyMVPA](http://www.pymvpa.org) |
| 368 |
- [fatiando](https://github.com/fatiando/fatiando) |
| 369 |
- [Nipype](https://github.com/nipy/nipype) |
| 370 |
- [QInfer](https://github.com/QInfer/python-qinfer) |
| 371 |
- [shablona](https://github.com/uwescience/shablona) |
| 372 |
- [gfusion](https://github.com/mvdoc/gfusion) |
| 373 |
- [pybids](https://github.com/INCF/pybids) |
| 374 |
- [Quickshear](https://github.com/nipy/quickshear) |
| 375 |
- [meqc](https://github.com/emdupre/meqc) |
| 376 |
- [MDAnalysis](https://www.mdanalysis.org) |
| 377 |
- [bctpy](https://github.com/aestrivex/bctpy) |
| 378 |
- [TorchIO](https://github.com/fepegar/torchio) |
| 379 |
- [BIDScoin](https://github.com/Donders-Institute/bidscoin) |
| 380 |
|
| 381 |
Last updated 2024-02-23. |