spesim Package Review

Task A3

Author

Affiliation

Published

2026/06/15

Assignment: professional review of the spesim package

In this assignment you will work in your fixed group of three to review the spesim package as professional ecologists with practical interest in software design and engineering. Your task is to assess whether spesim functions as a useful, accessible, and reliable pedagogical tool for BCB743. It is not your job to advertise the package or to complain about it, although actionable feedback will be appreciated and will assist the software developer (me) to improve it where you deem it necessary.

The review must be professional in tone, evidence-based in method, and constructive in its recommendations. Treat the package as a real teaching product being considered for adoption in a quantitative ecology module, so take this task seriously. You should ask whether a BCB743 student can install it, understand its purpose, run its examples, connect the outputs to ecological theory, and use it to learn the methods taught in the module.

This assignment is one of the three formally assessed BCB743 tasks. It will contribute between 20% and 40% to your final module mark, depending on the weighting declaration you submit.

Review brief

Your group must evaluate spesim in relation to the aims of BCB743. The package should be judged as both ecological teaching material and scientific software.

Your review should assess:

Pedagogical fit: whether the package helps students learn BCB743 concepts, including species-abundance distributions, environmental gradients, ordination, dissimilarity, constrained analysis, clustering, spatial structure, and sampling design. Where did it help your understanding of the module content, and where did it complicate things? What are the gaps? How does it compare to other similar software?
Usability: whether installation, setup, configuration, function names, examples, outputs, and error messages are clear enough for the intended audience. If you deem it difficult to use, why so? And what would you suggest changing to improve usability? Remember, it is R software, so it is meant to be command-line driven.
Accessibility: whether the documentation, vignettes, examples, and terminology make the package usable by students who are still developing confidence in R. Where are the obvious gaps where I can spend time improving the function documentation?
Scientific and ecological clarity: whether the simulations are explained in a way that connects the generated data to ecological theory and to the limitations of synthetic data. What ecological theory does it cover well, and where does it do less well?
Software design: whether the package structure, function interfaces, defaults, returned objects, messages, examples, and reproducibility choices support reliable use.
Reliability: whether the documented examples run as described on your machines, whether outputs are reproducible when seeds are set, and whether failures are understandable.
Value for BCB743: whether the package should be used in the module as-is, used with changes, used only for selected topics, or not used until specific issues are addressed.

The review must be based on direct testing. Do not rely only on reading the documentation.

Minimum testing expectations

Each group must install the package from GitHub, work through the spesim chapter, and test a representative set of package material from the documentation site. At minimum, your group should test:

installation from a clean R session
the minimal example in the BCB743 spesim chapter
the introductory vignette or start-here material
one environmental-gradient example
one quadrat-placement example
one point-process or spatial-structure example
one constrained-ordination or BCB743-linked example

However, better marks can be had from developing and following a structured review methodology: write out the review approach, method, rationale, aims, objectives, and run it as you would a thorough scientific study. This will get you marks >70%.

Record the operating system, R version, package version, and date of testing. If a test fails, record the exact command, error message, session information, and the steps needed to reproduce the failure.

You are welcome to come to me any time and request bug fixes, but for me to fix them, I will require that you give me reproducible examples.

Professional stance

Write as professional reviewers. That means:

knowing the playing field: know what other packages exist that promise similar functions, what their strengths and weaknesses are, and how spesim ranks relative to these
separate evidence from opinion
identify strengths as carefully as weaknesses
distinguish defects, limitations, missing documentation, and reasonable design choices
describe the likely effect of each issue on a BCB743 student
prioritise recommendations by severity and educational consequence
make recommendations that could realistically be acted on by a package maintainer or course coordinator
suggest places where the spesim package can formally be integrated into the BCB743 curriculum (specific chapters and purposes)

A useful review does not need to find many faults. It needs to show careful judgement. A small number of well-evidenced issues, each tied to a consequence for teaching or usability, is stronger than a long list of minor preferences.

Suggested report structure

You may adapt the structure if your argument requires it, but most reports should include:

