Vignettes

[nickbearman]

Hi,

We (@aduhour & I) are looking at the Vignettes - https://github.com/r-tmap/tmap/blob/master/vignettes/01_basics_vv.Rmd

We were planning to look through them and update them where possible.

For 1. visual variables (01_basics_vv.Rmd), it looks similar to https://r-tmap.github.io/tmap_vv.html.

Should @aduhour copy that into 01_basics_vv.Rmd?

I have looked at 03_versus_ggplot2.html and will post a PR shortly.

If there is a better way of doing this, or something else we should do, please let us know.

Thanks!

Working at FOSS4G https://github.com/r-tmap/tmap/issues/978

[nickbearman]

ggplot2 comparison https://github.com/r-tmap/tmap/pull/980

[mtennekes]

Thanks @nickbearman and @aduhour

Yes, PRs welcome!

What is important is that

My idea was to structure the vignettes in such a way that it is useful for all types of users (beginners/experiences, theory/application driven). My proposal is something like this:

tmap_basics:

• visual variables
• scales
• facets
• legends
• modes (plot and view)
• basemaps
• layout
• exporting maps

tmap_examples:

• choropleth
• bubble map
• raster map (input from @gilbertocamara)
• bivarite choropleth
• gridmap
• topographic map

tmap_theory:

• grammar of graphics
• map projections

tmap_advanced

• options
• mode extensions
• layer extensions

tmap_versus:

• ggplot2
• mapview
• leaflet

Let me know if you agree or have suggestions to this structure and the topics

Two final remarks:

• @Nowosad and I will update/rewrite the book https://github.com/r-tmap/tmap-book (contributions welcome). So in other words, the vignettes don't need to be detailed. Furthermore, it would be preferable if we can use tmap's own datasets.
• For the v4 release we don't need all the vignettes, and also not in too much detail.

Let me know if you agree on the list of topics. When we've settled on this, we can coordinate/distribute the work load to write them. Thx

[nickbearman]

Thanks @mtennekes. I will have a read of your comment and reply in due course. I am away for the rest of December, so it will probably be in early Jan.

One other comment is do you have thoughts / a structure / an outline for the various bits of documentation that exist for tmap. So this would include:

• the help files (already mentioned elsewhere I think)
• the vignettes - how/where is the compiled version stored (is it at https://cran.r-project.org/web/packages/tmap/index.html, anywhere else?)
• the page at https://r-tmap.github.io/tmap/

I was trying to explain how this was organized to @aduhour and realized I didn't understand it myself....!

Thanks! Nick.

[mtennekes]

I was trying to explain how this was organized to @aduhour and realized I didn't understand it myself....!

😅 Totally understandable.

Actually, the vignettes will not be part of the CRAN package, but only deployed online at https://r-tmap.github.io/tmap/ Two reasons: overlap (as you've pointed out) and the other is the CRAN package size restriction (image rich vignettes are large).

The help files are just very brief/to-the-point descriptions of all functions and arguments: most is already there, but if you notice that something is incomplete and important for the CRAN submission, please let us know.

Good question about which version the vignettes are based on. Currently always the GH version (master branch), but the question is what to do when v4 is on CRAN. (@olivroy ?)

[olivroy]

Good question about which version the vignettes are based on. Currently always the GH version (master branch), but the question is what to do when v4 is on CRAN. (@olivroy ?)

We can reenable site dev mode once tmap v4 hits CRAN.

https://r-tmap.github.io/ would show CRAN vignettes while https://r-tmap.github.io/dev would show the development version vignettes.

[aduhour]

Hello! Thank you for your replies. I am interested, as a user of tmap, in to cotribute in what I can. I could read today about what is needed and the structure suggestions.

I can make a PR about https://github.com/r-tmap/tmap/blob/master/vignettes/01_basics_vv.Rmd, so you can consider my contribution so that I can make useful suggestions in the future.

Thanks! Andrés

[mtennekes]

Thanks a lot @aduhour, much appreciated!

[aduhour]

I added a PR about visual variables vignette. I hope it will be helpful. #992

[mtennekes]

Thx @aduhour I've shortened it a bit; e.g. removed the visual constant from the table, because that are for default. In essence every visual variable can be either a value or data-variable. (So I used 'visual variable' a bit broader now).

[mtennekes]

FYI, new:

https://r-tmap.github.io/tmap/articles/03_basics_facets.html https://r-tmap.github.io/tmap/articles/04_basics_legends.html

What is the easiest way to cross-link between vignettes and between vignette and roxygen2 docs (@olivroy) ?

[olivroy]

It is easy to cross link from vignette to docs. Functions are automatically hyperlinked. We'd need to pepper-spray links to vignettes in docs. For example, in @seealso to provide links from functions to vignettes.

[mtennekes]

Yes, we need some pepper-spray (love this analogy)!

Indeed via @seealso, but also urls in each details paragraph. Before we do this, we need to make use of a standard text for the 'details' section in the tm layer functions (tm_polygons, tm_text). Isn't there a markdown import function we can use? Then we can easily update that with vignette urls, and apply that to all layer functions.

[olivroy]

We can do something like this

#' @seealso `r .link_vig("04_basics_legends")`

with this in R/docs.R

.link_vig = function(title) {
  paste0("Learn more in the [", title, " vignette]", "(https://r-tmap.github.io/tmap/articles/", title, ")")
}

[mtennekes]

New vignettes drafted: versus mapsf, basic components and advanced positioning.

@olivroy This [tm_pos_in()] doesn't work in the vignette https://r-tmap.github.io/tmap/articles/41_adv_positions. What is the correct way to link to the package docs?

[olivroy]

It is simply to surround with backticks :) https://pkgdown.r-lib.org/articles/linking.html

[gmgui]

Hi,

Thanks so much for updating the vignettes, it really helps a lot! I realized that the vignette for exporting (https://r-tmap.github.io/tmap/articles/basics_exporting) actually has the same contents from the scales vignette (https://r-tmap.github.io/tmap/articles/basics_scales)

thanks again!

[mtennekes]

Thx for the reminder @gmgui !

Now I think all vignettes I wanted to write have been written. There may be some (or many) typos, and some minor layout thinks, but it should be sufficient for now.

Let me know if something is still missing or can be improved.

[mtennekes]

Submitted :-)

Still strange that https://r-tmap.github.io/tmap/articles/adv_groups not fully renders...

We can reenable site dev mode once tmap v4 hits CRAN.

https://r-tmap.github.io/ would show CRAN vignettes while https://r-tmap.github.io/dev would show the development version vignettes.

I think for now it's preferable to keep the current situation (so don't use a /dev development version). Why? Because I foresee that people may find typos or unclarities.

When the time comes that new features are being implemented that need explanation in the vignettes, we could either put that under a "Development version only" section, or go with the two-deployments.

[nickbearman]

https://github.com/r-tmap/tmap/pull/1033 Updated scales vignette and also spotted a typo. Do let me know if I need to do anything different in the future.

[mtennekes]

Pretty complete now, so closing this