search

elifesciences / schematron-wiki

This contains the markdown from gitbook for schematron.
MIT License
2 stars 0 forks source link

Create Additional files page #41

Closed naushinthomson closed 3 years ago

naushinthomson commented 4 years ago

Definition of done

JGilbert-eLife commented 3 years ago

@bcollins14 @griffithsc @FAtherden-eLife @Melissa37 @naushinthomson - Please could you take a look at the additional files page and let me know what you think? I think I've covered everything, but there might be stuff I need to expand or illustrate.

https://app.gitbook.com/@elifesciences/s/productionhowto/article-details/content/allowed-assets/additional-files

Thanks!

Melissa37 commented 3 years ago

Asset- and article-level source files, supplementary files and other additional filess

Need to remove extra s :-)

Melissa37 commented 3 years ago

Audio files

Are they explicitly not allowed as children of fig/table/video? If not why? Might be worth explaining

Melissa37 commented 3 years ago

At present, eLife cannot support inline audio-only playback so audio files (as distinct from videos) should be included as additional files. These are treated in all respects like Supplementary files, but are labelled as as Audio file 1, Audio file 2, etc.

Need to remove second "as"

Melissa37 commented 3 years ago

Source data and source code may be provided to aloow readers access to the raw data and any scripts

typo - allow

Melissa37 commented 3 years ago

Source files (asset-level

Missing end bracket

Melissa37 commented 3 years ago

The source data will usually consist of tables of raw data but may also include unprocessed images, editable version of charts provided as flat images, or multiple-page documents that cannot be typeset as single figures/figure supplements

Does "editable version of charts provided as flat images" refer to content provided as a figure? This could be clearer

fred-atherden commented 3 years ago

Is it worth including an example of a suitable reporting standards file? In the past we've had files come through labelled as reporting standards, which actually didn't need to be included (validation report from data uploaded to a repo for example), so it would be good to cover that as well, if possible.

fred-atherden commented 3 years ago

It's implied in the language (XXX should have a title/legend), and in the actions, but perhaps worth expanding somewhere above the Schematron rules that while it's highly preferred/recommended, we can publish additional files without titles/legends.

fred-atherden commented 3 years ago

supplementary-material-test-6

Is it worth adding a link to the allowed assets page in the action, to point the user to a list of permitted labels?

fred-atherden commented 3 years ago

Is this page where we should cover the Schematron checks for additional file titles?

supplementary-material-title-test-1 - supplementary-material-title-test-8.

fred-atherden commented 3 years ago

Think we should include supplementary-material-child-conformance here too.

Nice work James, thanks.

Melissa37 commented 3 years ago

Asset-level source files may accompany figures, videos and tables in an appendix as well as those in the main text. Schema and Chemical structures, however, cannot support associated source files.

I am not sure I understand this. Can you explain at the production meeting?

Melissa37 commented 3 years ago

To facilitate the interpretation and replication of experiments, authors are asked during full submission to provide information relating to sample-size estimation, replicates, and statistical reporting.

There is an Oxford comma here, but it's not used elsewhere

Melissa37 commented 3 years ago

Transparent reporting form To facilitate the interpretation and replication of experiments, authors are asked during full submission to provide information relating to sample-size estimation, replicates, and statistical reporting. They are then encouraged to fill out a template form (available as a PDF or a Word file) describing the places within their article where this information has been included. This transparent reporting form will be published alongside the final version of record. It is important to note that while TRFs accompany most articles, they are not mandatory. If, for example, an article does not describe experiments or the analysis of data (as might be the case in a Tools and Resources submission), the form would not be needed. Transparent reporting forms do not require a title or legend and are published at the end of the Additional files section.

Transparent reporting forms then TRF then Transparent reporting forms again. Might be worth defining, using the abbreviation and then using it thereafter. I think its useful to use the abbreviation somewhere as that is used and might be a way for someone to look up what it is

Melissa37 commented 3 years ago

As indicated by the relevant schematron tests, asset-level source data and code should be relate directly

related, not relate

Melissa37 commented 3 years ago

The details from the orphaned legend can then be added that asset's own legend

added to that...?

Melissa37 commented 3 years ago

Occasionally, authors will provide a LaTex (.tex) file as an additional file, under the assumption that we will typeset it for them. If they do so, they must be asked to provide a PDF version of this file so that it will be available in an easy-to-read format for publication. We noticed that you have provided a .tex file as an additional file. Please could you provide a typeset PDF version of this file that we can use for final publication?

I don't understand this, can you explain in the prod meeting?

Melissa37 commented 3 years ago

In these cases, there is unfortunately little we can do beyond making sure the files to not have an arbitrarily low size (e.g. in the range of bytes rather than at least kilobytes).

to should be do?

Melissa37 commented 3 years ago

Key Resources table schematron messages - suggest we mention KRTs here as they can sometimes remain as suppl files when they should be changed to appendices if not at the start of the methods?

Melissa37 commented 3 years ago

Action: This warning indicates at the pre-author stage that no file is present for an additional file entry. The author should be queried to provide the missing document. Please provide the file for this source data. Please provide the file for this source code. Please provide the file for this supplementary file. Please provide the file for this reporting standard

Suggest adding line, indicating the most appropriate of the options should be added as a query to author

Melissa37 commented 3 years ago

final-supplementary-material-test-5 Error: XXXXXX is missing a file (supplementary-material must have a media). Action: This errors indicates no fil

This error (remove s)

Melissa37 commented 3 years ago

source-code-test-1 Warning: XXXXXX has a file which looks like code - XXXXXX, but it's not labelled as code. Action: This warning indicates that an additional file has an extension that may indicate it is source code rather than, for example, data. It currently checks for the following extensions: .m, .py, .lib, .jl, .c, .sh, .for, .cpproj, .ipynb, .mph, .cc, .rmd, .nlogo, .stan, .wrl, .pl, .r, .fas, .ijm, .llb, .ipf, .mdl, .h. If the title and/or legend does not clearly indicate that the file contains data alone, please query the author as to whether it should be changed to source code. Should this file be labelled as source code?

Does this actually ever fire, if source code is always zipped up?

Melissa37 commented 3 years ago

supplementary-material-test-7 Error: supplementary-material in additional files sections cannot have the a media element with the attribute mimetype='video'. This should be mimetype='application'

Is there a typo in this "the a"

This is a repeat issues below

Melissa37 commented 3 years ago

back-supplementary-file-position Error: XXXXXX id ends with XXXXXX, but it is placed XXXXXX. Either it is mislabelled, the id is incorrect, or it should be moved to a different position. Action: This error indicates the labelling for a supplementary file does not match the sequence in which the other files of that type have been placed. And example would be Supplementary file 1,

An example, not And example

This is a repeat issues below

Melissa37 commented 3 years ago

back-supplementary-file-id Error: The id (XXXXXX) for XXXXXX is not in the correct format. Supplementary files need to have ids in the format 'supp0'. Action: This error indicates a supplementary file has an ID that does not confirm to the standard format 'supp0'. T

conform to?

This is a repeat issues below

JGilbert-eLife commented 3 years ago

source-code-test-1 Warning: XXXXXX has a file which looks like code - XXXXXX, but it's not labelled as code. Action: This warning indicates that an additional file has an extension that may indicate it is source code rather than, for example, data. It currently checks for the following extensions: .m, .py, .lib, .jl, .c, .sh, .for, .cpproj, .ipynb, .mph, .cc, .rmd, .nlogo, .stan, .wrl, .pl, .r, .fas, .ijm, .llb, .ipf, .mdl, .h. If the title and/or legend does not clearly indicate that the file contains data alone, please query the author as to whether it should be changed to source code. Should this file be labelled as source code?

Does this actually ever fire, if source code is always zipped up?

Doesn't fire on code, fires on other files that might be code. I did a double take on this too!

JGilbert-eLife commented 3 years ago

Is this page where we should cover the Schematron checks for additional file titles?

supplementary-material-title-test-1 - supplementary-material-title-test-8.

Argh - must have stopped searching prematurely. Sorry, will get those and the other one added in.

Melissa37 commented 3 years ago

supplementary-material-child-conformance supplementary-material/* Error: XXXXXX is not allowed as a child of supplementary-material.

I am a bit confused by this at the end

Melissa37 commented 3 years ago

Great work, thanks James!

Melissa37 commented 3 years ago

source-code-test-1 Warning: XXXXXX has a file which looks like code - XXXXXX, but it's not labelled as code. Action: This warning indicates that an additional file has an extension that may indicate it is source code rather than, for example, data. It currently checks for the following extensions: .m, .py, .lib, .jl, .c, .sh, .for, .cpproj, .ipynb, .mph, .cc, .rmd, .nlogo, .stan, .wrl, .pl, .r, .fas, .ijm, .llb, .ipf, .mdl, .h. If the title and/or legend does not clearly indicate that the file contains data alone, please query the author as to whether it should be changed to source code. Should this file be labelled as source code?

Does this actually ever fire, if source code is always zipped up?

Doesn't fire on code, fires on other files that might be code. I did a double take on this too!

Ahhh, good point! I guess reading this with an example in front of you it would be obvious, reading it alone it's a double-take! Thanks!!

griffithsc commented 3 years ago

At present, eLife cannot support inline audio-only playback so audio files (as distinct from videos) should be included as additional files. Pretty sure I know what this means, but could you be clearer about what you mean by inline here?

griffithsc commented 3 years ago

This should be done by downloading the file from the proof (or staged article) and seeing if there are any issues when it is opened in the appropriate program. Not sure what staged article means, could you clarify this?

griffithsc commented 3 years ago

This should definitely be checked after the article is loaded to the journal website as conversions may occur at this stage. In the unlikely event that it appears the creation of the final package is responsible for the corruption of a file, the content processors should be advised and requested to resolve the issue. I wasn't sure who you meant by content processors, could you clarify this?

griffithsc commented 3 years ago

Otherwise this is great - really comprehensive - thank you James!

NuclearRedeye commented 3 years ago

@JGilbert-eLife Just before I take a look at this, was I assigned to this by mistake or was there something you need my input on?

fred-atherden commented 3 years ago

Think it was a mistake @NuclearRedeye! Feel free to ignore.

fred-atherden commented 3 years ago

After doing a Pub check on Kriya 2 I realised we don't have robust enough tests on labelling for asset level source data/code.

I've added the following tests which (I presume) will also need covering on this page:

Sorry for the inconvenience.

JGilbert-eLife commented 3 years ago

No problem @FAtherden-eLife - I will take a look and get everything updated accordingly.

fred-atherden commented 3 years ago

Many thanks!

naushinthomson commented 3 years ago

Nothing further to add, thanks for covering this one James!

JGilbert-eLife commented 3 years ago

@FAtherden-eLife Please could you update the message for supplementary-material-test-7 to:

Error: supplementary-material in additional files sections cannot have a media element with the attribute mimetype='video'. This should be mimetype='application'

fred-atherden commented 3 years ago

@FAtherden-eLife Please could you update the message for supplementary-material-test-7 to:

Error: supplementary-material in additional files sections cannot have a media element with the attribute mimetype='video'. This should be mimetype='application'

🤦...

Thanks, done.