Executive summary: your main judgement on whether spesim is ready for BCB743 use, and under what conditions
Scope of review: what you tested, your testing rationale and approach (maybe with aims, objectives, and/or hypotheses), what you did not test, and the computing environments used
Pedagogical assessment: how well the package supports the learning outcomes of BCB743
Usability assessment: installation, first use, function interfaces, configuration, examples, outputs, and error messages
Documentation assessment: whether the chapter, package website, vignettes, examples, and terminology are clear and complete enough for students
Reproducibility and reliability: whether examples run, whether outputs can be reproduced, and whether failures are diagnosable
Issue register: a prioritised table of findings, each with evidence, consequence, severity, and recommendation
Future functionality: features that would make spesim more useful for BCB743 or for ecological teaching more broadly. These may include tools for simulating real geographically linked landscapes, known biodiversity structures in systems such as fynbos, arbitrary mapped landscapes supplied by the user, river networks, coastal strips, habitat mosaics, or other spatial settings where the ecological structure is known or can be specified. Rank these proposals from low to high priority, and explain the ecological use case, teaching value, and likely difficulty of implementation.
Recommendations: changes you would make before using the package in teaching, separated into urgent, useful, and optional improvements; if useful to BCB743, how you would integrate it as a teaching tool (what theory/prac needs does spesim address?)
Conclusion: your final recommendation for BCB743 adoption

Submission requirements

Submit:

a PDF review report
the Quarto source file for the report
any scripts used to test examples or reproduce issues
an issue register as a table in the report, and optionally as a separate CSV file
relevant screenshots only where they provide evidence of a usability or documentation issue
a short author-contribution statement explaining what each group member contributed
a brief AI-use disclosure if generative AI tools were used

The Quarto file must render cleanly. Code used for testing should be reproducible or accompanied by enough information for me to rerun the test. All claims about the package must be tied to direct evidence, package documentation, or relevant BCB743 learning outcomes.

Assessment criteria

This assignment will be formally assessed and will contribute between 20% and 40% to your final BCB743 mark, depending on the weighting declaration you submit for the three assessed assignments. The three declared weights for Task A1, Task A2, and Task A3 must add to 100%, and no single task may carry more than 40%. If you do not submit a valid declaration by 17 July, the three tasks will be weighted equally.

Indicative mark bands:

90-100%: professional-quality review. The report is evidence-based, technically careful, pedagogically insightful, and immediately useful to a maintainer or course coordinator. It tests the package thoroughly, distinguishes issue severity, and makes prioritised recommendations that are specific enough to act on.
80-89%: excellent review. The report tests the package well, links usability to BCB743 teaching needs, identifies important strengths and weaknesses, and gives clear recommendations, but may need stronger prioritisation, deeper software-design insight, or fuller reproducibility evidence.
70-79%: good to very good review. The report covers the main testing areas and makes sensible judgements, but the evidence base, issue register, pedagogical interpretation, or software-design analysis is less developed than in the higher bands.
60-69%: competent review. The package is tested and the report identifies some useful issues, but the analysis is more descriptive than evaluative, or the recommendations are too general to guide improvement.
50-59%: adequate but limited review. The report shows basic engagement with the package, but testing is narrow, evidence is thin, reproducibility details are incomplete, or the link to BCB743 teaching is weak.
Below 50%: incomplete, poorly evidenced, technically unreliable, unprofessional in tone, difficult to reproduce, or not focused on the package’s role in BCB743.

The assessment will consider:

Professional judgement: the report must read like a serious technical and pedagogical review, not a user diary or informal opinion piece.
Testing depth: conclusions must be based on direct testing across installation, examples, vignettes, outputs, documentation, and reproducibility.
Pedagogical insight: the review must assess whether the package helps teach the concepts and methods that BCB743 is designed to develop.
Software-design insight: the review must consider function interfaces, defaults, returned objects, messages, documentation structure, reproducibility, and maintainability from the perspective of an ecological user.
Evidence and traceability: findings must be supported by commands, outputs, screenshots where useful, documentation references, or clear observations from testing.
Recommendations: suggested changes must be specific, prioritised, realistic, and linked to their likely effect on student learning or package reliability.
Writing and structure: the report must be clear, concise, proofread, well organised, and professional.
Collaboration: all three group members are responsible for the full review. The submitted work should show shared intellectual ownership rather than three disconnected sections.

Reuse

CC BY-NC-SA 4.0

Citation

BibTeX citation:

