duecredit

duecredit旨在解决科学软件和方法引用不足，以及开源软件捐赠请求可见性有限的问题。

它提供了一个简单的框架（目前仅适用于Python），可以将出版物或其他引用嵌入到原始代码中，以便在必要的引用详细级别自动收集和向用户报告，即如果软件提供了多个可引用的实现，则只会呈现实际使用功能的相关引用。

安装

通过pip安装duecredit非常简单，只需输入

pip install duecredit

示例

引用您正在使用的模块和方法

您可以使用duecredit在Python模块中“注册”引用，甚至为尚未使用duecredit的模块注册引用（我们称此方法为“注入”）。duecredit将保持为可选依赖项，即即使未安装duecredit，您的软件也能正常工作。

例如，使用几个简单的命令列出yourproject使用的模块和方法的引用

cd /path/to/yourmodule # for ~/yourproject
cd yourproject # change directory into where the main code base is
python -m duecredit yourproject.py

或者，您也可以使用以下命令以BibTex格式显示它们

duecredit summary --format=bibtex

请参阅这个GIF动画以获得更好的说明：

让他人引用您的软件

在您的软件中使用duecredit

1. 将duecredit/stub.py复制到您的代码库中，例如：

    wget -q -O /path/tomodule/yourmodule/due.py \
      https://raw.githubusercontent.com/duecredit/duecredit/master/duecredit/stub.py
   

   注意最好避免将其命名为duecredit.py，以避免覆盖已安装的duecredit。

2. 然后在您的代码中使用duecredit导入due和必要的条目，如下所示：

    from .due import due, Doi, BibTeX
   

   为了提供整个模块的通用参考，只需使用例如：

     due.cite(Doi("1.2.3/x.y.z"), description="Solves all your problems", path="magicpy")
   

   默认情况下，添加的引用不会出现在总结报告中（但请参阅下面的User-view部分）。如果您的引用是针对核心包，并且您发现它应该列在总结中，则设置cite_module=True（有关参数的完整描述，请参阅此处）

     due.cite(Doi("1.2.3/x.y.z"), description="The Answer to Everything", path="magicpy", cite_module=True)
   

   类似地，为了提供函数或方法的直接引用，请使用dcite装饰器（默认情况下，此装饰器设置cite_module=True）

     @due.dcite(Doi("1.2.3/x.y.z"), description="Resolves constipation issue")
     def pushit():
         ...
   

   您可以使用Zenodo.org和其他一些DOI提供者轻松地为您的软件获取DOI。

引用也可以作为BibTeX条目输入

    due.cite(BibTeX("""
            @article{mynicearticle,
            title={A very cool paper},
            author={Happy, Author and Lucky, Author},
            journal={The Journal of Serendipitous Discoveries}
            }
            """),
            description="Solves all your problems", path="magicpy")

现在怎么办

完成它

一旦您在duecredit输出中获得了引用，请将它们包含在您的论文或软件的参考文献部分。

添加其他现有模块的注入

我们希望最终这种有些残酷的方法将不再必要。但在其他包“原生”支持duecredit之前，我们已经提供了一种通过注入在模块和/或函数和方法中添加引用的方法：在导入相应的模块时，将添加到相应的功能中。

所有注入都收集在duecredit/injections下。请参阅任何带有mod_前缀的文件以获取完整的示例。但总的来说，它只是一个常规的Python模块，定义了一个名为inject(injector)的函数，它将随后将新条目添加到注入器中，注入器随后将那些条目添加到duecredit中，每当导入相应的模块时。

User-view

默认情况下，duecredit确实什么也不做——所有装饰器都不进行装饰，所有cite函数都仅返回，因此不应担心它会破坏任何东西。然后，无论何时有人运行他们的分析，使用您的代码并设置DUECREDIT_ENABLE=yes环境变量或使用python -m duecredit，并调用任何引用的函数/方法，运行结束时，所有收集到的参考文献都将显示在屏幕上，并pickle到当前目录中的.duecredit.p文件或您的DUECREDIT_FILE环境设置中

