Repository navigation
Rework the documentation and site for 3.0.0 - #16
Merged
Merged
Conversation
The rules for reading input geometry, the condition classes and the two work-limit options were spread over the argument entries and sections of many help pages. Three topics now hold them in one place: ?spatialkit-geometry (CRS alignment, layers without a CRS, mixed dimensions and M, rows without a location, boundaries, polygons in degrees), ?spatialkit-conditions (every class the package raises, who raises it, what it means, what to do, the fields it carries and how to catch it) and ?spatialkit-options (spatialkit.exact_pairs_max and spatialkit.fit_work_max). Each statement is checked against the code.
The home page now leads with what the package does, installs from CRAN first, and runs a quick start that draws Voronoi cells at the default count and compares random with blocked cv_rf() scores, with every number computed when the page is knitted. A pipeline map and one table of articles replace the function table, the backend guide, the troubleshooting and operations notes and the duplicate documentation list, which move to their own articles and to a contributing guide. The Scope section now says the Bayesian backend fits binary, ordinal and categorical responses. The resolution figure is rebuilt around the default count with its leave-one-out errors, and the folds figure is drawn side by side. DESCRIPTION describes the default cell count and the pooled value and cites kNNDM. inst/CITATION gives each method its own entry.
?spatialkit now opens with where to start, lists the eleven pipeline steps with the article for each, and names resolution_profile() and select_resolution() as the route to a cell count. Migration notes and version history leave the help for NEWS; uncited defaults are listed as such. ?resolution_profile, ?select_resolution and ?determine_optimal_levels get headed sections, a Value written as lists, their own conditions only, links to the shared geometry and conditions topics, and examples that print what their comments describe. Simulation figures no script reproduces are cut. ?ensure_projected says what target_crs does to input that is already projected. coerce_to_points() documents each mode, and its line_midpoint error names the argument `mode`.
Get started now installs from CRAN first and holds the one table of optional packages, with a note on the Stan toolchain. Its first step chooses the cell count with resolution_profile() and select_resolution(), and every count and score in the prose and the map's alt text is computed from the output, so the page no longer says eight cells where it draws seven. It names which functions take a logical, factor or character response and which refuse one, drops the claims that predict_surface() takes a raster and that the reporting article fits on cells, and gives the R2 of both fold schemes with the forest's out-of-bag R2. Warnings the text names are shown, each optional-package chunk leaves a note when the package is missing, the scripts table moves here from the home page, the earlier-defaults paragraph goes to the changelog, the glossary moves to its own page, and a Next section replaces the article list.
Retitle it "Exporting and reporting results" and order it as the cells as a file, a cell mean, a pooled cell value, a model's score and what to save. Correct what the code contradicts: sites need no reprojection before a membership lookup, a negative R2 is against the training mean, get_voronoi_seeds() is unseeded by default, three report lines are computed checks, and a shapefile renames most columns. Add a table of seed arguments, a saveRDS() record, the surface with its flag, and compute every count inline. Drop the date line, the closing printout of package versions and the earlier-defaults paragraph, and link the other articles for detail.
?summarize_by_cell now opens with its output columns, then pooled values, intervals, standard errors and design effects, and conditions, and gathers its simulation figures in one section that links the script that makes them. Figures that no script in the repository reproduces are cut, and the column names, cell_weight and id_col are described as the code returns them. The other cell-building and assignment pages lose their version history and the repeated boundary rules, which ?spatialkit-geometry now holds, and the longest ones gain headed sections. Titles start with a verb. create_grid_polygons() takes a selection, a profile or ranked levels as target_cells, as build_tessellation() does, and logs when n overrides target_cells. plot_tessellation_map() reads ID columns in the order the join reads them, and the kriging_adequacy() report wraps to the console width.
?make_folds opens with what it returns and where the result goes, then a table of the six methods, and moves block sizing, NNDM, kNNDM and the numerical tolerances into headed sections, so each argument states only its contract. ?estimate_sac_range gets headed sections in reading order and absorbs ?print.sac_range; ?cv_block_size_sweep absorbs the plot method. ?cv_spatial holds one text for folds, boundary, pointize and the fold-size arguments, which cv_gwr() and cv_bayes() inherit, and lists its return value element by element. Input-geometry rules link to ?spatialkit-geometry; version history and measured figures with no script behind them are gone; examples print every value their comments name. plot_folds() now gives the size of the blocks it draws beside the block_size asked for, with no scientific notation, and draws its axes in the projected CRS of the map; the variogram and sweep plots name the CRS's linear unit in short form; the sweep's printed table and the directional ranges of print(<sac_range>) fit 80 columns.
The help pages of the fitters, the methods on a fit, the in-sample and cross-validated comparisons, predictor selection, prediction and the area of applicability state the current behaviour, without version history or simulation figures that no script reproduces. The predict, fitted, residuals and coef methods of the three backends share one page per verb with a runnable example, and the families follow the reference sections. Fixes: a literal \% that cut lines on ?area_of_applicability, the `...` text of predict() for GWR and Bayesian fits, the GWR fitted() description, coef() logging rather than warning, n_pred in the shared metrics section, and the Bolin and Wallin reference. Plot labels no longer clip or show Markdown backticks, and resolution profile panels get fewer, shorter y labels.
The article is retitled "Worked example: North Carolina" and opens with one sentence linking Get started in place of the overview list and the note on earlier defaults. The modelling half now runs fit and residuals, then spatial folds, then the surface, with a bridge from cells to points. Every number the runs produce is computed inline, the closing summary that contradicted the fold_separation() reading is gone, and the comparison and area of applicability use the folds that reading matches. Adds the variogram plot and a GWR coefficient map, sizes maps for the state's shape, cuts explanations other pages own to links, and drops the date line, em dashes and sessionInfo().
The Diagnostics article becomes "Fitting and checking models" (vignettes/models.Rmd). It now covers choosing a backend, which moves here from the home page without its outdated timings; the random forest, GWR with a map of its local intercept, and the Bayesian GP as shown code; writing a backend with new_spatial_fit(); scoring all of them on the same blocked folds; residual Moran's I and what to do when it is large; choosing predictors inside the folds, with the nested run; and the area of applicability, computed with the folds and followed by what to do outside it. Every number in the prose is computed on the page. The cell sections leave for the cells article.
The spatial cross-validation article now opens on the built-in cv_*() functions, cuts the custom learner to its constructor and predict(), and gives the four fold_separation() readings with a clustered example where random folds read closer and kNNDM folds match the map. It runs kNNDM, buffered leave-one-out and Voronoi blocks, prints the blocks built beside block_size, draws the variogram, checks each sweep size against the map, shows the warnings it describes, and ends with the next article and the method references. Every number is computed.
The package's core step had no article of its own: tessellation methods, standard errors and the design effect, the kriging check and the pooled-value warnings were spread over four pages. The new article "Building cells and summarising them" takes them in pipeline order, from choosing a method and placing seeds to cell values at other locations. It corrects the design-effect and kriging wording, shows the warnings as R prints them, and computes every count inline.
The article now opens with what the cell count controls and the default call, then covers a size for pooled values, leave-one-out for plain means, a ladder of counts with its bounds before the criteria, an elbow from the coordinates (with a clustered example that finds one), choosing on one half, and passing the count to the cells. It corrects the claim that a profile's levels share one random stream, says which count arguments take a selection, gives the full ceiling and structure rules, and prints every warning its prose names, the default rule on a ladder of counts among them. It says a bound chose the count only when one did, uses "flat region" throughout, links the simulation script, and drops the date line and an unsourced cross-validation claim.
Troubleshooting and performance takes the README's troubleshooting and practice sections: each message is quoted as R prints it, the examples print real output, and a table gives the work limits a large layer meets, each read from the code. It also covers parallel folds, the two caches and the log file's path. Terms used on these pages is the glossary from Get started, with the block entry corrected and the terms the other pages use added.
The reference index now has the pipeline's sections in order, each with a verb-first title and a description, with seed placement and the lower-level builders as subsections under Build the cells. The Articles menu groups the nine articles as Get started, Step by step, Worked example and Help, and the old Diagnostics page redirects to the models article. KaTeX renders the formulas that reference pages showed as LaTeX source, and the options section now says when each cache needs clearing. The workflow comments name the articles each job runs in full.
The tour scripts and the North Carolina script described defaults by how they differed from earlier versions, used " -- " as a dash, and gave a few numbers and behaviours the code no longer bears out: the fitted ranges of the fixture, a k reduction said to raise no warning, and what n_local_singular counts. They now state current behaviour in the site's terms and spelling, give distances in metres, and quote the numbers a run prints. example_nc_demo.R follows the reworked North Carolina article step for step, with the same folds and numbers.
The development entry becomes the 3.0.0 entry: an opening paragraph, Breaking changes led by the defaults that change results and the argument that restores each, the new functions with the article that shows them, bug fixes a 2.0.0 user could meet merged by theme, and a short Documentation section. Entries sit under the reference index's section titles, ordered by function name, and none runs past 120 words. The 2.0.0 entry keeps its substance without the dashes and the notes on how the release was written.
The help pages, articles and changelog were rewritten, so thirteen test files still pinned the sentences they replaced. The help and article pins now read the new text: predict_surface, ensure_projected, assign_features_to_polygons, resolution_profile, the boundary rules in ?spatialkit-geometry, the condition list in ?spatialkit-conditions and the troubleshooting article. Pins on changelog wording are gone; one check that Breaking changes holds the adapt_delta entry stays. Every behavioural assertion is unchanged.
The tests that read help pages, articles, the README and the scripts now look for the sentences where they stand after the rework: the fold-reading sentences on their new pages, the seeders' boundary rules in "Sampling inside the boundary", the sweep plot in its section of ?cv_block_size_sweep. Phrases reworded without a direction word leave the exception list, and the checks on changelog wording go. Prints of kriging_adequacy() are read unwrapped, the plot caption without backticks, and tessellation labels in the ID column order of the join.
Eleven test files read help text that the reference rework moved, split or reworded. Their assertions now match the new sentences, including the rules now stated once on ?spatialkit-geometry, and assertions on changelog wording are gone. Two tests read output whose format changed: the kriging check's report, now wrapped at the console width, is read at a wide one, and the plot_cv_metrics() captions are matched without the backticks ggplot2 drew as plain text.
The help pages now link the shared geometry topic, state current behaviour without version history and keep no unsourced lattice counts. These tests now read the new text, check that ?spatialkit points to Breaking changes in NEWS, and print kriging_adequacy() wide so its wrapped report lines stay whole. Assertions on NEWS wording go; the behavioural assertions are unchanged.
The documentation tests read the help pages, vignette sections and NEWS entries that describe pooled values. They now find those texts under their new titles, including the "How this was checked" sections and the cells article, and keep the three rules: the denial sentence wherever an interval is described, no figure that is not a row of dev/sim-pooled-values.csv, and no existing units named. Checks on NEWS wording and on help paragraphs that were removed go with them. The reference helpers and their tests describe each reference by what it computes, with the code unchanged, and inst/WORDLIST lets spelling::spell_check_package() run clean.
A read of the built site found statements the code contradicts and pages that are hard to use. The design-effect, glossary, cv_spatial() and README cell-ID claims now match the code; a help paragraph that rendered as a code box renders as prose; long Value sections become lists; each article links its first use of a term to the glossary and states optional packages one way; models gains a map of the masked surface; wide tables scroll at phone width. Prints lose a "WSS rises at 0 step(s)" clause and the "levels in band" label, give the area-of-applicability distance in the CRS unit, and show record errors in one notation without forcing 9.52 into 9.52e+00. Tests and 52 frozen records follow the new print text, and builds from a worktree leave out its .git file.
A network failure on the runner image kept setup-r retrying apt for 92 minutes before the job failed. Each R setup step now stops after 15 minutes and each dependency install after 40, and every job has a limit well above its usual run time: 120 minutes for the check matrix, 150 for the optional backends and the nightly brms check, and 60 for the site build.
The test fitted a random forest without checking for ranger, which is in Suggests, so it errored on the check jobs that install only the required packages. The unit and CRS checks now run first and the forest caption check skips when ranger is missing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reworks the documentation and the pkgdown site ahead of 3.0.0, so that every page states what the package does now and the articles follow the order in which the pipeline runs.
Site organisation
articles/diagnostics.htmlnow redirects toarticles/models.html.Content
inst/scriptsare updated to match the current API.setup-r;Checks on this branch
R CMD check --as-cranspelling::spell_check_package()pkgdown::check_pkgdown()and a full site builddocument()andbuild_readme()The check's NOTE includes five README links that return 404 until this branch is merged and the site deploys:
articles/cells.htmlarticles/glossary.htmlarticles/models.htmlarticles/troubleshooting.html.github/CONTRIBUTING.mdLeft for later
development: mode: autokey: added at the 3.0.0 version bump.