Skip to content

Commit

Permalink
Enable annotating contributor roles
Browse files Browse the repository at this point in the history
  • Loading branch information
cthoyt committed Sep 19, 2024
1 parent e241d32 commit 5503760
Show file tree
Hide file tree
Showing 12 changed files with 607 additions and 4 deletions.
8 changes: 6 additions & 2 deletions .github/workflows/example-doc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,16 @@ jobs:
- name: Checkout
uses: actions/checkout@v4

- name: Build docker
run: |
docker build -t inara:edgiest .
- name: Build draft PDF
run: >-
docker run \
--volume "$(pwd):/data" \
--user "$(id -u):$(id -g)" \
openjournals/inara:latest \
inara:edgiest \
-o "jats,contextpdf,crossref,preprint,tex,pdf" example/paper.md
- name: Upload draft PDF
Expand All @@ -44,7 +48,7 @@ jobs:
docker run \
--volume "$(pwd):/data" \
--user "$(id -u):$(id -g)" \
openjournals/inara:latest \
inara:edgiest \
-o "jats,contextpdf,crossref,preprint,tex,pdf" -p example/paper.md
- name: Upload production PDF
Expand Down
4 changes: 2 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

## UNRELEASED

- Fix bug in application of `prepare-affiliations.lua` filter (Charles Tapley Hoyt)
- Fix a bug in the injection of `SOURCE_DATE_EPOCH` (https://github.com/openjournals/inara/pull/86) in tests
- Support for annotating author roles with the Contribution Role Taxonomy (CRediT) (https://github.com/openjournals/inara/pull/87)
- Fix a bug in the injection of `SOURCE_DATE_EPOCH` in tests (https://github.com/openjournals/inara/pull/86)
- Fix test files (https://github.com/openjournals/inara/pull/86, https://github.com/openjournals/inara/pull/85)
- Switch testing to work on tex instead of pdf (https://github.com/openjournals/inara/pull/82)
- Refactor testing folders (https://github.com/openjournals/inara/pull/84)
Expand Down
2 changes: 2 additions & 0 deletions data/defaults/pdf.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ filters:
path: self-citation.lua
- type: lua
path: fix-bibentry-spacing.lua
- type: lua
path: prepare-credit.lua
variables:
# styling options
colorlinks: true
Expand Down
3 changes: 3 additions & 0 deletions data/defaults/preprint.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
to: latex
output-file: paper.preprint.tex
template: preprint.latex
filters:
- type: lua
path: prepare-credit.lua
variables:
# styling options
colorlinks: true
Expand Down
97 changes: 97 additions & 0 deletions data/filters/prepare-credit.lua
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
-- Checks if any contributor information is available

roles = pandoc.List {
"conceptualization",
"data-curation",
"formal-analysis",
"funding-acquisition",
"investigation",
"methodology",
"project-administration",
"resources",
"software",
"supervision",
"validation",
"visualization",
"writing-original-draft",
"writing-review-editing"
}

degrees = pandoc.List {
"Lead",
"Supporting",
"Equal"
}

function invalidRole(str)
return not roles:includes(str)
end

function invalidDegree(str)
return not degrees:includes(str)
end

function join_with_commas_and(list)
local len = #list
if len == 0 then
return ""
elseif len == 1 then
return list[1]
elseif len == 2 then
return list[1] .. " and " .. list[2]
else
local result = table.concat(list, ", ", 1, len - 1)
return result .. ", and " .. list[len]
end
end

function capitalize_first_letter(str)
return str:sub(1, 1):upper() .. str:sub(2)
end

function clean_role_dict(d)
if d.type then
return d
else
return {["type"] = pandoc.utils.stringify(d)}
end
end

local function prepare_credit (meta)
meta.hasRoles = false
for _, author in ipairs(meta.authors or {}) do
if author.roles then
roleList = {}
for _, roleDict in ipairs(author.roles) do
roleDict = clean_role_dict(roleDict)
role = pandoc.utils.stringify(roleDict.type)
if invalidRole(role) then
print("invalid role for author " .. author.name .. ": " .. role)
elseif roleDict.degree then
degree = capitalize_first_letter(pandoc.utils.stringify(roleDict.degree))
if invalidDegree(degree) then
print("invalid degree for author " .. author.name .. ": " .. degree)
-- even though the degree is invalid, add the role anyway
table.insert(roleList, role)
else
table.insert(roleList, role .. " (" .. degree .. ")")
end
else
table.insert(roleList, role)
end
end
if #roleList > 0 then
meta.hasRoles = true
author.rolesString = join_with_commas_and(roleList)
end
end
end
return meta
end

function Meta (meta)
local ok, result = pcall(prepare_credit, meta)
if ok then
return result
end
end
11 changes: 11 additions & 0 deletions data/templates/default.latex
Original file line number Diff line number Diff line change
Expand Up @@ -557,6 +557,17 @@ $if(lof)$
$endif$
$body$

$if(hasRoles)$
\section{Author Contributions}\label{author-contributions}
\begin{enumerate}
$for(authors)$
$if(it.rolesString)$
\item $it.name$ - $it.rolesString$
$endif$
$endfor$
\end{enumerate}
$endif$

$if(natbib)$
$if(bibliography)$
$if(biblio-title)$
Expand Down
11 changes: 11 additions & 0 deletions data/templates/preprint.latex
Original file line number Diff line number Diff line change
Expand Up @@ -438,6 +438,17 @@ $if(has-frontmatter)$
$endif$
$body$

$if(hasRoles)$
\section{Author Contributions}\label{author-contributions}
\begin{enumerate}
$for(authors)$
$if(it.rolesString)$
\item $it.name$ - $it.rolesString$
$endif$
$endfor$
\end{enumerate}
$endif$

$if(has-frontmatter)$
\backmatter
$endif$
Expand Down
79 changes: 79 additions & 0 deletions example/paper.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,27 @@ authors:
affiliation: "1, 2, 4"
orcid: 0000-0002-9455-0796
corresponding: true
roles:
- type: software
degree: equal
- 'methodology'
- name: Juanjo Bazán
orcid: 0000-0001-7699-3983
affiliation: [1]
equal-contrib: true
roles:
- type: software
degree: equal
- name: Arfon M. Smith
orcid: 0000-0002-3957-2474
affiliation: [1, 3]
equal-contrib: true
roles:
- type: software
degree: equal
- type: supervision
degree: lead

affiliations:
- index: 1
name: Open Journals
Expand Down Expand Up @@ -365,6 +378,72 @@ authors:
<!-- given-names: 瀧 -->
<!-- surname: 立花 -->

## Contributor Roles

The [Contribution Role Taxonomy (CRediT)](https://credit.niso.org/contributor-roles) defines
fourteen standard roles of authors. Each author can be annotated with one or more contribution
roles.

1. [conceptualization](https://credit.niso.org/contributor-roles/conceptualization)
2. [data-curation](https://credit.niso.org/contributor-roles/data-curation)
3. [formal-analysis](https://credit.niso.org/contributor-roles/formal-analysis)
4. [funding-acquisition](https://credit.niso.org/contributor-roles/funding-acquisition)
5. [investigation](https://credit.niso.org/contributor-roles/investigation)
6. [methodology](https://credit.niso.org/contributor-roles/methodology)
7. [project-administration](https://credit.niso.org/contributor-roles/project-administration)
8. [resources](https://credit.niso.org/contributor-roles/resources)
9. [software](https://credit.niso.org/contributor-roles/software)
10. [supervision](https://credit.niso.org/contributor-roles/supervision)
11. [validation](https://credit.niso.org/contributor-roles/validation)
12. [visualization](https://credit.niso.org/contributor-roles/visualization)
13. [writing-original-draft](https://credit.niso.org/contributor-roles/writing-original-draft)
14. [writing-review-editing](https://credit.niso.org/contributor-roles/writing-review-editing)

JATS also specifies three degrees which can be used to quantify the impact of a contribution:

1. `Lead`
2. `Supporting`
3. `Equal` - for use if multiple equivalent leads

Together, these can be used to identify which authors materially contributed to the paper,
such as through `formal-analysis` or `data-curation` and which authors contributed immaterially,
such as through `supervision`. It also allows for saying if multiple people made the same
kind of contribution, who took the lead.

```yaml
authors:
- name: John Doe
affiliation: [ 1 ]
roles:
- type: 'formal-analysis'
degree: 'lead'
- name: John Boss
affiliation: [ 1 ]
roles:
- type: 'funding-acquisition'
degree: 'lead'
- type: 'supervision'
degree: 'lead'
```

Roles are optional, and within roles, degrees are optional. It's possible to shorthand
roles by using strings directly:

```yaml
authors:
- name: John Doe
affiliation: [ 1 ]
roles:
- 'formal-analysis'
- name: John Boss
affiliation: [ 1 ]
roles:
- 'funding-acquisition'
- 'supervision'
```

## Affiliations

Each affiliation requires an `index` and `name`.
Expand Down
100 changes: 100 additions & 0 deletions test/expected-draft/paper.jats/paper.jats
Original file line number Diff line number Diff line change
Expand Up @@ -520,6 +520,106 @@ Software should use an OSI-approved license.
<p> </p>
</sec>
</sec>
<sec id="contributor-roles">
<title>Contributor Roles</title>
<p>The
<ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles">Contribution
Role Taxonomy (CRediT)</ext-link> defines fourteen standard roles of
authors. Each author can be annotated with one or more contribution
roles.</p>
<list list-type="order">
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/conceptualization">conceptualization</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/data-curation">data-curation</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/formal-analysis">formal-analysis</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/funding-acquisition">funding-acquisition</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/investigation">investigation</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/methodology">methodology</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/project-administration">project-administration</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/resources">resources</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/software">software</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/supervision">supervision</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/validation">validation</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/visualization">visualization</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/writing-original-draft">writing-original-draft</ext-link></p>
</list-item>
<list-item>
<p><ext-link ext-link-type="uri" xlink:href="https://credit.niso.org/contributor-roles/writing-review-editing">writing-review-editing</ext-link></p>
</list-item>
</list>
<p>JATS also specifies three degrees which can be used to quantify
the impact of a contribution:</p>
<list list-type="order">
<list-item>
<p><monospace>Lead</monospace></p>
</list-item>
<list-item>
<p><monospace>Supporting</monospace></p>
</list-item>
<list-item>
<p><monospace>Equal</monospace> - for use if multiple equivalent
leads</p>
</list-item>
</list>
<p>Together, these can be used to identify which authors materially
contributed to the paper, such as through
<monospace>formal-analysis</monospace> or
<monospace>data-curation</monospace> and which authors contributed
immaterially, such as through <monospace>supervision</monospace>. It
also allows for saying if multiple people made the same kind of
contribution, who took the lead.</p>
<code language="yaml">authors:
- name: John Doe
affiliation: [ 1 ]
roles:
- type: 'formal-analysis'
degree: 'lead'

- name: John Boss
affiliation: [ 1 ]
roles:
- type: 'funding-acquisition'
degree: 'lead'
- type: 'supervision'
degree: 'lead'</code>
<p>Roles are optional, and within roles, degrees are optional. It’s
possible to shorthand roles by using strings directly:</p>
<code language="yaml">authors:
- name: John Doe
affiliation: [ 1 ]
roles:
- 'formal-analysis'

- name: John Boss
affiliation: [ 1 ]
roles:
- 'funding-acquisition'
- 'supervision'</code>
</sec>
<sec id="affiliations">
<title>Affiliations</title>
<p>Each affiliation requires an <monospace>index</monospace> and
Expand Down
Loading

0 comments on commit 5503760

Please sign in to comment.