@online{smit2026,
  author = {Smit, A. J.},
  title = {Spesim {Package} {Review}},
  date = {2026-06-15},
  url = {https://tangledbank.netlify.app/BCB743/tasks/Task_A3.html},
  langid = {en}
}

For attribution, please cite this work as:

Smit AJ (2026) spesim Package Review. https://tangledbank.netlify.app/BCB743/tasks/Task_A3.html.

--- title: "spesim Package Review" subtitle: "Task A3" --- ```{r code-brewing-opts, echo=FALSE} knitr::opts_chunk$set( comment = "R>", warning = FALSE, message = FALSE, fig.width = 4.5, fig.height = 2.625, out.width = "75%", fig.asp = NULL, # control via width/height dpi = 300 ) ggplot2::theme_set( ggplot2::theme_minimal(base_size = 8) ) ggplot2::theme_set( ggplot2::theme_bw(base_size = 8) ) ``` ## Assignment: professional review of the spesim package In this assignment you will work in your fixed group of three to review the [`spesim`](../spesim.qmd) package as professional ecologists with practical interest in software design and engineering. Your task is to assess whether `spesim` functions as a useful, accessible, and reliable pedagogical tool for BCB743. It is not your job to advertise the package or to complain about it, although actionable feedback will be appreciated and will assist the software developer (me) to improve it where you deem it necessary. The review must be professional in tone, evidence-based in method, and constructive in its recommendations. Treat the package as a real teaching product being considered for adoption in a quantitative ecology module, so take this task seriously. You should ask whether a BCB743 student can install it, understand its purpose, run its examples, connect the outputs to ecological theory, and use it to learn the methods taught in the module. This assignment is one of the three formally assessed BCB743 tasks. It will contribute between 20% and 40% to your final module mark, depending on the weighting declaration you submit. ### Review brief Your group must evaluate `spesim` in relation to the aims of BCB743. The package should be judged as both ecological teaching material and scientific software. Your review should assess: - **Pedagogical fit:** whether the package helps students learn BCB743 concepts, including species-abundance distributions, environmental gradients, ordination, dissimilarity, constrained analysis, clustering, spatial structure, and sampling design. Where did it help your understanding of the module content, and where did it complicate things? What are the gaps? How does it compare to other similar software? - **Usability:** whether installation, setup, configuration, function names, examples, outputs, and error messages are clear enough for the intended audience. If you deem it difficult to use, why so? And what would you suggest changing to improve usability? Remember, it is R software, so it is meant to be command-line driven. - **Accessibility:** whether the documentation, vignettes, examples, and terminology make the package usable by students who are still developing confidence in R. Where are the obvious gaps where I can spend time improving the function documentation? - **Scientific and ecological clarity:** whether the simulations are explained in a way that connects the generated data to ecological theory and to the limitations of synthetic data. What ecological theory does it cover well, and where does it do less well? - **Software design:** whether the package structure, function interfaces, defaults, returned objects, messages, examples, and reproducibility choices support reliable use. - **Reliability:** whether the documented examples run as described on your machines, whether outputs are reproducible when seeds are set, and whether failures are understandable. - **Value for BCB743:** whether the package should be used in the module as-is, used with changes, used only for selected topics, or not used until specific issues are addressed. The review must be based on direct testing. Do not rely only on reading the documentation. ### Minimum testing expectations Each group must install the package from GitHub, work through the [`spesim`](../spesim.qmd) chapter, and test a representative set of package material from the documentation site. At minimum, your group should test: - installation from a clean R session - the minimal example in the BCB743 `spesim` chapter - the introductory vignette or start-here material - one environmental-gradient example - one quadrat-placement example - one point-process or spatial-structure example - one constrained-ordination or BCB743-linked example However, better marks can be had from developing and following a structured review methodology: write out the review approach, method, rationale, aims, objectives, and run it as you would a thorough scientific study. This will get you marks >70%. Record the operating system, R version, package version, and date of testing. If a test fails, record the exact command, error message, session information, and the steps needed to reproduce the failure. You are welcome to come to me any time and request bug fixes, but for me to fix them, I will require that you give me reproducible examples. ### Professional stance Write as professional reviewers. That means: - knowing the playing field: know what other packages exist that promise similar functions, what their strengths and weaknesses are, and how spesim ranks relative to these - separate evidence from opinion - identify strengths as carefully as weaknesses - distinguish defects, limitations, missing documentation, and reasonable design choices - describe the likely effect of each issue on a BCB743 student - prioritise recommendations by severity and educational consequence - make recommendations that could realistically be acted on by a package maintainer or course coordinator - suggest places where the spesim package can formally be integrated into the BCB743 curriculum (specific chapters and purposes) A useful review does not need to find many faults. It needs to show careful judgement. A small number of well-evidenced issues, each tied to a consequence for teaching or usability, is stronger than a long list of minor preferences. ### Suggested report structure You may adapt the structure if your argument requires it, but most reports should include: - **Executive summary:** your main judgement on whether `spesim` is ready for BCB743 use, and under what conditions - **Scope of review:** what you tested, your testing rationale and approach (maybe with aims, objectives, and/or hypotheses), what you did not test, and the computing environments used - **Pedagogical assessment:** how well the package supports the learning outcomes of BCB743 - **Usability assessment:** installation, first use, function interfaces, configuration, examples, outputs, and error messages - **Documentation assessment:** whether the chapter, package website, vignettes, examples, and terminology are clear and complete enough for students - **Reproducibility and reliability:** whether examples run, whether outputs can be reproduced, and whether failures are diagnosable - **Issue register:** a prioritised table of findings, each with evidence, consequence, severity, and recommendation - **Future functionality:** features that would make `spesim` more useful for BCB743 or for ecological teaching more broadly. These may include tools for simulating real geographically linked landscapes, known biodiversity structures in systems such as fynbos, arbitrary mapped landscapes supplied by the user, river networks, coastal strips, habitat mosaics, or other spatial settings where the ecological structure is known or can be specified. Rank these proposals from low to high priority, and explain the ecological use case, teaching value, and likely difficulty of implementation. - **Recommendations:** changes you would make before using the package in teaching, separated into urgent, useful, and optional improvements; if useful to BCB743, how you would integrate it as a teaching tool (what theory/prac needs does spesim address?) - **Conclusion:** your final recommendation for BCB743 adoption ### Submission requirements Submit: - a PDF review report - the Quarto source file for the report - any scripts used to test examples or reproduce issues - an issue register as a table in the report, and optionally as a separate CSV file - relevant screenshots only where they provide evidence of a usability or documentation issue - a short author-contribution statement explaining what each group member contributed - a brief AI-use disclosure if generative AI tools were used The Quarto file must render cleanly. Code used for testing should be reproducible or accompanied by enough information for me to rerun the test. All claims about the package must be tied to direct evidence, package documentation, or relevant BCB743 learning outcomes. ### Assessment criteria This assignment will be formally assessed and will contribute between 20% and 40% to your final BCB743 mark, depending on the weighting declaration you submit for the three assessed assignments. The three declared weights for Task A1, Task A2, and Task A3 must add to 100%, and no single task may carry more than 40%. If you do not submit a valid declaration by 17 July, the three tasks will be weighted equally. Indicative mark bands: - **90-100%:** professional-quality review. The report is evidence-based, technically careful, pedagogically insightful, and immediately useful to a maintainer or course coordinator. It tests the package thoroughly, distinguishes issue severity, and makes prioritised recommendations that are specific enough to act on. - **80-89%:** excellent review. The report tests the package well, links usability to BCB743 teaching needs, identifies important strengths and weaknesses, and gives clear recommendations, but may need stronger prioritisation, deeper software-design insight, or fuller reproducibility evidence. - **70-79%:** good to very good review. The report covers the main testing areas and makes sensible judgements, but the evidence base, issue register, pedagogical interpretation, or software-design analysis is less developed than in the higher bands. - **60-69%:** competent review. The package is tested and the report identifies some useful issues, but the analysis is more descriptive than evaluative, or the recommendations are too general to guide improvement. - **50-59%:** adequate but limited review. The report shows basic engagement with the package, but testing is narrow, evidence is thin, reproducibility details are incomplete, or the link to BCB743 teaching is weak. - **Below 50%:** incomplete, poorly evidenced, technically unreliable, unprofessional in tone, difficult to reproduce, or not focused on the package's role in BCB743. The assessment will consider: - **Professional judgement:** the report must read like a serious technical and pedagogical review, not a user diary or informal opinion piece. - **Testing depth:** conclusions must be based on direct testing across installation, examples, vignettes, outputs, documentation, and reproducibility. - **Pedagogical insight:** the review must assess whether the package helps teach the concepts and methods that BCB743 is designed to develop. - **Software-design insight:** the review must consider function interfaces, defaults, returned objects, messages, documentation structure, reproducibility, and maintainability from the perspective of an ecological user. - **Evidence and traceability:** findings must be supported by commands, outputs, screenshots where useful, documentation references, or clear observations from testing. - **Recommendations:** suggested changes must be specific, prioritised, realistic, and linked to their likely effect on student learning or package reliability. - **Writing and structure:** the report must be clear, concise, proofread, well organised, and professional. - **Collaboration:** all three group members are responsible for the full review. The submitted work should show shared intellectual ownership rather than three disconnected sections.