Draft package vignettes

[cforgaci]

I drafted a set of vignettes which are meant to explain to the end user how the package works.

The vignettes are organised in two categories:

1. Vignettes for each step of the delineation process: corridor edge delineation, segmentation, and river space delineation. The first vignette in this category describes the overall delineation method.
2. Vignettes with generic use cases: multiple delineations, delineation around a point of interest.

The distinction between these two categories is also indicated on the package website.

Note that:

• Many of the code chunks are not evaluated as they contain functions that have not been written yet.
• As I suggest in some vignettes, some preprocessing steps and API calls can be replaced by package data to make sure that the vignettes is focused on the core task.
• It might be helpful to have a separate vignette on OSM functions, but I am not sure.
• I expect more use cases in the second category, so feel free to suggest essential vignette topics that slipped my mind.

Vignettes ready for review:

Delineation:

• 1. The method
• 2. Corridor delineation
• 3. Corridor segmentation
• 4. Riverspace delineation

Use cases:

• 5. Multiple delineations
• 6. Study area around a POI

I hope this helps us sharpen our understanding of the package functionality and design.

[meiertgrootes]

Hi @cforgaci,
the vignettes look nice and give a clear impression of what CRiSp does/will do. I've added a number of minor comments, largely addressing very minor issues or where I hope they can add some additional clarity. None of these are crucial, however, so please do with them as you see fit.

[fnattino]

Hi @cforgaci , looks great, it all reads very clearly and it looks to me very useful as a general guideline to structure the package!
I like the separation between methodological and use-case-driven vignettes. Feel free to merge on my side.

As a general comment, I agree with your suggestion of replacing API calls/preprocessing steps with packaged data in most of the vignettes. We could maybe think about moving all OSM-related stuff to a separate vignette that focuses on how to get data from OSM in a form that is suitable to work with CRiSp - basically documentation on how to use OSM-related utility functions of CRiSp.

All other vignettes could then start from packaged data that is already cleaned and preprocessed, so that it will be clearer to the reader what are the main core functions of CRiSP (i.e. the delineation methods). This would also force us to expose and document functions that run each of the delineation steps independently and using arbitrary datasets in input (say, a river line, a street network, etc.), in addition to the all-at-once functions that automatically get data from OSM (such as delineate_corridor). But I think this is a good thing, since not everyone will be working (exclusively) with OSM data.

[cforgaci]

Hi @cforgaci, the vignettes look nice and give a clear impression of what CRiSp does/will do. I've added a number of minor comments, largely addressing very minor issues or where I hope they can add some additional clarity. None of these are crucial, however, so please do with them as you see fit.

Thanks @meiertgrootes! I tried to address all the comments.

[cforgaci]

Hi @cforgaci , looks great, it all reads very clearly and it looks to me very useful as a general guideline to structure the package! I like the separation between methodological and use-case-driven vignettes. Feel free to merge on my side.

Perfect, thanks for the review!

We could maybe think about moving all OSM-related stuff to a separate vignette that focuses on how to get data from OSM in a form that is suitable to work with CRiSp - basically documentation on how to use OSM-related utility functions of CRiSp.

I created #22 for this.

All other vignettes could then start from packaged data that is already cleaned and preprocessed, so that it will be clearer to the reader what are the main core functions of CRiSP (i.e. the delineation methods). This would also force us to expose and document functions that run each of the delineation steps independently and using arbitrary datasets in input (say, a river line, a street network, etc.), in addition to the all-at-once functions that automatically get data from OSM (such as delineate_corridor). But I think this is a good thing, since not everyone will be working (exclusively) with OSM data.

This PR is ready to be merged.