research documents for rMarkdown #111

fgregg · 2020-09-08T01:17:27Z

Overview

This PR will contains research documents for rMarkdown

Handles #21

Testing Instructions

Read the documents and evaluate?

fgregg · 2020-09-26T00:39:19Z

@jeancochrane @hancush, i think this is ready for review and discussion.

jeancochrane

These docs make a strong case for RMarkdown over our existing toolkit for data analysis. Thanks for sharing!

Reading through the docs, it strikes me that the relevant change recommended here isn't exclusively swapping RMarkdown in for Pweave but rather changing up our whole workflow and tooling for reproducible data analysis. I think that effort makes sense, but it has two implications for me:

We'll need to plan to do a major edit of https://github.com/datamade/data-analysis-guidelines and bring it into this repo, ideally with some templates (I hear Courts has some cookiecutter templates already?)
It would be more appropriate for these docs to live in whatever subdirectory the data analysis docs do, e.g. something like data-analysis/ instead of rmarkdown/

We can do 2 immediately in this PR but I think 1 will be a big task that could take several cycles to accomplish. I expect it'll be hard for you to execute alone given your capacity constraints. As part of pulling this in, we should make a plan for how that work is going to be tracked and delegated, since updated documentation is going to be key to the success of the adoption of this workflow.

rmarkdown/research/comparisons-with-existing-tools.md

jeancochrane · 2020-10-08T19:29:26Z

rmarkdown/research/comparisons-with-existing-tools.md

