Skip to content

Commit 5503760

Browse files
cthoytcthoyt
committed
Enable annotating contributor roles
1 parent e241d32 commit 5503760

File tree

12 files changed

+607
-4
lines changed

12 files changed

+607
-4
lines changed

‎.github/workflows/example-doc.yml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,16 @@ jobs:
1919
- name: Checkout
2020
uses: actions/checkout@v4
2121

22+
- name: Build docker
23+
run: |
24+
docker build -t inara:edgiest .
25+
2226
- name: Build draft PDF
2327
run: >-
2428
docker run \
2529
--volume "$(pwd):/data" \
2630
--user "$(id -u):$(id -g)" \
27-
openjournals/inara:latest \
31+
inara:edgiest \
2832
-o "jats,contextpdf,crossref,preprint,tex,pdf" example/paper.md
2933
3034
- name: Upload draft PDF
@@ -44,7 +48,7 @@ jobs:
4448
docker run \
4549
--volume "$(pwd):/data" \
4650
--user "$(id -u):$(id -g)" \
47-
openjournals/inara:latest \
51+
inara:edgiest \
4852
-o "jats,contextpdf,crossref,preprint,tex,pdf" -p example/paper.md
4953
5054
- name: Upload production PDF

‎CHANGELOG.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
## UNRELEASED
66