$> python -m duecredit examples/example_scipy.py
I: Simulating 4 blobs
I: Done clustering 4 blobs

DueCredit Report:
- Scientific tools library / numpy (v 1.10.4) [1]
- Scientific tools library / scipy (v 0.14) [2]
  - Single linkage hierarchical clustering / scipy.cluster.hierarchy:linkage (v 0.14) [3]

2 packages cited
0 modules cited
1 function cited

References
----------

[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.
[2] Jones, E. et al., 2001. SciPy: Open source scientific tools for Python.
[3] Sibson, R., 1973. SLINK: an optimally efficient algorithm for the single-link cluster method. The Computer Journal, 16(1), pp.30–34.

各种软件的增量运行将不断丰富该文件。然后您可以使用duecredit summary命令再次显示该信息（存储在.duecredit.p文件中）或将其导出为BibTeX文件以供重用，例如：

$> duecredit summary --format=bibtex
@article{van2011numpy,
        title={The NumPy array: a structure for efficient numerical computation},
        author={Van Der Walt, Stefan and Colbert, S Chris and Varoquaux, Gael},
        journal={Computing in Science \& Engineering},
        volume={13},
        number={2},
        pages={22--30},
        year={2011},
        publisher={AIP Publishing}
        }
@Misc{JOP+01,
      author =    {Eric Jones and Travis Oliphant and Pearu Peterson and others},
      title =     {{SciPy}: Open source scientific tools for {Python}},
      year =      {2001--},
      url = "https://scipy.org.cn/",
      note = {[Online; accessed 2015-07-13]}
    }
@article{sibson1973slink,
        title={SLINK: an optimally efficient algorithm for the single-link cluster method},
        author={Sibson, Robin},
        journal={The Computer Journal},
        volume={16},
        number={1},
        pages={30--34},
        year={1973},
        publisher={Br Computer Soc}
    }

并且如果默认情况下仅列出“实现”的引用，我们还可以启用列出其他标签的引用（例如，“edu”表示有关该主题的教学材料——教科书等）

$> DUECREDIT_REPORT_TAGS=* duecredit summary

DueCredit Report:
- Scientific tools library / numpy (v 1.10.4) [1]
- Scientific tools library / scipy (v 0.14) [2]
  - Hierarchical clustering / scipy.cluster.hierarchy (v 0.14) [3, 4, 5, 6, 7, 8, 9]
  - Single linkage hierarchical clustering / scipy.cluster.hierarchy:linkage (v 0.14) [10, 11]

2 packages cited
1 module cited
1 function cited

References
----------

[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.
[2] Jones, E. et al., 2001. SciPy: Open source scientific tools for Python.
[3] Sneath, P.H. & Sokal, R.R., 1962. Numerical taxonomy. Nature, 193(4818), pp.855–860.
[4] Batagelj, V. & Bren, M., 1995. Comparing resemblance measures. Journal of classification, 12(1), pp.73–90.
[5] Sokal, R.R., Michener, C.D. & University of Kansas, 1958. A Statistical Method for Evaluating Systematic Relationships, University of Kansas.
[6] Jain, A.K. & Dubes, R.C., 1988. Algorithms for clustering data, Prentice-Hall, Inc..
[7] Johnson, S.C., 1967. Hierarchical clustering schemes. Psychometrika, 32(3), pp.241–254.
[8] Edelbrock, C., 1979. Mixture model tests of hierarchical clustering algorithms: the problem of classifying everybody. Multivariate Behavioral Research, 14(3), pp.367–384.
[9] Fisher, R.A., 1936. The use of multiple measurements in taxonomic problems. Annals of eugenics, 7(2), pp.179–188.
[10] Gower, J.C. & Ross, G., 1969. Minimum spanning trees and single linkage cluster analysis. Applied statistics, pp.54–64.
[11] Sibson, R., 1973. SLINK: an optimally efficient algorithm for the single-link cluster method. The Computer Journal, 16(1), pp.30–34.

DUECREDIT_REPORT_ALL标志允许您输出缺少对象或具有引用的函数的模块的所有引用。与前面的示例相比，以下输出还显示了scikit-learn的引用，因为example_scipy.py使用了一个未引用的该包的函数。

$> DUECREDIT_REPORT_TAGS=* DUECREDIT_REPORT_ALL=1 duecredit summary

DueCredit Report:
- Scientific tools library / numpy (v 1.10.4) [1]
- Scientific tools library / scipy (v 0.14) [2]
  - Hierarchical clustering / scipy.cluster.hierarchy (v 0.14) [3, 4, 5, 6, 7, 8, 9]
  - Single linkage hierarchical clustering / scipy.cluster.hierarchy:linkage (v 0.14) [10, 11]
- Machine Learning library / sklearn (v 0.15.2) [12]

3 packages cited
1 module cited
1 function cited

References
----------

[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.
[2] Jones, E. et al., 2001. SciPy: Open source scientific tools for Python.
[3] Sneath, P.H. & Sokal, R.R., 1962. Numerical taxonomy. Nature, 193(4818), pp.855–860.
...

标签

您可以根据您的引用引入特定的新标签，但我们希望为了项目之间的一致性，您会使用以下标签：

• implementation（默认）——引用方法的实现
• reference-implementation——引用方法的原始实现（理想情况下由论文的作者实现）
• another-implementation——该方法的其他实现，例如，如果您想为您的代码中实现的方法的其他实现提供引用，并且您已经为它提供了implementation或reference-implementation标签
• use——演示方法值得注意的使用价值的出版物
• edu — 教程、教科书和其他有助于了解引用功能的有用材料
• donate — 通常与URL条目一起使用，以指向描述如何向引用项目捐款的网站
• funding — 指向为特定功能实现和/或方法开发提供支持的资助来源
• dataset - 用于数据集

最终目标

减少对首席女主角项目的需求

问题：科学软件往往是通过使用实现它的软件来获得原始发表的引用。不幸的是，这种既定的程序阻碍了对现有项目的贡献，并鼓励从头开始开发新项目。

解决方案：通过以简单的方式提供对大（更）框架中使用的所有相关功能的引用，科学开发者将更愿意为现有项目做出贡献。

好处：因此，科学开发者将立即从遵循适当的发展程序（代码库结构、测试等）和现有项目已经拥有的既定交付和部署渠道中受益。这将提高科学软件开发效率，从而解决许多（如果不是所有）与科学软件开发相关的问题（可重复性、持久性等）。

充分引用核心库

问题：科学软件往往，如果不是总是，使用第三方库（例如，NumPy、SciPy、atlas），这些库可能在用户层面甚至不可见。因此，尽管它们为解决手头上的科学问题提供了基本的核心，但它们很少在出版物中引用。

解决方案：通过为所有使用的库自动生成参考文献，这些项目和它们的作者将有机会获得充分的引用。

好处：充分欣赏科学软件开发。结合“首席女主角”问题的解决方案，更多的贡献将流向核心/基础项目，使新的方法学发展能够迅速地提供给更广泛的受众，而无需低质量科学软件的扩散。

类似/相关项目

sempervirens -- 一个收集开源科学软件匿名、自愿使用数据的实验原型。最终，在duecredit中，我们旨在提供类似的功能（因为我们也在收集此类信息）或仅仅与sempervirens接口/报告。

citepy -- 使用从它们的包仓库自动收集的信息轻松引用软件库。

当前使用情况

这是一个使用DueCredit的项目列表。如果您正在使用DueCredit或计划使用它，请考虑发送一个pull请求并将您的项目添加到这个列表中。感谢@fedorov的想法。

• PyMVPA
• fatiando
• Nipype
• QInfer
• shablona
• gfusion
• pybids
• Quickshear
• meqc
• MDAnalysis
• bctpy
• TorchIO
• BIDScoin

最后更新日期 2024-02-23。