Better description of authorship

[kstenio]

In the paper, it is mentioned several (8) authors (including @b-pardi), but when it comes to the commits, you are the only contributor to the code.

Since the theme of the software is very specialized, I understand that maybe all those authors helped somehow in the software development, writing a piece of code or helping in the development in another manner. However I find very odd the statement that someone who did not uploaded any of the software's code to have contributed equally in its development (e.g. Syeda Ahmed).

In order to avoid misinterpretation, I recommend adding a proper "Author contributions" section before the Acknowledgments. You can follow the CRediT (Contributor Roles Taxonomy) guidelines for support.

---

If it helps, I did a while ago a very simple script that reads a xlsx file and creates the Author contributions paragraph:

import pandas as pd

def main(args):
    df = pd.read_excel('credit_matrix.xlsx', index_col=0, dtype=bool)
    paragraph = ''
    for cred in df.index:
        row = ''
        for auth in df.columns:
            if df.loc[cred, auth]:
                row += f' {auth},'
        paragraph += f'{cred}:{row[:-1]}; '
    with open('credit.txt', 'w') as cr:
        cr.write(paragraph[:-2]+'.')
    print(paragraph[:-2]+'.')
    return 0

if __name__ == '__main__':
    import sys
    sys.exit(main(sys.argv))

Where the credit_matrix.xlsx file is structured in the following manner:

CRediT	A. A.	A. B.	A. C.	A. D.
Conceptualization	1	1	0	1
data curation	1	1	0	0
formal analysis	1	1	1	1
funding acquisition	0	0	0	1
investigation	1	1	0	0
methodology	1	1	1	1
project administration	1	0	0	1
resources	0	0	0	1
software	1	1	0	0
supervision	0	0	0	1
validation	1	1	1	1
visualization	1	1	1	0
writing – original draft	1	1	0	0
writing – review & editing	1	1	1	1

So, you can put in columns the initials of authors (A. A. == Author A, etc.), and a boolean for the contribution. Run the script, and it will create a credit.txt file with the proper data for you. :+1:

[b-pardi]

That's super helpful thank you!

There is only one piece of the project that was written by someone else, JM Friedt. He wrote the raw QSD file formatting bit manipulation code, everything else was me. And he emailed it to me unprompted which is why he hasn't actually committed anything lol, but with his permission and an offer of co authorship he was happy to have his code in the project.

As for Syeda Ahmed, you have a good point. Her contribution was data curation, and it was my PI's idea to give her equal contrib for that reason, but that is probably something I should discuss with him. I will have this updated as soon as I can meet with my PI and discuss contributions, thanks!

[kstenio]

Authorship and acknowledgement are very important in papers. Everyone involved wants proper credit, and to me the Credit guidelines are a great help!

You are right in talking with your PI before any commits, no problem.

Also, by convention, the PI name is the last.

[b-pardi]

Met with my PI this morning and established authorship credits. Thank you again!

[kstenio]

Hello! @b-pardi , I was looking into the paper and did not found the Author contributions section, and then realized: you added the TXT file into the repository. Sorry not explaining properly. :sweat_smile:

The script above is just a helper; the section is supposed to be in the paper, prior to Acknowledgements section, like this one:

Just include the content of the credit.txt file into paper.bib, for example:

(...) and crystal thickness. This tool is key for efficient data analysis in preference over laborious spreadsheet evaluation.

# Author contributions

Conceptualization: Brandon Pardi, Syeda Tajin Ahmed, Roberto C. Andresen Eguiluz; data curation: Syeda Tajin Ahmed, Silvia Jonguitud Flores, Warren Flores, Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz; formal analysis: Brandon Pardi, Syeda Tajin Ahmed, Jean-Michel Friedt, Laura L.E. Mears, Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz; funding acquisition: Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz; investigation: Brandon Pardi, Syeda Tajin Ahmed, Roberto C. Andresen Eguiluz; methodology: Brandon Pardi, Syeda Tajin Ahmed, Jean-Michel Friedt, Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz; project administration: Brandon Pardi, Roberto C. Andresen Eguiluz; resources: Brandon Pardi, Syeda Tajin Ahmed, Laura L.E. Mears, Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz; software: Brandon Pardi, Jean-Michel Friedt; supervision: Brandon Pardi, Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz; validation: Brandon Pardi, Syeda Tajin Ahmed, Silvia Jonguitud Flores, Warren Flores, Jean-Michel Friedt, Laura L.E. Mears, Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz; visualization: Brandon Pardi, Syeda Tajin Ahmed, Laura L.E. Mears, Roberto C. Andresen Eguiluz; writing - original draft: Brandon Pardi, Syeda Tajin Ahmed, Silvia Jonguitud Flores, Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz; writing - review & editing: Brandon Pardi, Syeda Tajin Ahmed, Silvia Jonguitud Flores, Laura L.E. Mears, Bernardo Yáñez Soto, Roberto C. Andresen Eguiluz.

# Acknowledgements

R.C.A.E. acknowledges funding from the NSF-CREST: Center for Cellular and Biomolecular Machines through the support of the National Science Foundation (NSF) Grant No. NSF-HRD-1547848. R.C.A.E. and B.P. acknowledge funding from the CAREER grant NSF CMMI Grant No. #2239665 awarded to R.C.A.E. 

# Supporting information
The authors have compiled additional (...)

Finally, I have three extra recommendations (non mandatory):

1. Do you prefer the full name in Author contributions? I believe just initials are sufficient;
2. It is usual in papers adding a Conflict of interest section. The example above is fine;
3. The --- separating the sections feels odd to me when reading the PDF, but it is up to you.

[b-pardi]

@kstenio you know it makes a lot more sense now that you mention that 😆 Should be taken care of. For the other issues I think I prefer contributions be full names personally, so I don't need to keep scrolling up to the author list in the beginning and figure out who has what initials. The rest of the points you made are solid and I corrected those as well

[kstenio]

Nice! The latest paper artifact is great! :smiley: