How to cite specs

[magicDGS]

How can I cite the current specs?

For instance, SAM was defined in http://bioinformatics.oxfordjournals.org/cgi/doi/10.1093/bioinformatics/btp352, but the specifications have changed a lot since them. In addition, the SAM tags definitions are also in active development.

Thanks in advance!

[michaelmhoffman]

A Digital Object Identifier (DOI) for GA4GH standards would be nice and would lend some extra stability to the process. I'm not sure what is involved in minting one's own or getting someone else to mint them for GA4GH. Another option would be to deposit them at Zenodo.

[jkbonfield]

I think this is something to push upstream to GA4GH coordinators as we should have the same mechanism available to all published documents.

I like the DOI approach (or DOI plus something else).

[susanfairley]

Agree with @jkbonfield and @michaelmhoffman. I can see why a DOI approach would make sense and also having a consistent approach to our documents.

[jmarshall]

To summarise and expand on the discussion on slack: I think when we have discussed this issue in the past, the recommendation has been to cite the appropriate URL¹ and/or an appropriate paper such as one of these primordial papers.

To the extent that DOIs are useful identifiers for use in papers' lists of citations,² and to the extent that it is useful for papers to directly reference specification documents,³ it would be useful to mint DOIs for format and protocol specifications. it would be best to have a pan-GA4GH approach to this, so 👍 to addressing this via e.g. @ga4gh/TASC. I believe LSG has not done anything in this space to date; I wonder whether any other work streams have.

Options for GA4GH to investigate would appear to be:

1. Registering GA4GH as a DOI Registration Agency, hence presumably getting our own 10.nnnn prefix and allocating DOIs ourselves. (Probably not a particularly attractive approach, but it would be worth investigating what other similar standards organisations do w.r.t. DOIs. In fact, it appears that that really is the complete list of RAs, so presumably this is off the table and similar standards organisations to us operate instead as members of one or other of the consortia RAs, probably Crossref, if at all.)

2. Selecting an established RA to become a member of, and using their services to mint DOIs as appropriate. For example, as noted by @michaelmhoffman in the slack conversation, Crossref has been around for 20+ years, is a consortium of relevant looking academic societies and publishers, and has a line item for “Standards”.

   This does require a bit of thinking about. For example some of Crossref's membership obligations are somewhat onerous: e.g. in GA4GH's context, “use the DOI as the permanent link to the page” does not seem entirely appropriate.

   (Doing this involves spending money. At a glance: a little money for Crossref; rather more for DataCite.)

3. Depositing specification documents at e.g. Zenodo. However note that this would surely be depositing a copy of (a particular version of) a specification document; it does not provide a stable DOI referring to the canonical “SAM format” or “BED specification” or etc. Moreover IMHO this level of informality and dependence on a third party would be unbecoming for GA4GH.

4. Ensuring that there is always an up-to-date paper to be used as a proxy, instead of creating DOIs directly for formats and specifications. For example, GA4GH could write⁴ an annual survey article outlining its recent activities (similar perhaps to Ensembl 2021 et al) and/or work streams could aim to publish (brief) papers corresponding to new specifications or major additions to existing ones.

Another question to be investigated would be whether a direct DOI identifies e.g. “the SAM format” as a platonic ideal, or whether we would want to mint DOIs corresponding to particular versions of specifications. If the latter, note that “which editions of specifications are the important ones, and how do we refer to them (permanently)” is an ongoing discussion already and has different answers depending on how work streams have organised their work.

Footnotes

1. Yes, I'm glossing over some details here 😄 ↩

2. Fairly uncontroversially accepted, I think. ↩

3. More debatable IMHO. Using the 2009 paper as a proxy for “the SAM format” works pretty well in practice. ↩

4. And hopefully have the clout to get it published! ↩

[jmarshall]

The following also came up in the slack conversation:

Would you want to reference the doi in the bed file as a header?

IMHO DOIs would not add a lot of value in other contexts. In particular, there would not be any point in writing out a specification DOI in the headers of an e.g. BED file. A file can be determined to be a BED file by other means (perhaps via a magic number in future; today, by recognising the tabular data; via filename extension), so adding an explicit DOI as well as other BED-specific magic number headers wouldn't really add anything. One of the few similar things in other file formats would be XHMTL-style DTDs, which HTML5 has moved away from.

[jkbonfield]

I think this is actually two-fold: author credit and specification document linkage.

If we need to cite a specific version of a standard it ought to aleady be in the file headers (@HD VN:1.6, ##fileformat=VCFv4.3). If it's text in a paper, then referring to the version number should be sufficient. Some journals can be right pains in the neck though and refuse to accept a citation unless it's in their "recognised club". Although I've argued and been successful before in getting RFCs accepted as citations.

For standards with existing papers, the authors almost certainly want their work cited. So for SAM/BAM it's the original paper. For CRAM 3.0 and earlier it'd probably need to be the pre-CRAM EBI paper (Fritz et al) in lieu of anything better and for CRAM 3.1 it'd be my own paper. For BED I guess it's BEDtools. For VCF it'd be Petr's 2011 paper.

However those papers typically are for purposes of tracking author credit and aren't specifically citing the version of the standard being used by the file. Quite often they're way out of date too. Plus if we're looking at this from a credit perspective, often the people doing the legwork now aren't the same ones who originally published. Eg citations to the VCF spec don't give credit to any of the current specification maintainers.

At the very least each standard should probably come with a citation section outlining the preferred mechanism to cite it. This can include past papers, but also should recommend a modern citeable object where they substantially differ in authorship. We ought to lodge a new version every time there is a formal update to the specification version number.

One possibility is looking into protocols.io. I don't know if they specifically accept file formats or network protocols, but it does feel like a good fit to me and they have linkage within their protocols to other protocols, so this feels like a foundation level for them.

[michaelmhoffman]

There is a UCSC Genome Browser paper where BED is originally mentioned, which I treat as the canonical journal article reference for BED. We also describe the drafting of the GA4GH BED standard in the Acidbio paper so one could make a case for citing that too if you are using the GA4GH BED spec. There are a lot of advantages to using DOIs for a centralized authoritative reference to GA4GH specifications or other documents, without regard to the cultural role of DOIs in academic credit. It’s actually academic credit where thought of this, however—our faculty annual activity report asks for a list of documents (mostly journal articles) with a column for the document DOI. Having one would be very helpful here and in many other contexts. It would also be a lot easier to track citations to DOIs through existing mechanisms, whether they be scholarly citations or altmetrics.

[michaelmhoffman]

Structured CrossRef metadata may be useful to authoritatively record some of the things people are asking about in the GA4GH Connect session on Product Approval. cc @susanfairley

[susanfairley]

Raising this issue with TASC: ga4gh/TASC#39