-
Notifications
You must be signed in to change notification settings - Fork 29
docs: rewrite of the documentation #219
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Caution Review failedThe pull request is closed. WalkthroughThe documentation update reorganizes and expands the content in Changes
Possibly related PRs
Poem
Tip ⚡🧪 Multi-step agentic review comment chat (experimental)
📜 Recent review detailsConfiguration used: .coderabbit.yaml 📒 Files selected for processing (1)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 5
🧹 Nitpick comments (1)
docs/further.md (1)
3-3
: Clarify Explanation and Enforce Consistent Hyphenation
In the sentence explaining the removal of redundant logs, consider hyphenating “rule specific logs” to “rule‑specific logs” for grammatical accuracy.-... after all, we have the rule specific logs, too. +... after all, we have the rule‑specific logs, too.🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: When ‘rule-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...uccessful jobs - after all, we have the rule specific logs, too. Remote executors submit Sna...(SPECIFIC_HYPHEN)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/further.md
(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/further.md
[uncategorized] ~3-~3: When ‘rule-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...uccessful jobs - after all, we have the rule specific logs, too. Remote executors submit Sna...
(SPECIFIC_HYPHEN)
[formatting] ~11-~11: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ... a job sheperd running on the login node, because nobody should calculate there. We there...
(COMMA_BEFORE_BECAUSE)
[misspelling] ~17-~17: Use “a” instead of ‘an’ if the following word doesn’t start with a vowel sound, e.g. ‘a sentence’, ‘a university’.
Context: ...ur cluster and contribute your stats as an (https://github.com/snakemake/snakemake...
(EN_A_VS_AN)
[misspelling] ~21-~21: Use “a” instead of ‘an’ if the following word doesn’t start with a vowel sound, e.g. ‘a sentence’, ‘a university’.
Context: ...report bugs related to this plugin as an (https://github.com/snakemake/snakemake...
(EN_A_VS_AN)
🪛 markdownlint-cli2 (0.17.2)
docs/further.md
15-15: Reversed link syntax
(https://github.com/snakemake-workflows/transcriptome-differential-expression)[Transcriptome DiffExp + Fusion detection]
(MD011, no-reversed-links)
15-15: Bare URL used
null
(MD034, no-bare-urls)
15-15: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
17-17: Reversed link syntax
(https://github.com/snakemake/snakemake-executor-plugin-slurm/issue)[issue to the plugin repo on GitHub]
(MD011, no-reversed-links)
17-17: Bare URL used
null
(MD034, no-bare-urls)
21-21: Reversed link syntax
(https://github.com/snakemake/snakemake-executor-plugin-slurm/issue)[issue to the plugin repo on GitHub]
(MD011, no-reversed-links)
21-21: Reversed link syntax
(https://github.com/snakemake/snakemake/issues)[Snakemake main repository]
(MD011, no-reversed-links)
21-21: Bare URL used
null
(MD034, no-bare-urls)
21-21: Bare URL used
null
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: formatting
- GitHub Check: testing
🔇 Additional comments (4)
docs/further.md (4)
1-1
: Improved Section Title
The new title, "How this Plugin works", clearly conveys the section’s purpose and improves upon the previous, more generic title.
7-7
: Usage Hints Section Header
The header "#### Usage Hints" is concise and effective in guiding the reader to practical information.
9-9
: Clear Installation Instructions
The installation instructions are straightforward and informative. No changes are needed here.
19-19
: Reporting Bugs and Feature Requests Header
The header "#### Reporting Bugs and Feature Requests" is clear and sets the right expectation for users.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🔭 Outside diff range comments (3)
docs/further.md (3)
151-154
: 🛠️ Refactor suggestion
⚠️ Potential issueFix YAML Syntax in Configuration Snippet
In the YAML snippet under the configuration file example, the value for
slurm_account
is missing a closing quote, which could lead to copy-paste errors. Please update as follows:- slurm_account: "<your account> + slurm_account: "<your account>"
277-279
:⚠️ Potential issueCorrect Typographical Error in Log Removal Notice
There is a typo in the log removal notice where "sucessful jobs" should be "successful jobs." Please apply this change:
-This executor will remove SLURM logs of sucessful jobs immediately when they are finished. +This executor will remove SLURM logs of successful jobs immediately when they are finished.
319-319
:⚠️ Potential issueRemove Redundant Word in Dynamic Parameterization Section
In the sentence describing dynamic parameterization, the word "different" is duplicated. Please remove one instance to improve clarity:
-Using dynamic parameterization we can react on different different inputs and prevent our HPC jobs from failing. +Using dynamic parameterization we can react on different inputs and prevent our HPC jobs from failing.🧰 Tools
🪛 LanguageTool
[duplication] ~319-~319: Possible typo: you repeated a word.
Context: ...ynamic parameterization we can react on different different inputs and prevent our HPC jobs from fa...(ENGLISH_WORD_REPEAT_RULE)
🧹 Nitpick comments (3)
docs/further.md (3)
3-3
: Clarify Job Script Explanation and Correct HyphenationThe description explains that on an HPC cluster Snakemake submits itself as a job script. For improved readability, please change “rule specific logs” to “rule‑specific logs”.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: When ‘rule-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...uccessful jobs - after all, we have the rule specific logs, too. Remote executors submit Sna...(SPECIFIC_HYPHEN)
7-9
: Introduction of 'Usage Hints' SectionThe new "Usage Hints" subsection provides concise installation guidance, including the dependency on the "jobstep" plugin and recommendation to install
snakemake-storage-plugin-fs
. Consider adding a link or a brief description of the "jobstep" plugin to further assist users unfamiliar with it.
12-17
: Measurement Table Formatting and ClarityThe added table of performance metrics is a valuable inclusion. Please verify that the Markdown table uses consistent leading and trailing pipe characters so that it renders correctly in all Markdown processors. Additionally, the standard Markdown link format in the contribution call-to-action is now correctly applied.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
17-17: Table pipe style
Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe(MD055, table-pipe-style)
17-17: Table pipe style
Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe(MD055, table-pipe-style)
17-17: Table column count
Expected: 5; Actual: 1; Too few cells, row will be missing data(MD056, table-column-count)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/further.md
(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/further.md
[uncategorized] ~3-~3: When ‘rule-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...uccessful jobs - after all, we have the rule specific logs, too. Remote executors submit Sna...
(SPECIFIC_HYPHEN)
🪛 markdownlint-cli2 (0.17.2)
docs/further.md
17-17: Table pipe style
Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
(MD055, table-pipe-style)
17-17: Table pipe style
Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
(MD055, table-pipe-style)
17-17: Table column count
Expected: 5; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: testing
🔇 Additional comments (4)
docs/further.md (4)
1-2
: Update Section Title for ClarityThe header has been updated to "How this Plugin works", which makes the section purpose more immediately understandable compared to the previous title.
5-5
: Clear Description of Remote Executor FunctionalityThe explanation of how remote executors submit Snakemake jobs is clear and informative.
11-11
: Execution Advice on Login NodeThe guidance recommending that Snakemake be run on the login node is now clearly stated and correctly explains that administrative policies might restrict heavy computation on the login node.
19-21
: Enhanced Bug Reporting InstructionsThe "Reporting Bugs and Feature Requests" section clearly instructs users to report issues with well-formatted Markdown links. This should help direct feedback to the correct repository.
@dlaehnemann as agreed, please review. Thank you! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 1
🧹 Nitpick comments (11)
docs/further.md (11)
1-3
: Enhance Introductory Punctuation
Consider adding a comma after “In this plugin” (line 3) to improve readability.🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: A comma might be missing here.
Context: ### How this Plugin works In this plugin Snakemake submits itself as a job scrip...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
34-34
: Spacing in Profile Reference
In “persist such settings via a configuration profileconfiguration profile”, consider inserting a space before the bracketed link to improve readability.
51-51
: Refinecpus_per_task
Description
Consider rephrasing the sentence in line 51—perhaps by inserting a punctuation mark after “threads” or splitting the sentence—to enhance clarity.
71-74
: Typo Correction in YAML Comment
The word “seperately” (line 71) should be corrected to “separately”.-# parallelization with threads needs to be defined seperately: +# parallelization with threads needs to be defined separately:
112-112
: Improve MPImpiexec
Guidance
The sentence “To adapt the workflow an application usingmpiexec
” appears awkward. Consider rephrasing it to “To adapt the workflow for an application usingmpiexec
”.
253-271
: SLURM Resource Mapping
The guide mapping Snakemake resource definitions to SLURM flags is detailed. Consider adjusting the list indentation to fully comply with Markdown lint standards.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
260-260: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
261-261: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
263-263: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
264-264: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
266-266: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
267-267: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
269-269: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
270-270: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
369-373
: Conda Deployment and File System Guidance
There are minor typographical issues here. Consider correcting “in dicated” to “indicated” and revising “pointing the installation to different file system” to “pointing the installation to a different file system”.-... needs to be in dicated (e.g. because of quotas). In this case pointing the installation to different file system with `--conda-prefix /other/filesystem` might be a solution. +... needs to be indicated (e.g. because of quotas). In this case, pointing the installation to a different file system with `--conda-prefix /other/filesystem` might be a solution.🧰 Tools
🪛 LanguageTool
[uncategorized] ~373-~373: A comma might be missing here.
Context: ...table/snakefiles/deployment.html). On a cluster sometimes a file system other than `HOM...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~373-~373: Consider inserting a comma after an introductory phrase for better readability.
Context: ...be in dicated (e.g. because of quotas). In this case pointing the installation to different ...(IN_THAT_CASE_COMMA)
[uncategorized] ~373-~373: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...(AI_EN_LECTOR_MISSING_DETERMINER_A)
386-386
: Module Loading Wording
Consider shortening “immediately prior to execution” to “immediately before execution” for brevity.🧰 Tools
🪛 LanguageTool
[style] ~386-~386: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ... amodule load bio VinaLC
immediately prior to execution. Note, that - environment ...(EN_WORDINESS_PREMIUM_PRIOR_TO)
416-421
: Global Profile Setup Instructions
The instructions for setting up a global profile are clear. A minor improvement would be to add a comma in the first bullet point for better readability.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
416-416: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
419-419
: Typo in Profile Setup
“twill” (line 419) should be corrected to “will”.
500-500
: Duplicate Word Correction
“different different inputs” contains a duplicate word. Please remove the extra “different”.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/further.md
(9 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/further.md
[uncategorized] ~3-~3: A comma might be missing here.
Context: ### How this Plugin works In this plugin Snakemake submits itself as a job scrip...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[misspelling] ~40-~40: This word is normally spelled as one.
Context: ... that are either single-core scripts or multi-threaded applications, which are categorized as ...
(EN_COMPOUNDS_MULTI_THREADED)
[typographical] ~167-~167: Two consecutive dots
Context: ...ust be specified as a numerical value. .. note:: Internally, Snakemake knows the ...
(DOUBLE_PUNCTUATION)
[typographical] ~206-~206: Two consecutive dots
Context: ...our CPU cores for each GPU requested. .. note:: If cpus_per_gpu
is set to a va...
(DOUBLE_PUNCTUATION)
[uncategorized] ~298-~298: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...
(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
[uncategorized] ~373-~373: A comma might be missing here.
Context: ...table/snakefiles/deployment.html). On a cluster sometimes a file system other than `HOM...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~373-~373: Consider inserting a comma after an introductory phrase for better readability.
Context: ...be in dicated (e.g. because of quotas). In this case pointing the installation to different ...
(IN_THAT_CASE_COMMA)
[uncategorized] ~373-~373: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...
(AI_EN_LECTOR_MISSING_DETERMINER_A)
[style] ~386-~386: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ... a module load bio VinaLC
immediately prior to execution. Note, that - environment ...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
[uncategorized] ~439-~439: Loose punctuation mark.
Context: ... not needed anymore. - latency-wait: 5
: Sets a 5-second latency wait to accommo...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~440-~440: Loose punctuation mark.
Context: ...delays. - default-storage-provider: fs
: Utilizes the file system storage plugin...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~447-~447: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually you will be abl...
(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[typographical] ~447-~447: Consider adding a comma after ‘Eventually’ for more clarity.
Context: ...files. ==This is ongoing development. Eventually you will be able to annotate different ...
(RB_LY_COMMA)
[style] ~553-~553: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...
(CONSULT_WITH)
🪛 markdownlint-cli2 (0.17.2)
docs/further.md
40-40: Bare URL used
null
(MD034, no-bare-urls)
116-116: Dollar signs used before commands without showing output
null
(MD014, commands-show-output)
260-260: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
261-261: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
263-263: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
264-264: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
266-266: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
267-267: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
269-269: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
270-270: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
416-416: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
538-538: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: testing
🔇 Additional comments (51)
docs/further.md (51)
5-6
: Clarity of Execution Description
The explanation of remote executors and the discussion on memory footprint are clear and concise.
7-9
: Installation Instructions Clarity
The usage hints and installation instructions are well structured and clear.
11-13
: Improved Bug Reporting Guidelines
The “Reporting Bugs and Feature Requests” section now uses standard Markdown link syntax and offers clear instructions.
16-19
: Account and Partition Section Clarity
The explanation regarding SLURM’s account and partition concepts is well detailed and easy to follow.
36-36
: Job Status Check Timing Explanation
The explanation of the 40‑second wait for job status checks is clear and informative.
38-38
: SMP Jobs Section Header
The updated header “### Configuring SMP Jobs in Snakemake with the SLURM Executor Plugin” is clear and descriptive.
76-80
: Configuration Profile Explanation
The bullet-point explanation outlining default resources, overrides, and thread settings is clear and informative.
86-88
: MPI Jobs Overview
The MPI jobs section clearly explains the use ofsrun
and the benefits of this approach within SLURM-managed clusters.
134-138
: MPI Resource Specifications Clarity
The bullet points detailing resource allocations for MPI tasks are well presented and clear.
148-159
: GPU Resources Example
The provided example demonstrating GPU resource requests (withgpu
andgpu_model
) is concise and correctly formatted.
170-184
: Alternative GPU Resource Specification
The alternative method using thegres
resource is well explained with a clear Python example.
192-203
: CPU Allocation per GPU Example
The sample rule illustrating the use ofcpus_per_gpu
is concise and clear.
213-227
: Workflow Profile for GPU Jobs
The YAML snippet for the GPU jobs profile is clear and effectively demonstrates resource specifications.
231-234
: Profile Configuration Summary
The bullet-point summary describing the profile configuration for GPU jobs is clear and informative.
238-241
: Clarification on GPU Resource Request Methods
The note explaining the differences between usinggpu
andgres
is thorough and useful.
242-247
: Local Execution Guidelines
The section on running jobs locally and the use of thelocalrules
directive is explained clearly.
274-288
: Example Rule Resource Specifications
The example rule detailing resource specifications (such as partition, runtime, memory, and CPUs) is clear and practical.
289-293
: Important Considerations for Resources
The discussion on the mutual exclusivity of memory flags and the advice against hardcoding cluster-specific resources is well articulated.
296-298
: Leveraging Configuration Profiles
The rationale for using configuration profiles to manage resource specifications is presented clearly.🧰 Tools
🪛 LanguageTool
[uncategorized] ~298-~298: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
300-316
: Snakemake Profile Configuration Example
The YAML configuration example for a Snakemake profile is well structured and comprehensive.
317-320
: Profile Configuration Summary
The summary of default resources and rule-specific overrides is clear and effectively communicated.
329-343
: Multicluster Support Documentation
The section on multicluster support—with examples for setting default clusters and comma-separated lists—is clear and thorough.Also applies to: 347-350
354-357
: Custom Job Configuration with slurm_extra
The explanation and example illustrating how to use theslurm_extra
parameter for custom job options are clear and useful.
375-377
: Using Environment Modules
The explanation regarding the use of environment modules with--sdm env-modules
is concise and clear.
388-392
: Environment Modules Note
The additional notes on environment modules are clear. Ensure that the formatting remains consistent with the rest of the documentation.
392-398
: Job Information Commands
The commands provided for retrieving job information withsacct
(and the formatting details) are well explained and useful.🧰 Tools
🪛 LanguageTool
[misspelling] ~394-~394: This word is normally spelled with a hyphen.
Context: ... strain on the batch system's database. Human readable information is stored in the comment of...(EN_COMPOUNDS_HUMAN_READABLE)
400-406
: SLURM Log Format Details
The explanation of how the%40
formatting works in log commands is clear and informative.
408-410
: Job Status Check Timings
The details explaining the job status check intervals in Snakemake are clearly presented.
412-416
: Profiles Overview
The introduction to the “Using Profiles” section is well written and provides a useful link to further documentation.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
416-416: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
421-434
: Global Profile Configuration Example
The YAML snippet for configuring a global Snakemake profile is clear and comprehensive.
437-443
: Summary of Profile Settings
The bullet list summarizing the global profile settings is concise and informative.🧰 Tools
🪛 LanguageTool
[uncategorized] ~439-~439: Loose punctuation mark.
Context: ... not needed anymore. -latency-wait: 5
: Sets a 5-second latency wait to accommo...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~440-~440: Loose punctuation mark.
Context: ...delays. -default-storage-provider: fs
: Utilizes the file system storage plugin...(UNLIKELY_OPENING_PUNCTUATION)
445-447
: File System Storage Plugin Notice
The note regarding the file system storage plugin is informative. The phrasing is acceptable, though you might consider a slight rewording for enhanced clarity if desired.🧰 Tools
🪛 LanguageTool
[uncategorized] ~447-~447: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually you will be abl...(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[typographical] ~447-~447: Consider adding a comma after ‘Eventually’ for more clarity.
Context: ...files. ==This is ongoing development. Eventually you will be able to annotate different ...(RB_LY_COMMA)
447-447
: Ongoing Development Notice
The notice about ongoing development is clear. No changes needed here.🧰 Tools
🪛 LanguageTool
[uncategorized] ~447-~447: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually you will be abl...(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[typographical] ~447-~447: Consider adding a comma after ‘Eventually’ for more clarity.
Context: ...files. ==This is ongoing development. Eventually you will be able to annotate different ...(RB_LY_COMMA)
449-453
: Log Files Management
The section on log file retention and deletion is comprehensive and well documented.
455-461
: SLURM Log Directory Configuration
The instructions for redirecting SLURM logs to a centralized directory are clear and helpful.
461-463
: Retries and Job Failure Section
The header for the retries section effectively introduces the subsequent content.
463-473
: Automatic Retry Commands
The examples demonstrating how to use the--retries
option for job retries are clear and succinct.
474-481
: Resuming Incomplete Jobs
The instructions and examples on how to resume incomplete jobs using--rerun-incomplete
(or its shorthand--ri
) are clear and useful for users.
482-489
: Job Requeuing Details
The explanation of SLURM’s job requeue feature, along with the example command, is detailed and informative.
490-495
: Requeue Option Guidance
The advice on checking cluster requeue settings and using--slurm-requeue
is clear and practical.
496-496
: Dynamic Parameterization Introduction
The transition into the dynamic parameterization section is smooth and sets the stage well.
502-521
: Dynamic Resource Adjustments Examples
The examples demonstrating how to adjust memory requirements and runtime dynamically are clear and instructive.
522-529
: Workflow Profile Runtime Adjustment
The YAML snippet showing dynamic runtime adjustments via a workflow profile is clear and effective.
531-531
: Parallel Execution Recommendation
The advice to use sensible settings and leverage parallel execution and global profiles is useful for optimizing performance.
534-536
: Nesting Jobs Warning
The caution regarding running Snakemake within an active SLURM job is well explained and appropriately warns users.
538-547
: Command Line Summary
The summary section and accompanying command-line example provide a concise and practical overview of typical usage scenarios.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
538-538: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
548-556
: Introduction to FAQ Section
The FAQ section is introduced clearly, setting an appropriate context for common user questions.🧰 Tools
🪛 LanguageTool
[style] ~553-~553: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...(CONSULT_WITH)
557-560
: CPU Time Measurement Example
The/usr/bin/time -v snakemake ...
command example is very useful for users needing to profile CPU usage on the login node.
561-565
: Measurement Table Presentation
The presentation of the measurements table is clear, with proper formatting and helpful metrics.
569-569
: Call to Contribute Statistics
The call-to-action for submitting statistics is well formatted and clear.
571-575
: FAQ on Running Snakemake on Login Node
The FAQ section discussing the implications of running Snakemake on a login node is detailed and helpful.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/further.md (5)
3-3
: Punctuation Suggestion in Introductory Sentence
Consider adding a comma after “In this plugin” to improve readability. For example:-In this plugin Snakemake submits itself... +In this plugin, Snakemake submits itself...🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: A comma might be missing here.
Context: ### How this Plugin works In this plugin Snakemake submits itself as a job scrip...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
40-40
: Word Spelling Consistency
Static analysis suggests using “multithreaded” as a single word rather than “multi-threaded.” Consider:- multi-threaded + multithreadedThis change aligns with common usage and improves consistency.
🧰 Tools
🪛 LanguageTool
[misspelling] ~40-~40: This word is normally spelled as one.
Context: ... that are either single-core scripts or multi-threaded applications, which are categorized as ...(EN_COMPOUNDS_MULTI_THREADED)
373-373
: Conda Deployment Grammar Suggestion
On line 373, consider revising the phrasing for better clarity. For example:-... a file system other than `HOME` needs to be in dicated (e.g. because of quotas). In this case pointing the installation to different file system with `--conda-prefix /other/filesystem` might be a solution. +... a file system other than `HOME` needs to be indicated (e.g. because of quotas). In this case, pointing the installation to a different file system using `--conda-prefix /other/filesystem` might be a solution.🧰 Tools
🪛 LanguageTool
[uncategorized] ~373-~373: A comma might be missing here.
Context: ...table/snakefiles/deployment.html). On a cluster sometimes a file system other than `HOM...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~373-~373: Consider inserting a comma after an introductory phrase for better readability.
Context: ...be in dicated (e.g. because of quotas). In this case pointing the installation to different ...(IN_THAT_CASE_COMMA)
[uncategorized] ~373-~373: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...(AI_EN_LECTOR_MISSING_DETERMINER_A)
376-387
: Environment Modules Section – Minor Wording Improvement
The instructions for using environment modules are clear. Consider replacing “immediately prior to execution” with “immediately before execution” for conciseness:-This will trigger a `module load bio VinaLC` immediately prior to execution. +This will trigger a `module load bio VinaLC` immediately before execution.🧰 Tools
🪛 LanguageTool
[style] ~386-~386: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ... amodule load bio VinaLC
immediately prior to execution. Note, that - environment ...(EN_WORDINESS_PREMIUM_PRIOR_TO)
🪛 markdownlint-cli2 (0.17.2)
379-379: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
445-447
: Development Note Formatting
The note “==This is ongoing development. Eventually you will be able to annotate different file access patterns.==” appears informal. Consider reformatting it as a blockquote or removing it from the final documentation if it’s meant only for internal development.🧰 Tools
🪛 LanguageTool
[uncategorized] ~447-~447: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually you will be abl...(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[typographical] ~447-~447: Consider adding a comma after ‘Eventually’ for more clarity.
Context: ...files. ==This is ongoing development. Eventually you will be able to annotate different ...(RB_LY_COMMA)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/further.md
(9 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/further.md
[uncategorized] ~3-~3: A comma might be missing here.
Context: ### How this Plugin works In this plugin Snakemake submits itself as a job scrip...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[misspelling] ~40-~40: This word is normally spelled as one.
Context: ... that are either single-core scripts or multi-threaded applications, which are categorized as ...
(EN_COMPOUNDS_MULTI_THREADED)
[typographical] ~167-~167: Two consecutive dots
Context: ...ust be specified as a numerical value. .. note:: Internally, Snakemake knows the ...
(DOUBLE_PUNCTUATION)
[typographical] ~206-~206: Two consecutive dots
Context: ...our CPU cores for each GPU requested. .. note:: If cpus_per_gpu
is set to a va...
(DOUBLE_PUNCTUATION)
[uncategorized] ~298-~298: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...
(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
[uncategorized] ~373-~373: A comma might be missing here.
Context: ...table/snakefiles/deployment.html). On a cluster sometimes a file system other than `HOM...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~373-~373: Consider inserting a comma after an introductory phrase for better readability.
Context: ...be in dicated (e.g. because of quotas). In this case pointing the installation to different ...
(IN_THAT_CASE_COMMA)
[uncategorized] ~373-~373: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...
(AI_EN_LECTOR_MISSING_DETERMINER_A)
[style] ~386-~386: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ... a module load bio VinaLC
immediately prior to execution. Note, that - environment ...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
[uncategorized] ~439-~439: Loose punctuation mark.
Context: ... not needed anymore. - latency-wait: 5
: Sets a 5-second latency wait to accommo...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~440-~440: Loose punctuation mark.
Context: ...delays. - default-storage-provider: fs
: Utilizes the file system storage plugin...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~447-~447: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually you will be abl...
(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[typographical] ~447-~447: Consider adding a comma after ‘Eventually’ for more clarity.
Context: ...files. ==This is ongoing development. Eventually you will be able to annotate different ...
(RB_LY_COMMA)
[style] ~553-~553: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...
(CONSULT_WITH)
🪛 markdownlint-cli2 (0.17.2)
docs/further.md
116-116: Dollar signs used before commands without showing output
null
(MD014, commands-show-output)
260-260: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
261-261: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
263-263: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
264-264: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
266-266: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
267-267: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
269-269: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
270-270: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
416-416: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
538-538: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: testing
🔇 Additional comments (54)
docs/further.md (54)
1-1
: Section Title Clarity
The new section title “### How this Plugin works” is clear and immediately sets the reader’s expectations.
5-5
: Clarity on Executor Functionality
The explanation of how remote executors work and their impact on memory footprint is clear and informative.
7-10
: Usage Hints Are Well Presented
The “#### Usage Hints” section provides clear installation instructions and lists helpful dependency recommendations.
11-13
: Improved Bug Reporting Section
The “#### Reporting Bugs and Feature Requests” section now uses standard Markdown link syntax, which greatly improves clarity.
17-19
: SLURM Account and Partition Explanation
The description of SLURM’s account and partition is succinct and well explained.
21-32
: Command Examples Are Clear
The provided examples for specifying default resources and overriding partitions are clear and practical for users.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
24-24: Dollar signs used before commands without showing output
null(MD014, commands-show-output)
31-31: Dollar signs used before commands without showing output
null(MD014, commands-show-output)
34-34
: Link to Configuration Profiles
The in-text link to the configuration profile documentation is correctly formatted and informative.
36-36
: Job Status Check Detail
Providing the default 40‑second wait and the option to adjust it is a useful detail for HPC workflow developers.
38-38
: SMP Jobs Section Header
The updated title “### Configuring SMP Jobs in Snakemake with the SLURM Executor Plugin” is descriptive and sets the correct context.
42-49
: Practical SMP Example
The Python code example for a rule that requests 8 CPU cores and 14 GB of memory is practical and easy to follow.
51-51
: Resource Parameter Clarification
The note about how Snakemake prioritizes thecpus_per_task
parameter overthreads
is useful and clear.
53-74
: Well-Structured YAML Profile Example
The YAML example illustrating default resources, rule-specific overrides, and thread settings is well organized and very informative.
76-83
: Configuration Profile Explanation
The explanation following the YAML example clearly outlines the benefits of using a configuration profile for platform independence.
90-101
: MPI Job Example Clarity
The MPI job rule example—with its use ofsrun
and clear resource definitions—is an excellent practical illustration.
103-108
: Detailed MPI Configuration Explanation
The additional explanation of MPI resource allocation and the rationale behind usingsrun
is thorough and useful.
109-112
: Portability Considerations Are Clear
The “#### Portability Considerations” section effectively explains why and how to ensure the workflow remains portable across different environments.
115-118
: Overriding MPI Launcher Example
The example demonstrating how to override thempi
resource at runtime is clear and helps illustrate the flexibility of configuring MPI jobs.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
116-116: Dollar signs used before commands without showing output
null(MD014, commands-show-output)
119-132
: Thorough MPI Resource Specification
The YAML example for specifying resources for MPI jobs is comprehensive and clearly demonstrates the allocation of MPI tasks and CPU cores per task.
133-137
: Concise MPI Resource Explanation
The summary of resource allocations for MPI rules is succinct and effectively communicates the configuration details.
138-139
: Advanced MPI Configuration Option
The mention of using theslurm_extra
parameter for advanced scenarios is a nice touch that informs users about extending default behavior.
140-140
: GPU Jobs Section Header Clarity
The “### GPU Jobs” header immediately signals that the following sections pertain to GPU resource configuration, which is helpful.
142-160
: Clear GPU Resource Example
The example for specifying GPU resources using thegpu
parameter, along with an optional GPU model, is straightforward and useful.
161-167
: GPU Resource Translation Explanation
The explanation detailing how Snakemake converts thegpu
resource into SLURM’s--gpus
flag is clear and beneficial for users.🧰 Tools
🪛 LanguageTool
[typographical] ~167-~167: Two consecutive dots
Context: ...ust be specified as a numerical value. .. note:: Internally, Snakemake knows the ...(DOUBLE_PUNCTUATION)
168-168
: Note Block Formatting Confirmation
The “.. note::” block concerninggpu_manufacturer
appears correctly formatted in reStructuredText. No changes required.
170-184
: Alternative GPU Specification via gres
The alternative method using thegres
resource is well presented and provides users with a flexible option based on their cluster’s capabilities.
188-203
: CPU Allocation per GPU Detailed Example
The section explaining how to allocate CPUs per GPU—including a clear example—is very helpful for preventing CPU bottlenecks in GPU-intensive jobs.
205-206
: CPU Allocation Explanation Clarity
The description stating that “cpus_per_gpu=4 allocates four CPU cores for each GPU” is clear and concise.🧰 Tools
🪛 LanguageTool
[typographical] ~206-~206: Two consecutive dots
Context: ...our CPU cores for each GPU requested. .. note:: Ifcpus_per_gpu
is set to a va...(DOUBLE_PUNCTUATION)
209-227
: Well-Structured Sample Workflow Profile for GPU Jobs
The YAML sample detailing resource specifications for GPU jobs is clearly formatted and provides practical examples for different rule requirements.
229-234
: Clear Explanation of GPU Profile Configuration
The breakdown of each rule’s settings in the GPU profile example effectively demonstrates how to customize resource requests.
235-236
: Concise Summary of Profile Benefits
The closing remark on the advantages of using a configuration profile for resource management is well stated.
237-241
: Effective Important Note on GPU Resources
The “#### Important Note” regarding the choice between usinggpu
orgres
is important and clearly prompts users to consult their cluster documentation.
243-250
: Local Job Execution Guidance
The “### Running Jobs locally” section concisely explains when and why to run certain jobs on the head node, providing a helpful tip with the localrules directive.
251-289
: Advanced Resource Specifications Are Comprehensive
The section mapping Snakemake resources to SLURM parameters—including a detailed rule example—is thorough and clear for advanced users.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
260-260: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
261-261: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
263-263: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
264-264: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
266-266: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
267-267: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
269-269: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
270-270: Unordered list indentation
Expected: 2; Actual: 4(MD007, ul-indent)
290-293
: Highlighting Key Considerations
The “#### Important Considerations” section effectively emphasizes best practices such as the mutual exclusivity of memory flags and avoiding hardcoded cluster-specific resources.
296-320
: Excellent Guidance on Using Profiles
The instructions for using configuration profiles for resource specifications, accompanied by a practical YAML example, are very well written.🧰 Tools
🪛 LanguageTool
[uncategorized] ~298-~298: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
329-343
: Multicluster Support Section Clarity
The explanation and YAML examples for multicluster support are clear and enable users to distribute jobs across clusters efficiently.
344-350
: Comma-Separated Multicluster Example Is Clear
The YAML snippet demonstrating comma-separated cluster support is straightforward and useful.
352-358
: Custom Job Configuration Guidance
The section on additional custom job configuration using theslurm_extra
resource is well explained and adds valuable flexibility for advanced users.
359-366
: Custom Job Example Is Well Illustrated
The Python code example showing how to useslurm_extra
provides a clear illustration of the concept.
367-367
: Profile Recommendation Reminder
The reminder to use a [profile] for specifying additional job configuration reinforces best practices and is well placed.
392-408
: Job Information and Rate Limiter Instructions
The examples usingsacct
andsqueue
to inquire about job status are precise and the explanations about column width adjustments are very helpful.🧰 Tools
🪛 LanguageTool
[misspelling] ~394-~394: This word is normally spelled with a hyphen.
Context: ... strain on the batch system's database. Human readable information is stored in the comment of...(EN_COMPOUNDS_HUMAN_READABLE)
412-420
: Using Profiles to Streamline Configuration
The explanation of how profiles consolidate configuration settings is clear and the reference link is useful for further reading.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
416-416: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
423-434
: Sample YAML Profile Configuration is Clear
The provided YAML configuration for setting up a global profile is well-formatted and serves as a practical example for users.
437-444
: Configuration Explanation Post-YAML Block
The explanation following the sample configuration effectively details the purpose of each key (e.g.,executor
,latency-wait
), ensuring that users understand the settings.🧰 Tools
🪛 LanguageTool
[uncategorized] ~439-~439: Loose punctuation mark.
Context: ... not needed anymore. -latency-wait: 5
: Sets a 5-second latency wait to accommo...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~440-~440: Loose punctuation mark.
Context: ...delays. -default-storage-provider: fs
: Utilizes the file system storage plugin...(UNLIKELY_OPENING_PUNCTUATION)
449-462
: Log Files Management is Well Documented
The section detailing the handling of SLURM log files—including how to retain or delete them—is comprehensive and the YAML example for setting a log directory is very useful.
463-481
: Retries and Workflow Resumption Instructions
The guidance on using the--retries
and--rerun-incomplete
options is clear and provides practical command examples for users facing job failures.
483-495
: Automatic Job Requeuing Section
The section explaining SLURM’s job requeue feature, accompanied by command examples, is thorough and well explained.
497-533
: Dynamic Parameterization is Well Articulated
The explanation of how to adjust memory requirements and runtime dynamically—with both Python and YAML examples—is clear and provides a powerful technique for managing job failures.🧰 Tools
🪛 LanguageTool
[uncategorized] ~501-~501: The preposition “to” seems more likely in this position.
Context: ...g dynamic parameterization we can react on different different inputs and prevent ...(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
[duplication] ~501-~501: Possible typo: you repeated a word.
Context: ...ynamic parameterization we can react on different different inputs and prevent our HPC jobs from fa...(ENGLISH_WORD_REPEAT_RULE)
534-537
: Nesting Jobs Warning is Clear
The cautionary note on running Snakemake within an active SLURM job is clear and appropriately warns users of potential unpredictable behavior.
538-548
: Summary Command Line Example is Helpful
The summary section that provides a comprehensive example command line is concise and reinforces the documentation in a practical manner.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
538-538: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
551-559
: FAQ on Running Snakemake on the Login Node
The FAQ addressing whether Snakemake can be run on a login node is comprehensive and answers potential administrator concerns well.🧰 Tools
🪛 LanguageTool
[style] ~553-~553: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...(CONSULT_WITH)
563-568
: Measurement Table is Well Formatted
The table of measurements, with standard Markdown link syntax and clear column formatting, is easy to read and informative.
569-570
: Encouraging Community Contributions
The instructions on how users can contribute their statistics are clear and present an excellent opportunity for community engagement.
571-575
: FAQ on Alternative Running Methods
The final FAQ addressing issues with running Snakemake on the login node when prohibited by administrators is clear and offers practical advice for reporting issues.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (12)
docs/further.md (12)
5-5
: Clarification on Resource Utilization Variability
The text now highlights that different functionalities (like piped group jobs or run directives) can affect memory requirements. You might consider briefly enumerating one or two typical examples for further clarity.
40-40
: Clarification on SMP Job Requirements
The explanation now clearly distinguishes between single-core scripts and multi-threaded applications. A minor nitpick: verify that the term “multi-threaded” is consistently hyphenated in the document.🧰 Tools
🪛 LanguageTool
[misspelling] ~40-~40: This word is normally spelled as one.
Context: ... that are either single-core scripts or multi-threaded applications, which are categorized as ...(EN_COMPOUNDS_MULTI_THREADED)
55-74
: YAML Configuration Example for Resource Settings
The comprehensive YAML example effectively demonstrates how to set default resources, overrides, and thread settings. Consider adding inline comments in the YAML snippet to help less experienced users understand each option.
142-142
: Clarification on GPU Allocation Options
The explanation regarding SLURM’s--gres
and--gpus
flags is thorough. You might add a brief remark about potential pitfalls if the numerical requirement forgpu
is not correctly specified.
258-269
: Detailed Mapping of Resource Settings
The bullet list clearly outlines how items such as partition, runtime, memory, and constraints correlate to SLURM flags. There are a few minor punctuation concerns—please review for consistent style.
298-298
: Explanation of the Flexibility Offered by Profiles
The text clearly explains the benefits of using profiles. A minor nitpick: consider inserting a comma after introductory phrases for improved clarity.🧰 Tools
🪛 LanguageTool
[uncategorized] ~298-~298: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
373-373
: Guidance on File System Considerations for Conda Deployments
There are minor grammatical issues here—consider revising the sentence to: “On a cluster, sometimes a file system other thanHOME
must be used; in this case, pointing the installation to a different file system with--conda-prefix /other/filesystem
might be a solution.”🧰 Tools
🪛 LanguageTool
[uncategorized] ~373-~373: A comma might be missing here.
Context: ...table/snakefiles/deployment.html). On a cluster sometimes a file system other than `HOM...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~373-~373: Consider inserting a comma after an introductory phrase for better readability.
Context: ... be indicated (e.g. because of quotas). In this case pointing the installation to different ...(IN_THAT_CASE_COMMA)
[uncategorized] ~373-~373: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...(AI_EN_LECTOR_MISSING_DETERMINER_A)
418-418
: Creating a Profile Directory
The recommendation to create a directory at$HOME/.config/snakemake
is clear; you might consider rephrasing for brevity as suggested.
447-447
: Ongoing Development Notice
The notice is informative. A minor nitpick: insert a comma after “Eventually” for improved readability (e.g., “Eventually, you will be able…”).🧰 Tools
🪛 LanguageTool
[uncategorized] ~447-~447: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually you will be abl...(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[typographical] ~447-~447: Consider adding a comma after ‘Eventually’ for more clarity.
Context: ...files. ==This is ongoing development. Eventually you will be able to annotate different ...(RB_LY_COMMA)
501-501
: Suggestion to Refine Dynamic Parameterization Text
While the message is clear, consider revising “react on different inputs” to “react to different inputs” and inserting a comma after the introductory phrase for enhanced readability.🧰 Tools
🪛 LanguageTool
[uncategorized] ~501-~501: A comma might be missing here.
Context: ...Dynamic Parameterization Using dynamic parameterization we can react on different inputs and pr...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~501-~501: The preposition “to” seems more likely in this position.
Context: ...g dynamic parameterization we can react on different inputs and prevent our HPC jo...(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
553-553
: Discussion on Running on the Login Node
The explanation is comprehensive; however, consider streamlining the phrasing (e.g. replace “should consult with your cluster's support team” with “consult your cluster’s support team”) to reduce redundancy.🧰 Tools
🪛 LanguageTool
[style] ~553-~553: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...(CONSULT_WITH)
565-565
: Table Formatting and Link Syntax in Workflow Metrics
The metrics table is informative. Please verify that the Markdown link formatting meets your project’s style guidelines (avoid reversed link syntax or bare URLs).
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/further.md
(10 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/further.md
[misspelling] ~40-~40: This word is normally spelled as one.
Context: ... that are either single-core scripts or multi-threaded applications, which are categorized as ...
(EN_COMPOUNDS_MULTI_THREADED)
[typographical] ~167-~167: Two consecutive dots
Context: ...ust be specified as a numerical value. .. note:: Internally, Snakemake knows the ...
(DOUBLE_PUNCTUATION)
[typographical] ~206-~206: Two consecutive dots
Context: ...our CPU cores for each GPU requested. .. note:: If cpus_per_gpu
is set to a va...
(DOUBLE_PUNCTUATION)
[uncategorized] ~298-~298: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...
(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
[uncategorized] ~373-~373: A comma might be missing here.
Context: ...table/snakefiles/deployment.html). On a cluster sometimes a file system other than `HOM...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~373-~373: Consider inserting a comma after an introductory phrase for better readability.
Context: ... be indicated (e.g. because of quotas). In this case pointing the installation to different ...
(IN_THAT_CASE_COMMA)
[uncategorized] ~373-~373: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...
(AI_EN_LECTOR_MISSING_DETERMINER_A)
[uncategorized] ~439-~439: Loose punctuation mark.
Context: ... not needed anymore. - latency-wait: 5
: Sets a 5-second latency wait to accommo...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~440-~440: Loose punctuation mark.
Context: ...delays. - default-storage-provider: fs
: Utilizes the file system storage plugin...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~447-~447: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually you will be abl...
(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[typographical] ~447-~447: Consider adding a comma after ‘Eventually’ for more clarity.
Context: ...files. ==This is ongoing development. Eventually you will be able to annotate different ...
(RB_LY_COMMA)
[uncategorized] ~501-~501: A comma might be missing here.
Context: ...Dynamic Parameterization Using dynamic parameterization we can react on different inputs and pr...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~501-~501: The preposition “to” seems more likely in this position.
Context: ...g dynamic parameterization we can react on different inputs and prevent our HPC jo...
(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
[style] ~553-~553: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...
(CONSULT_WITH)
🪛 markdownlint-cli2 (0.17.2)
docs/further.md
116-116: Dollar signs used before commands without showing output
null
(MD014, commands-show-output)
416-416: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
538-538: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: testing
🔇 Additional comments (101)
docs/further.md (101)
1-1
: Section Title Updated: "How this Plugin works"
The new title clearly outlines the section’s purpose. Please verify that this phrasing is consistent with similar headings elsewhere in the documentation.
3-3
: Overview of Job Submission and Log Handling
The explanation now provides a concise description of how Snakemake runs as a job script on an HPC cluster and manages SLURM log files. Consider mentioning any troubleshooting implications if users need to retain logs.
7-7
: New "Usage Hints" Subsection Introduced
The addition of this subheading is a great way to signal actionable installation instructions to users.
9-9
: Enhanced Installation Instructions
The installation guidance is clear and now includes a recommendation to install thesnakemake-storage-plugin-fs
. Verify that all dependencies and installation methods are documented consistently elsewhere.
11-11
: Improved Bug Reporting Heading
Using the standard Markdown link format greatly improves readability. It might be useful to add a short note about what qualifies as a bug specific to this plugin.
13-13
: Detailed Reporting Guidelines for Issues
The revised text now directs users to report plugin-specific issues with proper links. Confirm that both links are active and that the instructions are harmonized with community guidelines.
17-18
: Explanation of SLURM Account and Partition
The description about how an account and partition function in SLURM is succinct and informative. No further changes are needed.
34-34
: Recommendation to Persist Settings with a Configuration Profile
Suggesting a configuration profile helps users manage settings more easily. Please ensure the linked documentation is current.
36-36
: Adjustable Job Status Check Interval Added
Introducing the--slurm-init-seconds-before-status-checks
option is useful for development. You might add a brief example illustrating when and why to adjust it.
38-38
: SMP Jobs Section Title Revision
The updated title “Configuring SMP Jobs in Snakemake with the SLURM Executor Plugin” is descriptive and aligns with the detailed content.
51-51
: Note on Resource Precedence for CPU Settings
The reminder that Snakemake treatscpus_per_task
as an alternative tothreads
is helpful. Please ensure the terminology aligns throughout the docs.
53-53
: Guidance on Creating a Cluster-Specific Workflow Profile
The new instructions help users externalize resource settings for portability. This is clear and well‐documented.
76-78
: Explanatory Text for YAML Configuration
The accompanying explanation succinctly describes the purpose of each YAML section.
86-86
: Introduction to MPI Jobs
The description now informs users that the SLURM executor supports MPI jobs and recommends usingsrun
. This is clear and useful for those setting up parallel jobs.
88-88
: Example of Defining an MPI Rule
The provided MPI example clearly highlights how to set MPI tasks and specifysrun
as the launcher.
105-105
: Detailed Breakdown of MPI Resource Settings
The bullet list outlining howtasks
andmpi
are used in the MPI configuration is clear and direct.
114-114
: MPI Resource Override Instructions
The text explaining how to override the MPI launcher (for instance, to usempiexec
) is concise and useful.
120-120
: Defining Resources for Hybrid MPI Jobs
The explanation that bothtasks
andcpus_per_task
can be specified for hybrid MPI applications is clear.
134-136
: Explanation of Hybrid MPI Job Settings
The distinction betweenmpi_rule
andhybrid_mpi_rule
is well conveyed. Ensure that the CPU core allocations correspond to realistic workload expectations.
138-138
: Advanced MPI Configuration with Additional SLURM Options
Mentioning the use of theslurm_extra
parameter for advanced scenarios provides additional flexibility. Consider linking to further examples if available.
140-140
: New Section Introducing GPU Jobs
The GPU Jobs section is now comprehensive and introduces both native GPU resource requests and alternative methods.
144-144
: Guidance on Specifying GPU Resources in Rules
The instructions to use thegpu
resource and optionally specifygpu_model
clearly describe how to request GPUs.
148-148
: GPU Task Rule Example
The provided Python snippet demonstrates how to request GPUs effectively.
161-163
: Explanation of Translation of GPU Requests
The note that Snakemake converts the GPU request into a SLURM command flag (e.g.--gpus=a100:2
) is beneficial. Please verify this behavior against your cluster’s configuration.
166-166
: Emphasis on Numerical Specification for GPU Resources
A reminder that thegpu
resource must be a number is now clearly stated—a critical detail for users.
168-168
: Additional Note ongpu_manufacturer
The note adds valuable context about SLURM’s limitations in distinguishing GPU models from manufacturers.
170-170
: Offering an Alternative GPU Request Method
Introducing the option to use thegres
resource for specifying GPU requirements offers flexibility on various cluster setups.
172-172
: Explanation of GRE Syntax for GPU Requests
The text now clearly explains the syntax (either<resource_type>:<number>
or<resource_type>:<model>:<number>
) for usinggres
.
174-174
: Alternate GPU Task Rule with GRE Example
The alternative Python snippet usinggres
is well constructed and easy to follow.
186-186
: Highlight on CPU Allocation for GPU Tasks
The paragraph clearly emphasizes the importance of allocating sufficient CPU resources per GPU.
188-188
: Section Heading for CPU Allocation Considerations
This heading adequately introduces the subsequent details on CPU allocation per GPU.
190-190
: Example for Allocating CPUs per GPU
The code snippet neatly illustrates the allocation of 4 CPU cores per GPU.
205-205
: Summary of Resource Allocation Example
A succinct reminder thatcpus_per_gpu=4
translates into the desired CPU allocation for GPU tasks.
207-207
: Policy Note on CPU Request When Under-Allocated
This note clearly explains that ifcpus_per_gpu
is less than or equal to zero, no CPU request is made, letting the cluster’s defaults apply.
209-209
: Introduction to a Workflow Profile for GPU Jobs
Suggesting the use of a configuration profile to manage GPU resources simplifies ongoing maintenance.
229-232
: Explanation of GPU Workflow Profile Components
The breakdown of what each rule in the profile does is clear. Verify that the YAML syntax (such as spacing and use of quotes) meets your project’s style guidelines.
234-234
: Summary of Benefits of Using a Profile for GPU Configuration
This summary reinforces how profiles help in organizing and standardizing resource definitions.
236-236
: Important Note on Selecting a GPU Request Method
The note advising users to consult their cluster administrators highlights the need for customization based on local configuration.
240-240
: Optimizing GPU-Accelerated Job Performance
Encourages users to tailor GPU resource requests to their specific cluster configurations, enhancing overall performance.
243-243
: Section: Running Jobs Locally
This new section clarifies that not all tasks need to leverage the cluster, which can optimize performance and reduce overhead.
245-245
: Explanation of the Local Execution Directive
The description regarding thelocalrules
directive is clear and useful for users who need to run specific rules locally.
253-253
: Mapping Snakemake Resources to SLURM Parameters
The introduction to how resources map directly to SLURM flags is comprehensive.
273-273
: Introducing a Rule Example for SLURM Submissions
The text prepares the reader for an example rule that ties together the resource definitions.
288-288
: Clarification of the Example Rule Outcome
The explanation following the example succinctly describes the expected resource allocations (e.g. partition, runtime, memory, CPU cores).
290-290
: Important Considerations for Resource Flags
The heading introduces critical information about the mutual exclusivity of SLURM memory flags.
292-292
: Mutual Exclusivity Reminder for Memory Flags
This reminder effectively stresses that users should choose betweenmem_mb
andmem_mb_per_cpu
but not both.
294-294
: Recommendation Against Hardcoding Cluster-Specific Settings
Encouraging the use of default resources or configuration profiles helps maintain workflow portability.
296-296
: Introducing the Concept of Using Configuration Profiles
This heading clearly marks the start of a discussion on profiles for resource management.
300-300
: Example Configuration for Profiles
The sample configuration provides a practical template for users. Please double-check the YAML indentation and formatting against the project’s standards.
317-319
: Breakdown of Profile Components and Their Benefits
The explanation differentiating default settings from rule-specific overrides is clear and informative.
323-323
: Leveraging Profiles to Enhance Portability
This reiterates the advantages of using profiles without embedding cluster-specific details directly into the workflow.
327-327
: Multicluster Support Section Introduced
The addition of multicluster support details provides valuable flexibility for users submitting jobs across different clusters.
329-329
: Explanation of Multicluster Configuration Details
The text clearly explains how to set default and rule-specific clusters using comma-separated values.
331-331
: Multicluster YAML Example Provided
The YAML snippet for multicluster support is helpful. Please verify that the comma separation in the cluster list is correctly interpreted by SLURM.
343-343
: Additional Custom Job Configuration
The section explaining the use of theslurm_extra
resource to pass custom flags tosbatch
is a practical addition.
354-354
: Explanation of Extra SLURM Directives via slurm_extra
This text details how to specify additional parameters for job submissions.
369-369
: New "Software Recommendations" Section Heading
This new section helps guide users on deployment practices and managing dependencies using Conda and environment modules.
371-371
: Subsection: Conda Usage Recommendations
The advice on Conda-based deployment is clear and contextually relevant.
386-386
: Clarification on Environment Modules
The sentence explaining how environment modules trigger a module load is now clearer. Confirm that this language matches your cluster’s module management practices.
416-416
: Guidance for Setting Up a Global Profile
The instructions for establishing a global or individual profile are well articulated.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
416-416: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
419-419
: Usage of the Default Profile via Environment Variable
The explanation on setting and usingSNAKEMAKE_PROFILE
is helpful and straightforward.
421-421
: Introduction to the Sample Profile Configuration
The text prefaces the configuration with a clear explanation, making it easy for users to follow.
423-434
: Profile YAML Configuration Example
The YAML code block is well formatted. Please double-check the syntax and spacing to ensure full compatibility with the YAML parser.
437-437
: Explanation of Profile Configuration Components
Provides a clear breakdown of what each configuration option does.
438-443
: Detailed Breakdown of Profile Settings
The explanation of options likeexecutor
,latency-wait
, and storage prefixes is clear. Consider adding brief inline comments in the YAML for added clarity.🧰 Tools
🪛 LanguageTool
[uncategorized] ~439-~439: Loose punctuation mark.
Context: ... not needed anymore. -latency-wait: 5
: Sets a 5-second latency wait to accommo...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~440-~440: Loose punctuation mark.
Context: ...delays. -default-storage-provider: fs
: Utilizes the file system storage plugin...(UNLIKELY_OPENING_PUNCTUATION)
445-445
: File System Storage Plugin Usage Note
This reminder about the file system storage plugin is both useful and clear.
449-449
: Log Files Section Heading
The heading aptly introduces the section on managing SLURM log files.
451-451
: Explanation of SLURM Log Handling Behavior
The description about how logs are managed (deleted for successful jobs, retained for failures) is clearly stated.
453-453
: Log Deletion and Retention Guidelines
This passage effectively explains the rationale behind removing successful log files and retaining failed ones.
455-455
: Instructions for Redirecting SLURM Log Files
The guidance on using the--slurm-logdir
flag and storing logs centrally is detailed and practical.
457-459
: SLURM Log Directory YAML Example
The YAML snippet provided is clear. Ensure that users replace<username>
appropriately.
461-461
: Emphasis on Username Replacement
The note reminding users to replace<username>
is clear and necessary.
463-463
: Retries Section Heading
The heading introduces the topic of retries effectively.
465-465
: Explanation of Job Retry Mechanisms
The text clarifies that Snakemake can automatically retry jobs and resume workflows, which is very useful for cluster operations.
467-467
: Subheading for Retrying Failed Jobs
A clear subheading that signals how users should approach job failures.
469-469
: Usage of the--retries
Option
The explanation of how to invoke automatic retries is concise and correct.
471-471
: Resuming Incomplete Jobs
The instructions on using the--rerun-incomplete
flag (or its shorthand) are clear and helpful.
475-475
: Subheading for Automatic Job Requeuing
This heading clearly indicates the discussion of SLURM’s job requeue feature.
477-477
: Explanation of SLURM Job Requeuing
The detailed explanation on how job requeuing works and its benefits is very informative.
491-491
: Recommendation for Using--slurm-requeue
Clear guidance is provided for clusters where job requeuing is not enabled by default.
497-497
: Introduction to Dynamic Parameterization
This section introduces dynamic adjustment of runtime and memory based on input size, which is a good strategy to optimize resource usage.
499-499
: Dynamic Parameterization Section Heading
The heading clearly signals the start of a discussion on adjusting job parameters dynamically.
503-503
: Subheading for Adjusting Memory Requirements
This heading is clear and sets the context for discussing dynamic memory adjustments.
505-505
: Dynamic Resources Documentation Link
The inline link to Snakemake documentation on dynamic resources is valuable.
507-507
: Subheading for Runtime Adjustments
The heading clearly indicates the focus on runtime modifications.
509-509
: Note on Runtime Adjustment Options
The explanation of how runtime adjustments can be made in a Snakefile is clear and helpful.
522-522
: Alternative Approach via Workflow Profile
The note that runtime adjustments can alternatively be set in a workflow profile is a useful tip.
531-531
: Final Note on Sensible Dynamic Configuration Settings
This closing remark on dynamic parameterization reinforces the importance of using parallel execution and global profiles to avoid I/O contention.
534-534
: Section on Nesting Jobs
The heading clearly introduces the discussion on running Snakemake within an active SLURM job and the potential issues that may arise.
536-536
: Warning on Running Snakemake Within a SLURM Job
The detailed warning about the unpredictable behavior when nesting jobs is very informative and essential for users in such environments.
538-538
: Summary Section Heading
The “Summary:” heading effectively signals the consolidation of key command line examples.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
538-538: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
542-542
: Introduction to a Consolidated Command Line Example
The text briefly explains what a typical command line for executing workflows might look like.
549-549
: Frequently Asked Questions Section Heading
The introduction of an FAQ section is a strong addition that can help address common user concerns.
551-551
: FAQ on Running Snakemake on the Login Node
The FAQ question is clear and directly addresses common concerns about resource usage on login nodes.
555-555
: Profiling CPU Time on the Login Node
The text explains how to use/usr/bin/time -v
to assess Snakemake’s CPU usage, which is very practical.
561-561
: Analyzing Resource Usage Statistics
The guidance on sharing CPU time statistics with administrators provides valuable insight for performance tuning.
563-563
: Introduction to the Metrics Table
The sentence introducing the data table of measurements is clear.
567-567
: Workflow Metrics Table Row
The presented statistics and links are clear. Ensure that the numbers and percentages are accurate and up to date.
569-569
: Call to Action for Submitting Similar Statistics
Encourages community participation effectively, and the links now adhere to standard Markdown syntax.
571-571
: FAQ on Administrator Restrictions for Login Node Usage
The FAQ subheading is clear and concise.
573-573
: Reiterated Warning for Running Snakemake Within a SLURM Job
The repetition reinforces caution and ensures users are aware of potential configuration pitfalls when nesting jobs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (9)
docs/further.md (9)
3-3
: Plugin Log Management Explanation
The explanation of how the plugin submits Snakemake as a job and then deletes the redundant SLURM log file is clear. As a minor nitpick, you might consider rephrasing “the SLURM log file will duplicate the output” to “the SLURM log file mirrors the output of the corresponding rule” for added clarity.
138-138
: Advanced MPI Configuration Options
Mentioning the use of theslurm_extra
parameter to pass additional SLURM directives is a useful tip. Including an explicit example here (if space permits) could further benefit readers.
296-298
: Using Configuration Profiles for Resource Specifications
The text describing the benefits of using profiles is solid. A minor nitpick: consider rephrasing for smoother flow (e.g. “A more flexible approach to defining resource specifications is by using Snakemake profiles” instead of “manage resource specifications”).🧰 Tools
🪛 LanguageTool
[uncategorized] ~298-~298: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
373-373
: Conda Installation Instructions – Grammar Improvement
The sentence could be made clearer with improved punctuation and wording. For example, consider applying this diff:-In this case pointing the installation to different file system with `--conda-prefix /other/filesystem` might be a solution. +In this case, pointing the installation to a different file system using `--conda-prefix /other/filesystem` might be a solution.🧰 Tools
🪛 LanguageTool
[uncategorized] ~373-~373: A comma might be missing here.
Context: ...table/snakefiles/deployment.html). On a cluster sometimes a file system other than `HOM...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~373-~373: Consider inserting a comma after an introductory phrase for better readability.
Context: ... be indicated (e.g. because of quotas). In this case pointing the installation to different ...(IN_THAT_CASE_COMMA)
[uncategorized] ~373-~373: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...(AI_EN_LECTOR_MISSING_DETERMINER_A)
386-386
: Environment Modules Loading Clarification
In the sentence “This will trigger amodule load bio VinaLC
immediately before to execution,” remove the extraneous “to” for clarity:- module load bio VinaLC` immediately before to execution. + module load bio VinaLC` immediately before execution.
416-416
: Global Profile Heading Formatting
Remove the trailing colon from the “#### Setting Up a Global Profile:” heading to comply with Markdown style guidelines:-#### Setting Up a Global Profile: +#### Setting Up a Global Profile🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
416-416: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
418-419
: Profile Directory Instructions – Punctuation
Consider inserting a comma after the introductory clause for clarity:-If cluster administrators did not set up a global profile at `/etc/xdg/snakemake` users can opt for individual profiles. +If cluster administrators did not set up a global profile at `/etc/xdg/snakemake`, users can opt for individual profiles.
501-501
: Dynamic Parameterization Phrasing
A slight rewording can improve readability:-Using dynamic parameterization we can react on different inputs and prevent our HPC jobs from failing. +Using dynamic parameterization, we can react to different inputs and prevent our HPC jobs from failing.🧰 Tools
🪛 LanguageTool
[uncategorized] ~501-~501: A comma might be missing here.
Context: ...Dynamic Parameterization Using dynamic parameterization we can react on different inputs and pr...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~501-~501: The preposition “to” seems more likely in this position.
Context: ...g dynamic parameterization we can react on different inputs and prevent our HPC jo...(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
538-538
: Summary Heading Formatting
Remove the trailing colon from the “### Summary:” heading for consistency:-### Summary: +### Summary🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
538-538: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/further.md
(10 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/further.md
[typographical] ~167-~167: Two consecutive dots
Context: ...ust be specified as a numerical value. .. note:: Internally, Snakemake knows the ...
(DOUBLE_PUNCTUATION)
[typographical] ~206-~206: Two consecutive dots
Context: ...our CPU cores for each GPU requested. .. note:: If cpus_per_gpu
is set to a va...
(DOUBLE_PUNCTUATION)
[uncategorized] ~298-~298: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...
(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
[uncategorized] ~373-~373: A comma might be missing here.
Context: ...table/snakefiles/deployment.html). On a cluster sometimes a file system other than `HOM...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~373-~373: Consider inserting a comma after an introductory phrase for better readability.
Context: ... be indicated (e.g. because of quotas). In this case pointing the installation to different ...
(IN_THAT_CASE_COMMA)
[uncategorized] ~373-~373: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...
(AI_EN_LECTOR_MISSING_DETERMINER_A)
[uncategorized] ~439-~439: Loose punctuation mark.
Context: ... not needed anymore. - latency-wait: 5
: Sets a 5-second latency wait to accommo...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~440-~440: Loose punctuation mark.
Context: ...delays. - default-storage-provider: fs
: Utilizes the file system storage plugin...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~447-~447: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually, you will be ab...
(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[uncategorized] ~501-~501: A comma might be missing here.
Context: ...Dynamic Parameterization Using dynamic parameterization we can react on different inputs and pr...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~501-~501: The preposition “to” seems more likely in this position.
Context: ...g dynamic parameterization we can react on different inputs and prevent our HPC jo...
(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
[style] ~553-~553: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...
(CONSULT_WITH)
🪛 markdownlint-cli2 (0.17.2)
docs/further.md
116-116: Dollar signs used before commands without showing output
null
(MD014, commands-show-output)
416-416: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
538-538: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: testing
🔇 Additional comments (35)
docs/further.md (35)
1-1
: Section Title Update: "How this Plugin works"
The new section title is concise and user-friendly, immediately clarifying the content’s focus.
5-5
: Remote Executors & Memory Footprint
The description about remote executors and the dependency of memory requirements on functionalities (e.g. rules with a run directive) is well detailed.
7-7
: New Usage Hints Subsection
The introduction of the "#### Usage Hints" section clearly delineates installation and setup tips in a dedicated area.
9-9
: Installation Instructions Clarity
The instructions to install the plugin via conda (and the recommendation to install the related plugins) are informative and straightforward.
11-11
: Reporting Bugs and Feature Requests
The updated section now uses standard Markdown link formatting and provides clear guidance on where to report issues.
17-18
: SLURM Account and Partition Explanation
The text concisely explains the roles of SLURM’s account and partition. This clarity aids users in understanding resource allocation.
34-34
: Configuration Profile Recommendation
Encouraging users to persist resource settings via a configuration profile is a best practice for portability.
36-36
: Job Status Check Interval
The explanation regarding the 40‑second wait and how to adjust it is useful. You might consider explicitly mentioning that this is the default behavior.
38-38
: SMP Jobs Section Title
The revised heading “### Configuring SMP Jobs in Snakemake with the SLURM Executor Plugin” is descriptive and sets clear expectations.
40-40
: SMP Job Explanation and Example
The detailed explanation of how SMP jobs work—including the reference to shared memory—is well written and the accompanying code example is clear.
51-51
: Explanation ofcpus_per_task
This line effectively clarifies that Snakemake treatscpus_per_task
as an alternative tothreads
and that resource settings here take precedence.
53-53
: Cluster-Specific Workflow Profile Advice
The advice to avoid hard-coding resource parameters and to use a cluster-specific configuration profile is solid and well explained.
86-86
: MPI Support Overview
The explanation of how the SLURM executor supports MPI jobs—with a recommendation to usesrun
—is clear and thorough.
105-109
: MPI Configuration Bullet Points
The bullet-point list detailing how MPI tasks are defined (for both pure MPI and hybrid models) is organized and helpful.
119-119
: MPI Resource Specifications Heading
The “#### Resource Specifications for MPI Jobs” heading is clear and signals that detailed configuration guidance follows.
135-137
: Hybrid MPI Configuration Details
The explanation of allocating MPI tasks—and the provisions for hybrid applications using both MPI and multi-threading—is comprehensive and user-friendly.
142-142
: GPU Jobs Introduction
The introduction to integrating GPU resources is clear and sets proper expectations for the rest of the section.
144-144
: Specifying GPU Resources Heading
The header “#### Specifying GPU Resources in Snakemake” correctly prepares the reader for detailed examples.
146-146
: GPU Request Explanation
The explanation of using thegpu
resource (and optionally the GPU model) is succinct and helpful.
160-164
: GPU Resource Mapping to SLURM Flags
The breakdown detailing how thegpu
resource translates to SLURM’s--gpus
flag is excellent and very informative.
170-172
: Alternative GPU Specification Method using gres
Offering an alternative approach using thegres
resource adds flexibility and is clearly explained.
188-190
: CPU Allocation per GPU Considerations
The section on ensuring enough CPU resources per GPU is clear, emphasizing the importance of proper resource allocation.
205-205
: Note oncpus_per_gpu
Behavior
The explanatory note on how Snakemake handles non-positivecpus_per_gpu
values is precise and useful.
209-209
: Workflow Profile for GPU Jobs Heading
The “#### Sample Workflow Profile for GPU Jobs” header effectively signals the upcoming practical configuration example.
235-235
: Profile Benefits Summary
The summary that follows is succinct and reinforces the organizational benefits of using configuration profiles.
237-239
: Important Note on GPU Resource Request
The note clearly explains the tradeoffs between usinggpu
versusgres
and the lack of distinction between GPU model and manufacturer in SLURM.
243-243
: Running Jobs Locally Section
The guidance for identifying tasks suited for local execution is clear and practical.
245-245
: Explanation of the localrules Directive
The description of how to designate rules for local execution usinglocalrules
is straightforward and clear.
257-271
: Mapping Snakemake Resources to SLURM Parameters
The bullet-point list that maps specific Snakemake resources to their corresponding SLURM flags is detailed and well structured.
292-292
: Memory Flags Exclusivity Reminder
The explanation of the mutual exclusivity between SLURM’s--mem
and--mem-per-cpu
is concise and helps prevent configuration errors.
551-555
: FAQ on Running Snakemake on the Login Node
The FAQ explanation is detailed and outlines the practical considerations well.🧰 Tools
🪛 LanguageTool
[style] ~553-~553: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...(CONSULT_WITH)
563-563
: Measurement Table Formatting
The table of measurements is well-organized. In future updates, ensure that the table’s pipe alignment remains consistent for readability.
569-569
: Call-to-Action for Contributing Statistics
The invitation to run/usr/bin/time -v snakemake ...
and submit statistics via an issue is clear and uses proper Markdown link syntax.
571-571
: FAQ Heading for Administrative Restrictions
The heading “#### My Administrators do not let me run Snakemake on a Login Node” is clear and addresses a common concern.
573-575
: Final FAQ Explanation on Job Submission Issues
The guidance on how to proceed if running Snakemake within a SLURM job leads to issues is informative and actionable.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (10)
docs/further.md (10)
35-45
: Command-Line and Configuration Persistence Clarity.
The details on overriding default resource values and persisting settings through a configuration profile are well articulated. A minor nitpick: consider inserting a comma after introductory phrases (e.g., “for example,”) to further polish the text.🧰 Tools
🪛 LanguageTool
[uncategorized] ~35-~35: A comma might be missing here.
Context: ...URM partition> ``` If individual rules require for example a different partition, you ...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
🪛 markdownlint-cli2 (0.17.2)
39-39: Dollar signs used before commands without showing output
null(MD014, commands-show-output)
62-68
: Resource Profile Guidance and Consistency.
The recommendation to create a cluster-specific workflow profile is well stated. However, note that this section instructs users to use the--workflow-profile
option while later documentation refers to--profile
. Please standardize the option name for consistency.
162-193
: Comprehensive GPU Resource Overview.
This section thoroughly describes how GPU resources can be requested in Snakemake—both via thegpu
resource and the alternativegres
method. There is a minor formatting concern with the note directive (the “.. note::” syntax); please verify that the reStructuredText notation is intentional.🧰 Tools
🪛 LanguageTool
[typographical] ~191-~191: Two consecutive dots
Context: ...ust be specified as a numerical value. .. note:: Internally, Snakemake knows the ...(DOUBLE_PUNCTUATION)
335-361
: Streamlined Configuration Profiles.
This part explains how configuration profiles can centralize resource settings for enhanced portability. A small improvement: consider rephrasing “a more flexible approach to manage” as “a more flexible approach for managing” resource specifications. Additionally, please resolve the earlier noted inconsistency in the profile option naming.🧰 Tools
🪛 LanguageTool
[uncategorized] ~337-~337: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
399-403
: Flexibility with Custom SLURM Options.
The instructions for using theslurm_extra
resource to pass additional flags tosbatch
are well crafted. A minor nitpick: rephrase “immediately before to execution” to “immediately prior to execution” for better readability.
417-422
: Detailed Conda Deployment Guidance.
The section on using conda for software deployment is thorough. One suggestion: in line 421, add the article “a” before “different file system” and consider a brief pause (a comma) after the introductory clause for improved flow.🧰 Tools
🪛 LanguageTool
[uncategorized] ~420-~420: A comma might be missing here.
Context: ...ml#integrated-package-management). On a cluster sometimes a file system other than `HOM...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~420-~420: Consider inserting a comma after an introductory phrase for better readability.
Context: ...icated (for example because of quotas). In this case pointing the installation to different ...(IN_THAT_CASE_COMMA)
[uncategorized] ~421-~421: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...(AI_EN_LECTOR_MISSING_DETERMINER_A)
426-436
: Environment Modules Usage Clarity.
The guidance on employing HPC environment modules and the example using--sdm env-modules
clearly illustrate the process. A minor rewording in line 436 (e.g. “immediately prior to execution” instead of “immediately before to execution”) would enhance clarity.🧰 Tools
🪛 LanguageTool
[uncategorized] ~436-~436: “to” seems less likely than “the”.
Context: ...ule load bio VinaLC` immediately before to execution. Note, that - environment ...(AI_HYDRA_LEO_CP_TO_THE)
🪛 markdownlint-cli2 (0.17.2)
429-429: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
445-468
: Robust Job Monitoring Details.
The section explaining how to query job status withsacct
andsqueue
is detailed and practical. One small suggestion: ensure that “human readable” is hyphenated as “human‑readable” to conform to standard usage.🧰 Tools
🪛 LanguageTool
[misspelling] ~446-~446: This word is normally spelled with a hyphen.
Context: ... strain on the batch system's database. Human readable information is stored in the comment of...(EN_COMPOUNDS_HUMAN_READABLE)
484-506
: Clear Global Profile Configuration.
The example YAML configuration for global profiles is well formatted and informative. One minor suggestion from markdownlint: consider removing trailing punctuation in header titles (e.g., “### Summary:” → “### Summary”) if required by your style guide.🧰 Tools
🪛 LanguageTool
[uncategorized] ~501-~501: Loose punctuation mark.
Context: ... not needed anymore. -latency-wait: 5
: Sets a 5-second latency wait to accommo...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~502-~502: Loose punctuation mark.
Context: ...delays. -default-storage-provider: fs
: Utilizes the file system storage plugin...(UNLIKELY_OPENING_PUNCTUATION)
578-589
: Dynamic Parameterization Insights.
The section on dynamic parameterization is insightful for adapting runtime parameters based on input variability. A minor improvement would be to insert a comma after “Using dynamic parameterization” to enhance readability.🧰 Tools
🪛 LanguageTool
[uncategorized] ~580-~580: A comma might be missing here.
Context: ...Dynamic Parameterization Using dynamic parameterization we can react on different inputs and pr...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~580-~580: The preposition “to” seems more likely in this position.
Context: ...g dynamic parameterization we can react on different inputs and prevent our HPC jo...(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/further.md
(8 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/further.md
[uncategorized] ~35-~35: A comma might be missing here.
Context: ...URM partition> ``` If individual rules require for example a different partition, you ...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[typographical] ~191-~191: Two consecutive dots
Context: ...ust be specified as a numerical value. .. note:: Internally, Snakemake knows the ...
(DOUBLE_PUNCTUATION)
[typographical] ~236-~236: Two consecutive dots
Context: ...four CPU cores for each GPU requested. .. note:: If cpus_per_gpu
is set to a va...
(DOUBLE_PUNCTUATION)
[uncategorized] ~337-~337: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...ifications A more flexible approach to manage resource specifications is by using Sna...
(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
[uncategorized] ~420-~420: A comma might be missing here.
Context: ...ml#integrated-package-management). On a cluster sometimes a file system other than `HOM...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[formatting] ~420-~420: Consider inserting a comma after an introductory phrase for better readability.
Context: ...icated (for example because of quotas). In this case pointing the installation to different ...
(IN_THAT_CASE_COMMA)
[uncategorized] ~421-~421: You might be missing the article “a” here.
Context: ... this case pointing the installation to different file system with `--conda-prefix /other...
(AI_EN_LECTOR_MISSING_DETERMINER_A)
[uncategorized] ~436-~436: “to” seems less likely than “the”.
Context: ...ule load bio VinaLC` immediately before to execution. Note, that - environment ...
(AI_HYDRA_LEO_CP_TO_THE)
[misspelling] ~446-~446: This word is normally spelled with a hyphen.
Context: ... strain on the batch system's database. Human readable information is stored in the comment of...
(EN_COMPOUNDS_HUMAN_READABLE)
[uncategorized] ~501-~501: Loose punctuation mark.
Context: ... not needed anymore. - latency-wait: 5
: Sets a 5-second latency wait to accommo...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~502-~502: Loose punctuation mark.
Context: ...delays. - default-storage-provider: fs
: Utilizes the file system storage plugin...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~510-~510: You might be missing the article “an” here.
Context: ... -out in- and output files. ==This is ongoing development. Eventually, you will be ab...
(AI_EN_LECTOR_MISSING_DETERMINER_AN)
[uncategorized] ~580-~580: A comma might be missing here.
Context: ...Dynamic Parameterization Using dynamic parameterization we can react on different inputs and pr...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~580-~580: The preposition “to” seems more likely in this position.
Context: ...g dynamic parameterization we can react on different inputs and prevent our HPC jo...
(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
[style] ~637-~637: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...
(CONSULT_WITH)
🪛 markdownlint-cli2 (0.17.2)
docs/further.md
32-32: Dollar signs used before commands without showing output
null
(MD014, commands-show-output)
39-39: Dollar signs used before commands without showing output
null
(MD014, commands-show-output)
134-134: Dollar signs used before commands without showing output
null
(MD014, commands-show-output)
474-474: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
620-620: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
🔇 Additional comments (18)
docs/further.md (18)
1-8
: Solid Overarching Overview.
The updated section title “How this Plugin works” and the introductory paragraphs provide a clear explanation of the plugin’s operation on HPC clusters. The messaging is concise and informative.
10-21
: Clear Usage Hints and Reporting Guidelines.
The “Usage Hints” and “Reporting Bugs and Feature Requests” sections now use standard Markdown link formatting and offer practical installation and reporting instructions. The clarity in directing users to the appropriate GitHub repositories is excellent.
25-27
: Concise Account and Partition Explanation.
The explanation of how SLURM uses an account and partition is succinct and emphasizes platform independence. This ensures users understand that these settings can remain external to their Snakefiles.
47-50
: Enhanced Explanation for SMP Jobs.
The section discussing SMP (Shared Memory Processing) jobs very clearly delineates between single-core and multithreaded applications. The practical description helps the user understand how resources are allocated.
70-86
: Clear YAML Configuration Example.
The YAML code snippet demonstrating the setting of default resources alongside rule‑specific overrides is clear and easy to follow. This example significantly enhances the documentation’s usability.
101-107
: Thorough MPI Job Introduction.
The section on MPI jobs effectively explains the use of SLURM’ssrun
for launching MPI processes, making it straightforward for users setting up distributed tasks.
137-147
: Detailed MPI Resource Specification.
The bullet‐list outlining the allocation of MPI tasks and how to specify hybrid configurations (using bothtasks
andcpus_per_task
) is clear and well organized.
196-274
: Robust GPU Allocation Options.
The alternative method using thegres
resource and the detailed instructions on CPU allocation per GPU are very well presented. The examples are clear and offer excellent practical guidance for diverse cluster configurations.🧰 Tools
🪛 LanguageTool
[typographical] ~236-~236: Two consecutive dots
Context: ...four CPU cores for each GPU requested. .. note:: Ifcpus_per_gpu
is set to a va...(DOUBLE_PUNCTUATION)
276-284
: Local Job Execution Guidance.
The instructions on using the localrules directive to designate specific rules for local execution are concise and clear, offering users a practical tip to optimize workflow performance.
288-308
: Effective Mapping of Resources to SLURM Parameters.
The section that maps Snakemake resource definitions to corresponding SLURM flags is detailed and logically structured. The bullet-list format aids understanding and makes it easier to reference.
310-324
: Clear Rule Definition Example.
The provided Snakemake rule example effectively demonstrates how to request specific SLURM resources. The inclusion of a real-world command-line snippet adds to its clarity.
327-333
: Critical Considerations on Memory Parameters.
Emphasizing the mutual exclusivity of SLURM’s--mem
and--mem-per-cpu
flags—as well as advising against hardcoding cluster-specific resources—is essential. This section communicates these points clearly.
369-394
: Comprehensive Multicluster Support Explanation.
The documentation effectively describes how to assign rules to specific clusters using thecluster
resource flag and provides an illustrative YAML example. This guidance will certainly aid users with multicluster environments.
471-481
: Streamlined Profiles Overview.
This section concisely explains the benefits and setup of Snakemake profiles. The instructions are clear; just verify that the command-line option used here is consistent with what is referenced elsewhere in the documentation.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
474-474: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
513-527
: Comprehensive Log Files Management.
The section on SLURM log management offers extensive and practical guidance on how to control log file retention and redirection. This level of detail is very helpful for administrators managing disk space.
536-574
: Thorough Explanation on Job Retrying and Requeuing.
The documentation clearly explains how to leverage Snakemake’s retry mechanism and SLURM’s requeue feature to handle job failures. The command examples are clear and actionable.
615-618
: Caution on Nesting Jobs.
The warning regarding running Snakemake within an active SLURM job is concise and effectively alerts users to potential pitfalls in such setups.
630-663
: Detailed FAQ Section.
The FAQ segment is comprehensive and addresses common concerns thoroughly. While the explanations are clear, there is some repetition regarding job management warnings; consider streamlining these parts to maintain brevity.🧰 Tools
🪛 LanguageTool
[style] ~637-~637: This phrase is redundant. Consider writing “consult”.
Context: ... computational tasks. It's advisable to consult with your cluster's support team to understa...(CONSULT_WITH)
I'll merge this for now, after doing some initial formatting changes. So we have then have a separate and slightly cleaner diff on a next pull request. |
🤖 I have created a release *beep* *boop* --- ## [1.1.0](v1.0.1...v1.1.0) (2025-03-14) ### Features * tolerant status checks ([#232](#232)) ([cb20135](cb20135)) ### Bug Fixes * trying syntax fix ([#235](#235)) ([5e591ae](5e591ae)) ### Documentation * rewrite of the documentation ([#219](#219)) ([7d0b44c](7d0b44c)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Introduced tolerant status checks to improve functionality. - **Bug Fixes** - Resolved a syntax issue. - **Documentation** - Rewrote documentation for enhanced clarity. - **Chores** - Updated the release version to 1.1.0. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
see title
Summary by CodeRabbit