Debian Codegraph @

PKG-INFO

raw
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 [![Coverage Status](https://coveralls.io/repos/duecredit/duecredit/badge.svg)](https://coveralls.io/r/duecredit/duecredit)
43 [![DOI](https://zenodo.org/badge/DOI/110.5281/zenodo.3376260.svg)](https://doi.org/10.5281/zenodo.3376260)
44 [![PyPI version fury.io](https://badge.fury.io/py/duecredit.svg)](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 ![Example](examples/duecredit_example.gif)
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.