+rMarkdown has better editor support than Pweave. For the following editors, rMarkdown is as good and usually better
+than support for Pweave, if there any Pweave support exists.
+
+* [sublime](https://packagecontrol.io/packages/knitr)
+* [emacs](https://ess.r-project.org/)
+* [atom](http://www.goring.org/resources/atom_and_r.html)
+* [vscode](https://marketplace.visualstudio.com/items?itemName=Ikuyadeu.r)
+
+rMarkdown also has its own IDE, [RStudio](https://rstudio.com/)


It's great to hear that RMarkdown has such wide support. Our existing data analysis guidelines make a strong recommendation on which editor to use, though, and I've heard @hancush express the belief that RStudio is really good and we should recommend it. What do you think?

added this recommendation recommendation doc.

rmarkdown/research/comparisons-with-existing-tools.md

jeancochrane · 2020-10-08T19:33:06Z

rmarkdown/research/recommendation-of-adoption.md

+
+## Proof of concept and pilot
+
+RMarkdown has been the tool of choice for authoring reports in the Courts project. DataMade staff familiar with Pweave have picked it up quickly and journalists without a deep background in programming have also been able to use it successfully (within the RStudio environment).


It'd be great if we could link out to the relevant project here.

these are not going to be accessible to all staff, let alone public folks. unfortunately.

Pilots are useful in evaluating the tool, as well as for providing an example for future use. If we can't link to the project, could we host a clone of the cookiecutter as a basis for future analysis? It'd be ideal to add that in this repository, under docker/templates/r-markdown or something like that.

jeancochrane · 2020-10-08T19:33:59Z

rmarkdown/research/recommendation-of-adoption.md

+
+RMarkdown's interleaving of text and code adds another layer to interact with code. As such, we advise that staff not be introduced to RMarkdown until they are familiar with the programming language they will be using in the report. If the report will depend on SQL code, the developer should be familiar with how write and debug SQL code in the terminal or by writing SQL scripts. 
+
+If something is not working within a RMarkdown file, it's very useful to be able to work on the code in familiar environment in order to narrow the possible considerations while debugging.


Out of curiosity, can you drop a debugger in a Python block in an RMarkdown file?

no, not really.

Co-authored-by: Jean Cochrane <[email protected]>

fgregg · 2020-12-02T15:42:38Z

These docs make a strong case for RMarkdown over our existing toolkit for data analysis. Thanks for sharing!

Reading through the docs, it strikes me that the relevant change recommended here isn't exclusively swapping RMarkdown in for Pweave but rather changing up our whole workflow and tooling for reproducible data analysis. I think that effort makes sense, but it has two implications for me:
1. We'll need to plan to do a major edit of https://github.com/datamade/data-analysis-guidelines and bring it into this repo, ideally with some templates (I hear Courts has some cookiecutter templates already?)

2. It would be more appropriate for these docs to live in whatever subdirectory the data analysis docs do, e.g. something like `data-analysis/` instead of `rmarkdown/`
We can do 2 immediately in this PR but I think 1 will be a big task that could take several cycles to accomplish. I expect it'll be hard for you to execute alone given your capacity constraints. As part of pulling this in, we should make a plan for how that work is going to be tracked and delegated, since updated documentation is going to be key to the success of the adoption of this workflow.

I think this makes sense, I propose that we bring in this PR (once I resolve some of the inline comments) and then I can open an an issue on https://github.com/datamade/data-analysis-guidelines to track the changes that need to be made there.

how does that sound @hancush ?

hancush

Thanks for this, @fgregg. A couple of broad comments:

Is it rMarkdown or RMarkdown? In either case, could you standardize throughout?
We aren't consistent about organizing docs, e.g., some top-level directories are about tools, while others are about topic areas. As we expand this repository, I'm starting to prefer the topic area approach. Would you mind rehoming this, as Jean suggested, to a data-analysis directory?

Re: our existing docs (and related to a data-analysis directory), since the majority of our data analysis docs pertain to Pweave and because that repo hasn't really grown legs in the same way data making has, I think I'd prefer to archive that repo with a pointer to how-to and add documentation on our revised practices here. What do you think?

hancush · 2020-12-03T16:49:13Z

rmarkdown/research/comparisons-with-existing-tools.md

@@ -0,0 +1,54 @@
+# Comparing rMarkdown with existing tools
+
+How does rMarkdown compare with existing tools in DataMade's stack or possible alternatives.


Suggested change

How does rMarkdown compare with existing tools in DataMade's stack or possible alternatives.

How does rMarkdown compare with existing tools in DataMade's stack or possible alternatives?

hancush · 2020-12-03T16:50:29Z

rmarkdown/research/comparisons-with-existing-tools.md

+
+The main advantage of Pweave is that it is Python. 
+
+While rMarkdown does allow for Python code chunks, there is typically some setup code and that does need to be done in R. With Pweave, it's all Python.


Could you qualify the R setup a bit more, e.g., include a code block with an example setup? IIRC, it's pretty minimal, and an example could help to illuminate that.

hancush · 2020-12-03T16:50:43Z

rmarkdown/research/comparisons-with-existing-tools.md

+
+While rMarkdown does allow for Python code chunks, there is typically some setup code and that does need to be done in R. With Pweave, it's all Python.
+
+That is really the only advantage.


Suggested change

That is really the only advantage.

That is really the only advantage of Pweave.

hancush · 2020-12-03T16:51:34Z

rmarkdown/research/comparisons-with-existing-tools.md

+Like rMarkdown, Pweave requires an additional runtime beyond standard Python. rMarkdown requires R and Pweave requires
+[IPython](https://ipython.org/).
+
+Pweave is not actively maintained, and has not been updated


Could you add a link to the repo here?

hancush · 2020-12-03T16:51:50Z

rmarkdown/research/comparisons-with-existing-tools.md

+in three years.
+
+rMarkdown has better editor support than Pweave. For the following editors, rMarkdown is as good and usually better
+than support for Pweave, if there any Pweave support exists.


Suggested change

than support for Pweave, if there any Pweave support exists.

than support for Pweave, if any Pweave support exists.

hancush · 2020-12-03T16:52:32Z

rmarkdown/research/comparisons-with-existing-tools.md

+
+rMarkdown also has its own IDE, [RStudio](https://rstudio.com/)
+
+Beyond active devlopment and editor support, Pweave is missing many features compared to rMarkdown. Of greatest consequence are 1. chunk specific caching and support for 2. multiple languages, particularly SQL.


Suggested change

Beyond active devlopment and editor support, Pweave is missing many features compared to rMarkdown. Of greatest consequence are 1. chunk specific caching and support for 2. multiple languages, particularly SQL.

Beyond active development and editor support, Pweave is missing many features compared to rMarkdown. Of greatest consequence are chunk specific caching and support for multiple languages, particularly SQL.

hancush · 2020-12-03T16:58:36Z

rmarkdown/research/recommendation-of-adoption.md

+1. The report is for a client
+2. When the report contains graphs or statistics.
+3. When we use code to generate the graphs or statistics. If we are doing an quick analysis in Excel, because that is what a client needs, then a literate research report would not be useful approach.


Suggested change

1. The report is for a client

2. When the report contains graphs or statistics.

3. When we use code to generate the graphs or statistics. If we are doing an quick analysis in Excel, because that is what a client needs, then a literate research report would not be useful approach.

1. The report is for a client.

2. The report contains graphs or statistics.

3. We use code to generate the graphs or statistics. If we are doing a quick analysis in Excel, because that is what a client needs, then a literate research report would not be useful approach.

hancush · 2020-12-03T17:03:45Z

rmarkdown/research/recommendation-of-adoption.md

+
+## Proof of concept and pilot
+
+RMarkdown has been the tool of choice for authoring reports in the Courts project. DataMade staff familiar with Pweave have picked it up quickly and journalists without a deep background in programming have also been able to use it successfully (within the RStudio environment).


Pilots are useful in evaluating the tool, as well as for providing an example for future use. If we can't link to the project, could we host a clone of the cookiecutter as a basis for future analysis? It'd be ideal to add that in this repository, under docker/templates/r-markdown or something like that.

hancush · 2020-12-03T17:11:41Z

Follow up Q: Does RMarkdown obviate the need for us to learn LaTeX????

hancush · 2020-12-07T17:56:47Z

Update: We chatted out loud at R&D. We are going to archive the data analysis guidelines and maintain our revised docs, including these artifacts, in how-to/data-analysis. So, action items:

Move these docs into a data-analysis/ directory.
Add a brief README to that directory similar to Jean's Gatsby README: https://github.com/datamade/how-to/pull/12/files#diff-2d89f96961baf609c617e59bc1cd0bceabd6f9f03b4150a4f3e91f35cc046874
- It would be awesome to include a mirror of the Courts analysis cookiecutter in this PR, but I will leave that to your discretion, @fgregg.

fgregg · 2021-02-01T17:03:20Z

I think this responds to your requested changes?

hancush · 2021-02-11T17:14:03Z

It's a new day at DataMade! Thank you, @fgregg.

comparisons for rmarkdown

b9a00b4

fgregg marked this pull request as draft September 8, 2020 01:17

fgregg mentioned this pull request Sep 8, 2020

RMarkdown for literate analyses #21

Closed

fgregg added 2 commits September 8, 2020 09:28

discussion of editor support

1db95e2

recommendation of adoption

80fde68

fgregg changed the title ~~[WIP] research documents for rMarkdown~~ research documents for rMarkdown Sep 26, 2020

fgregg marked this pull request as ready for review September 26, 2020 00:39

jeancochrane requested review from jeancochrane and hancush October 5, 2020 16:22

jeancochrane reviewed Oct 8, 2020

View reviewed changes

fgregg and others added 4 commits November 5, 2020 08:45

Merge branch 'master' of github.com:datamade/how-to

4038849

Update rmarkdown/research/comparisons-with-existing-tools.md

84e7a06

Co-authored-by: Jean Cochrane <[email protected]>

Update rmarkdown/research/comparisons-with-existing-tools.md

ebd9935

Co-authored-by: Jean Cochrane <[email protected]>

Update rmarkdown/research/comparisons-with-existing-tools.md

4dd6536

Co-authored-by: Jean Cochrane <[email protected]>

fgregg added 2 commits December 2, 2020 10:48

Merge branch 'rmarkdown' of github.com:datamade/how-to into rmarkdown

fabfd1e

add section recommending people start with rstudio

1ce0727

hancush requested changes Dec 3, 2020

View reviewed changes

added readme doc, and otherwise follow hannah's reccs

6c5ec3b

fgregg requested a review from hancush February 1, 2021 17:08

hancush approved these changes Feb 11, 2021

View reviewed changes

hancush mentioned this pull request Feb 11, 2021

Deprecate datamade/data-analysis-guidelines #174

Closed

hancush merged commit a104298 into master Mar 1, 2021

hancush deleted the rmarkdown branch July 14, 2021 15:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

research documents for rMarkdown #111

research documents for rMarkdown #111

fgregg commented Sep 8, 2020

fgregg commented Sep 26, 2020

jeancochrane left a comment

jeancochrane Oct 8, 2020

fgregg Dec 2, 2020

jeancochrane Oct 8, 2020

fgregg Dec 2, 2020

hancush Dec 3, 2020

jeancochrane Oct 8, 2020

fgregg Dec 2, 2020

fgregg commented Dec 2, 2020

hancush left a comment

hancush Dec 3, 2020

hancush Dec 3, 2020

hancush Dec 3, 2020

hancush Dec 3, 2020

hancush Dec 3, 2020

hancush Dec 3, 2020

hancush Dec 3, 2020

hancush Dec 3, 2020

hancush commented Dec 3, 2020

hancush commented Dec 7, 2020

fgregg commented Feb 1, 2021

hancush commented Feb 11, 2021


		## Proof of concept and pilot

		RMarkdown has been the tool of choice for authoring reports in the Courts project. DataMade staff familiar with Pweave have picked it up quickly and journalists without a deep background in programming have also been able to use it successfully (within the RStudio environment).


		RMarkdown's interleaving of text and code adds another layer to interact with code. As such, we advise that staff not be introduced to RMarkdown until they are familiar with the programming language they will be using in the report. If the report will depend on SQL code, the developer should be familiar with how write and debug SQL code in the terminal or by writing SQL scripts.

		If something is not working within a RMarkdown file, it's very useful to be able to work on the code in familiar environment in order to narrow the possible considerations while debugging.

		@@ -0,0 +1,54 @@
		# Comparing rMarkdown with existing tools

		How does rMarkdown compare with existing tools in DataMade's stack or possible alternatives.


		The main advantage of Pweave is that it is Python.

		While rMarkdown does allow for Python code chunks, there is typically some setup code and that does need to be done in R. With Pweave, it's all Python.


		While rMarkdown does allow for Python code chunks, there is typically some setup code and that does need to be done in R. With Pweave, it's all Python.

		That is really the only advantage.

	That is really the only advantage.
	That is really the only advantage of Pweave.

	than support for Pweave, if there any Pweave support exists.
	than support for Pweave, if any Pweave support exists.


		rMarkdown also has its own IDE, [RStudio](https://rstudio.com/)

		Beyond active devlopment and editor support, Pweave is missing many features compared to rMarkdown. Of greatest consequence are 1. chunk specific caching and support for 2. multiple languages, particularly SQL.

	Beyond active devlopment and editor support, Pweave is missing many features compared to rMarkdown. Of greatest consequence are 1. chunk specific caching and support for 2. multiple languages, particularly SQL.
	Beyond active development and editor support, Pweave is missing many features compared to rMarkdown. Of greatest consequence are chunk specific caching and support for multiple languages, particularly SQL.

research documents for rMarkdown #111

research documents for rMarkdown #111

Conversation

fgregg commented Sep 8, 2020

Overview

Testing Instructions

fgregg commented Sep 26, 2020

jeancochrane left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fgregg commented Dec 2, 2020

hancush left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hancush commented Dec 3, 2020

hancush commented Dec 7, 2020

fgregg commented Feb 1, 2021

hancush commented Feb 11, 2021