7-
- Fix bug in application of `prepare-affiliations.lua` filter (Charles Tapley Hoyt)
8-
- Fix a bug in the injection of `SOURCE_DATE_EPOCH` (https://github.com/openjournals/inara/pull/86) in tests
7+
- Support for annotating author roles with the Contribution Role Taxonomy (CRediT) (https://github.com/openjournals/inara/pull/87)
8+
- Fix a bug in the injection of `SOURCE_DATE_EPOCH` in tests (https://github.com/openjournals/inara/pull/86)
99
- Fix test files (https://github.com/openjournals/inara/pull/86, https://github.com/openjournals/inara/pull/85)
1010
- Switch testing to work on tex instead of pdf (https://github.com/openjournals/inara/pull/82)
1111
- Refactor testing folders (https://github.com/openjournals/inara/pull/84)

‎data/defaults/pdf.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ filters:
1111
path: self-citation.lua
1212
- type: lua
1313
path: fix-bibentry-spacing.lua
14+
- type: lua
15+
path: prepare-credit.lua
1416
variables:
1517
# styling options
1618
colorlinks: true

‎data/defaults/preprint.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
to: latex
22
output-file: paper.preprint.tex
33
template: preprint.latex
4+
filters:
5+
- type: lua
6+
path: prepare-credit.lua
47
variables:
58
# styling options
69
colorlinks: true

‎data/filters/prepare-credit.lua‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
-- Checks if any contributor information is available
2+
3+
roles = pandoc.List {
4+
"conceptualization",
5+
"data-curation",
6+
"formal-analysis",
7+
"funding-acquisition",
8+
"investigation",
9+
"methodology",
10+
"project-administration",
11+
"resources",
12+
"software",
13+
"supervision",
14+
"validation",
15+
"visualization",
16+
"writing-original-draft",
17+
"writing-review-editing"
18+
}
19+
20+
degrees = pandoc.List {
21+
"Lead",
22+
"Supporting",
23+
"Equal"
24+
}
25+
26+
function invalidRole(str)
27+
return not roles:includes(str)
28+
end
29+
30+
function invalidDegree(str)
31+
return not degrees:includes(str)
32+
end
33+
34+
function join_with_commas_and(list)
35+
local len = #list
36+
if len == 0 then
37+
return ""
38+
elseif len == 1 then
39+
return list[1]
40+
elseif len == 2 then
41+
return list[1] .. " and " .. list[2]
42+
else
43+
local result = table.concat(list, ", ", 1, len - 1)
44+
return result .. ", and " .. list[len]
45+
end
46+
end
47+
48+
function capitalize_first_letter(str)
49+
return str:sub(1, 1):upper() .. str:sub(2)
50+
end
51+
52+
function clean_role_dict(d)
53+
if d.type then
54+
return d
55+
else
56+
return {["type"] = pandoc.utils.stringify(d)}
57+
end
58+
end
59+
60+
local function prepare_credit (meta)
61+
meta.hasRoles = false
62+
for _, author in ipairs(meta.authors or {}) do
63+
if author.roles then
64+
roleList = {}
65+
for _, roleDict in ipairs(author.roles) do
66+
roleDict = clean_role_dict(roleDict)
67+
role = pandoc.utils.stringify(roleDict.type)
68+
if invalidRole(role) then
69+
print("invalid role for author " .. author.name .. ": " .. role)
70+
elseif roleDict.degree then
71+
degree = capitalize_first_letter(pandoc.utils.stringify(roleDict.degree))
72+
if invalidDegree(degree) then
73+
print("invalid degree for author " .. author.name .. ": " .. degree)
74+
-- even though the degree is invalid, add the role anyway
75+
table.insert(roleList, role)
76+
else
77+
table.insert(roleList, role .. " (" .. degree .. ")")
78+
end
79+
else
80+
table.insert(roleList, role)
81+
end
82+
end
83+
if #roleList > 0 then
84+
meta.hasRoles = true
85+
author.rolesString = join_with_commas_and(roleList)
86+
end
87+
end
88+
end
89+
return meta
90+
end
91+
92+
function Meta (meta)
93+
local ok, result = pcall(prepare_credit, meta)
94+
if ok then
95+
return result
96+
end
97+
end

‎data/templates/default.latex‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -557,6 +557,17 @@ $if(lof)$
557557
$endif$
558558
$body$
559559

560+
$if(hasRoles)$
561+
\section{Author Contributions}\label{author-contributions}
562+
\begin{enumerate}
563+
$for(authors)$
564+
$if(it.rolesString)$
565+
\item $it.name$ - $it.rolesString$
566+
$endif$
567+
$endfor$
568+
\end{enumerate}
569+
$endif$
570+
560571
$if(natbib)$
561572
$if(bibliography)$
562573
$if(biblio-title)$

‎data/templates/preprint.latex‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -438,6 +438,17 @@ $if(has-frontmatter)$
438438
$endif$
439439
$body$
440440

441+
$if(hasRoles)$
442+
\section{Author Contributions}\label{author-contributions}
443+
\begin{enumerate}
444+
$for(authors)$
445+
$if(it.rolesString)$
446+
\item $it.name$ - $it.rolesString$
447+
$endif$
448+
$endfor$
449+
\end{enumerate}
450+
$endif$
451+
441452
$if(has-frontmatter)$
442453
\backmatter
443454
$endif$

‎example/paper.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,27 @@ authors:
77
affiliation: "1, 2, 4"
88
orcid: 0000-0002-9455-0796
99
corresponding: true
10+
roles:
11+
- type: software
12+
degree: equal
13+
- 'methodology'
1014
- name: Juanjo Bazán
1115
orcid: 0000-0001-7699-3983
1216
affiliation: [1]
1317
equal-contrib: true
18+
roles:
19+
- type: software
20+
degree: equal
1421
- name: Arfon M. Smith
1522
orcid: 0000-0002-3957-2474
1623
affiliation: [1, 3]
1724
equal-contrib: true
25+
roles:
26+
- type: software
27+
degree: equal
28+
- type: supervision
29+
degree: lead
30+
1831
affiliations:
1932
- index: 1
2033
name: Open Journals
@@ -365,6 +378,72 @@ authors:
365378
<!-- given-names: 瀧 -->
366379
<!-- surname: 立花 -->
367380

381+
## Contributor Roles
382+
383+
The [Contribution Role Taxonomy (CRediT)](https://credit.niso.org/contributor-roles) defines
384+
fourteen standard roles of authors. Each author can be annotated with one or more contribution
385+
roles.
386+
387+
1. [conceptualization](https://credit.niso.org/contributor-roles/conceptualization)
388+
2. [data-curation](https://credit.niso.org/contributor-roles/data-curation)
389+
3. [formal-analysis](https://credit.niso.org/contributor-roles/formal-analysis)
390+
4. [funding-acquisition](https://credit.niso.org/contributor-roles/funding-acquisition)
391+
5. [investigation](https://credit.niso.org/contributor-roles/investigation)
392+
6. [methodology](https://credit.niso.org/contributor-roles/methodology)
393+
7. [project-administration](https://credit.niso.org/contributor-roles/project-administration)
394+
8. [resources](https://credit.niso.org/contributor-roles/resources)
395+
9. [software](https://credit.niso.org/contributor-roles/software)
396+
10. [supervision](https://credit.niso.org/contributor-roles/supervision)
397+
11. [validation](https://credit.niso.org/contributor-roles/validation)
398+
12. [visualization](https://credit.niso.org/contributor-roles/visualization)
399+
13. [writing-original-draft](https://credit.niso.org/contributor-roles/writing-original-draft)
400+
14. [writing-review-editing](https://credit.niso.org/contributor-roles/writing-review-editing)
401+
402+
JATS also specifies three degrees which can be used to quantify the impact of a contribution:
403+
404+
1. `Lead`
405+
2. `Supporting`
406+
3. `Equal` - for use if multiple equivalent leads
407+
408+
Together, these can be used to identify which authors materially contributed to the paper,
409+
such as through `formal-analysis` or `data-curation` and which authors contributed immaterially,
410+
such as through `supervision`. It also allows for saying if multiple people made the same
411+
kind of contribution, who took the lead.
412+
413+
```yaml
414+
authors:
415+
- name: John Doe
416+
affiliation: [ 1 ]
417+
roles:
418+
- type: 'formal-analysis'
419+
degree: 'lead'
420+
421+
- name: John Boss
422+
affiliation: [ 1 ]
423+
roles:
424+
- type: 'funding-acquisition'
425+
degree: 'lead'
426+
- type: 'supervision'
427+
degree: 'lead'
428+
```
429+
430+
Roles are optional, and within roles, degrees are optional. It's possible to shorthand
431+
roles by using strings directly:
432+
433+
```yaml
434+
authors:
435+
- name: John Doe
436+
affiliation: [ 1 ]
437+
roles:
438+
- 'formal-analysis'
439+
440+
- name: John Boss
441+
affiliation: [ 1 ]
442+
roles:
443+
- 'funding-acquisition'
444+
- 'supervision'
445+
```
446+
368447
## Affiliations
369448

370449
Each affiliation requires an `index` and `name`.

‎test/expected-draft/paper.jats/paper.jats‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,6 +520,106 @@ Software should use an OSI-approved license.
520520
<p> </p>
521521
</sec>
522522
</sec>
523+
<sec id="contributor-roles">
524+
<title>Contributor Roles</title>
525+
<p>The
526+
<ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles">Contribution
527+
Role Taxonomy (CRediT)</ext-link> defines fourteen standard roles of
528+
authors. Each author can be annotated with one or more contribution
529+
roles.</p>
530+
<list list-type="order">
531+
<list-item>
532+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/conceptualization">conceptualization</ext-link></p>
533+
</list-item>
534+
<list-item>
535+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/data-curation">data-curation</ext-link></p>
536+
</list-item>
537+
<list-item>
538+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/formal-analysis">formal-analysis</ext-link></p>
539+
</list-item>
540+
<list-item>
541+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/funding-acquisition">funding-acquisition</ext-link></p>
542+
</list-item>
543+
<list-item>
544+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/investigation">investigation</ext-link></p>
545+
</list-item>
546+
<list-item>
547+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/methodology">methodology</ext-link></p>
548+
</list-item>
549+
<list-item>
550+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/project-administration">project-administration</ext-link></p>
551+
</list-item>
552+
<list-item>
553+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/resources">resources</ext-link></p>
554+
</list-item>
555+
<list-item>
556+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/software">software</ext-link></p>
557+
</list-item>
558+
<list-item>
559+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/supervision">supervision</ext-link></p>
560+
</list-item>
561+
<list-item>
562+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/validation">validation</ext-link></p>
563+
</list-item>
564+
<list-item>
565+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/visualization">visualization</ext-link></p>
566+
</list-item>
567+
<list-item>
568+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/writing-original-draft">writing-original-draft</ext-link></p>
569+
</list-item>
570+
<list-item>
571+
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/writing-review-editing">writing-review-editing</ext-link></p>
572+
</list-item>
573+
</list>
574+
<p>JATS also specifies three degrees which can be used to quantify
575+
the impact of a contribution:</p>
576+
<list list-type="order">
577+
<list-item>
578+
<p><monospace>Lead</monospace></p>
579+
</list-item>
580+
<list-item>
581+
<p><monospace>Supporting</monospace></p>
582+
</list-item>
583+
<list-item>
584+
<p><monospace>Equal</monospace> - for use if multiple equivalent
585+
leads</p>
586+
</list-item>
587+
</list>
588+
<p>Together, these can be used to identify which authors materially
589+
contributed to the paper, such as through
590+
<monospace>formal-analysis</monospace> or
591+
<monospace>data-curation</monospace> and which authors contributed
592+
immaterially, such as through <monospace>supervision</monospace>. It
593+
also allows for saying if multiple people made the same kind of
594+
contribution, who took the lead.</p>
595+
<code language="yaml">authors:
596+
- name: John Doe
597+
affiliation: [ 1 ]
598+
roles:
599+
- type: 'formal-analysis'
600+
degree: 'lead'
601+
602+
- name: John Boss
603+
affiliation: [ 1 ]
604+
roles:
605+
- type: 'funding-acquisition'
606+
degree: 'lead'
607+
- type: 'supervision'
608+
degree: 'lead'</code>
609+
<p>Roles are optional, and within roles, degrees are optional. It’s
610+
possible to shorthand roles by using strings directly:</p>
611+
<code language="yaml">authors:
612+
- name: John Doe
613+
affiliation: [ 1 ]
614+
roles:
615+
- 'formal-analysis'
616+
617+
- name: John Boss
618+
affiliation: [ 1 ]
619+
roles:
620+
- 'funding-acquisition'
621+
- 'supervision'</code>
622+
</sec>
523623
<sec id="affiliations">
524624
<title>Affiliations</title>
525625
<p>Each affiliation requires an <monospace>index</monospace> and

0 commit comments

Comments
 (0)