Add DOI links and references section for cited papers?

[alexandreroutier]

Hello everyone,

When reading the specifications of the upcoming BIDS Derivatives, I noticed that several papers were cited.

I was wondering if adding DOI links e.g. (Tournier et al., 2007; Descoteaux et al. 2009) and a References section at the bottom of the page with full references e.g. :

• Tournier JD, Calamante F, Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: non-negativity constrained super-resolved spherical deconvolution. Neuroimage, 2007. 10.1016/j.neuroimage.2007.02.016 (example of formatting)
• etc.

could enrich the document? For diffusion MRI, on top of specifying the derivates, it also makes a very good entry point on what are the possibilities to process this modality.

Besides, I noticed some discrepancies when citing a paper e.g. :

• (Tournier et al. 2007; Descoteaux et al. 2009) or (Zhang et al. 2012, Daducci et al., 2015)
• Conturo, T. et al. (1999); Mori, S. et al. (1999) or Garyfallidis et al. (2010); Mori, S. et al. (1999)

Is there any consensus about it?

Currently, I think these questions and propositions involve:

• intracranial Electroencephalography (iEEG)
• Derivatives fMRI
• Derivatives Diffusion MRI

Best, Alexandre

PS : I take also this opportunity to congratulate you for these great specifications!

[sappelhoff]

I was wondering if adding DOI links e.g. (Tournier et al., 2007; Descoteaux et al. 2009) and a References section at the bottom of the page with full references could enrich the document?

Besides, I noticed some discrepancies when citing a paper ... Is there any consensus about it

Currently most (all?) references to academic or non-academic sources are in the form of a brief identifier and an embedded link. As you noted, the brief identifier such as "Tournier et al. 2007" currently has no consistent form across the spec.

I agree that it may be worthwhile to decide for a consistent form for at least all academic references and update the spec accordingly. Perhaps APA style?

Regarding a reference section at the end of each page, spelling out all mentioned references in full form, I think the only benefit for this would be a scenario where somebody prints the spec and then cannot access the link anymore.

However, our main formats are the html rendering, and soon a pdf (see https://github.com/bids-standard/bids-specification/pull/400), both of which will preserve links and render a reference section not very beneficial IMO.

I take also this opportunity to congratulate you for these great specifications!

Thanks - and thanks to you for contributing this issue!

[francopestilli]

@sappelhoff choosing a referencing style across the spec is a good idea.

[yarikoptic]

I would vote for it to be doi:thedoi (not a http url to it) where possible (so strongly RECOMMENDED), free text where impossible. Machines would be able to tell one from another and link doi appropriately or even provide bib, ris, etc, humans would be able to do whatever they want to do

[sappelhoff]

@yarikoptic why do you vote against something like https://doi.org/thedoi ?

[yarikoptic]

Because it is a specific identifier (DOI), not a URL which might (and did in the past from dx.doi.org) change. Different ID resolution or metadata services provide different additional info etc. Having said all that - such urls are often are understood and actual DOI is parsed out/used.

[sappelhoff]

just stumbled over this:

perhaps https://github.com/shyamd/mkdocs-bibtex/ can be used for generating a bibliography with mkdocs.

We'd also need the solution to work with our pdf rendering via pandoc.

[Remi-Gau]

Related to issue #403 and PR #629

[Remi-Gau]

just stumbled over this:

perhaps https://github.com/shyamd/mkdocs-bibtex/ can be used for generating a bibliography with mkdocs.

We'd also need the solution to work with our pdf rendering via pandoc.

Trying to do this in relation to #1660 I get the following error in the build in RTD.

RuntimeError: Pandoc died with exitcode "83" during conversion: Error running filter pandoc-citeproc:
Could not find executable pandoc-citeproc

Not sure but it seems this is due to an old version of pypandoc when installed via pip, but conda forge may have a more recent version

[Remi-Gau]

ok it does work when installing pypandoc from conda