reorganize readme #232

magland · 2024-10-30T13:26:04Z

I took a crack at tidying the readme, mainly by moving technical content to separate files, and providing a link to the forum post.

With the existing readme, I think the table of query parameters is somewhat distracting - so that was my primary motivation for separating things out.

I also reordered the author list since you two are taking the lead at this point. :)

WardBrian

This looks good! I made a couple additional suggestions but you can merge as-is if you want, thanks for updating

WardBrian · 2024-10-30T14:06:22Z

README.md

@@ -17,54 +17,20 @@ While the Stan models execute in the browser (on your local machine), the compil

 This project is based on [stan-web-demo](https://github.com/WardBrian/stan-web-demo) which shows how to use [TinyStan](https://github.com/WardBrian/tinystan) to build a WebAssembly version of a Stan model that can be executed in the browser. While stan-web-demo focuses on integrating a specific Stan model into a website—essentially "baking" the model into the web environment—stan-playground is designed for a broader purpose. It offers a flexible platform for experimenting with and exploring various Stan models. This makes it ideal for users looking to test different statistical models and hypotheses directly in their browser, without the commitment to a single model implementation.


Do you think this also deserves to be in "notes"? I think this project is now the "premier" use case of wasm-for-tinystan, so it seems less likely people will have the context of those other projects beforehand

I moved it to notes.

WardBrian · 2024-10-30T14:56:23Z

README.md

Do we want to update the blurb at the top to be what we have on the FI website?

Stan Playground is a browser-based editor and runtime environment for Stan models. Users can edit, compile, and run models, as well as analyze the results using built-in plots and statistics or custom analysis code in Python or R, all with no local installation required.

instead of "Run Stan models directly in your browser"?

Okay I have now squashed the two together. I'll merge, but feel free to edit if that paragraph can be improved.

jsoules · 2024-10-30T15:05:35Z

docs/compilation_server_setup.md

@@ -0,0 +1,21 @@
+# Compilation server setup
+
+These instructions are only required if you want to set up your own compilation server. If you are content with using the public server, you can skip this section.


Suggested change

These instructions are only required if you want to set up your own compilation server. If you are content with using the public server, you can skip this section.

These instructions are only required if you want to set up your own compilation server.

jsoules · 2024-10-30T15:06:32Z

docs/compilation_server_setup.md

+
+In the menu bar, you can choose to use either the public server or your local server. If you opt for the local server, the default port is 8083. If you change this port or use a different host, update your settings in the "Custom server" option.
+
+To compile a Stan model, click the "compile" button at the top of the Stan file editor. After compilation, you can input JSON data to run the sampling. The results will be displayed directly in the browser, and there is also an option to download them.


This applies regardless of compilation server choice; should it be in the main readme? (Or do we/should we have official instructions elsewhere, or is "use the compile button to compile" sufficiently obvious...?)

I'm going to defer this (and any screenshots) to some future "let's write instructions" PR.

docs/compilation_server_setup.md

jsoules · 2024-10-30T15:09:57Z

docs/previous_stan_playground.md

@@ -0,0 +1,3 @@
+# How is this different from the previous stan-playground?
+
+The [previous version of stan-playground](https://discourse.mc-stan.org/t/old-introducing-stan-playground-a-web-based-platform-for-stan-programming-and-collaboration/31653) also provided a mechanism for running Stan models through the browser. However, that project relied on server-side processing for sampling. In contrast, this iteration of stan-playground (despite sharing the same name) performs all sampling directly within the browser, enhancing user control and privacy.


Suggested change

The [previous version of stan-playground](https://discourse.mc-stan.org/t/old-introducing-stan-playground-a-web-based-platform-for-stan-programming-and-collaboration/31653) also provided a mechanism for running Stan models through the browser. However, that project relied on server-side processing for sampling. In contrast, this iteration of stan-playground (despite sharing the same name) performs all sampling directly within the browser, enhancing user control and privacy.

The [previous version of stan-playground](https://discourse.mc-stan.org/t/old-introducing-stan-playground-a-web-based-platform-for-stan-programming-and-collaboration/31653) also provided a mechanism for running Stan models through the browser. However, that project relied on server-side processing for sampling. In contrast, this iteration of stan-playground (despite sharing the same name) performs all sampling directly within the browser, enhancing user control and privacy.

Note that while sampling and data remain local to the user's machine, the Stan code must be sent to the compilation server for compilation. The operators of the compilation server have limited access to submitted code, but users developing proprietary models should consider running a local compilation server or not using this tool.

(This gets at the privacy issue which AG mentioned in his forum post.)

jsoules · 2024-10-30T15:13:32Z

README.md


-Except where noted, these can also be combined. Here is a link that provides a Stan model, data.json file, and sets the title and the number of warmup draws:
+In addition to the built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists), you can also manually prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters).


Suggested change

In addition to the built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists), you can also manually prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters).

Stan Playground offers a built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists). This makes it easy to share your work with collaborators, students, forum users, and many other audiences.

Additionally, you can also prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters). For more information, see [URL Parameters](./docs/url_parameters.md),

We haven't mentioned the gists yet, and since they're probably easier, I think it'd be good to direct them there first.

jsoules · 2024-10-30T15:14:20Z

docs/url_parameters.md

@@ -0,0 +1,25 @@
+# URL Parameters
+
+In addition to the built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists), you can also manually prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters).


Given that they're already in the URL Parameters section, we can probably trim this.

jsoules · 2024-10-30T15:15:05Z

docs/url_parameters.md

@@ -0,0 +1,25 @@
+# URL Parameters
+
+In addition to the built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists), you can also manually prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters).


Suggested change

In addition to the built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists), you can also manually prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters).

Stan Playground supports the following [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters) in many combinations.

jsoules · 2024-10-30T15:16:10Z

Made a couple suggestions, but it looks like we merged already :)

Should I make a separate PR?

magland · 2024-10-30T15:19:07Z

Made a couple suggestions, but it looks like we merged already :)

Should I make a separate PR?

Oops, sorry Jeff! Merged too hastily. Looking over your points I agree with what you are saying. Would you mind making a separate PR? I think that would be easiest.

reorganize readme

39cf696

magland requested review from jsoules and WardBrian October 30, 2024 13:26

WardBrian approved these changes Oct 30, 2024

View reviewed changes

updates to readme

c8fcf66

magland merged commit aba9db1 into main Oct 30, 2024
2 checks passed

jsoules reviewed Oct 30, 2024

View reviewed changes

WardBrian deleted the reorganize-readme branch October 30, 2024 15:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

reorganize readme #232

reorganize readme #232

magland commented Oct 30, 2024

WardBrian left a comment

WardBrian Oct 30, 2024

magland Oct 30, 2024

WardBrian Oct 30, 2024

magland Oct 30, 2024

jsoules Oct 30, 2024

jsoules Oct 30, 2024

jsoules Oct 30, 2024

jsoules Oct 30, 2024

jsoules Oct 30, 2024

jsoules Oct 30, 2024

jsoules Oct 30, 2024

jsoules Oct 30, 2024

jsoules Oct 30, 2024

jsoules commented Oct 30, 2024

magland commented Oct 30, 2024

		@@ -17,54 +17,20 @@ While the Stan models execute in the browser (on your local machine), the compil

		This project is based on [stan-web-demo](https://github.com/WardBrian/stan-web-demo) which shows how to use [TinyStan](https://github.com/WardBrian/tinystan) to build a WebAssembly version of a Stan model that can be executed in the browser. While stan-web-demo focuses on integrating a specific Stan model into a website—essentially "baking" the model into the web environment—stan-playground is designed for a broader purpose. It offers a flexible platform for experimenting with and exploring various Stan models. This makes it ideal for users looking to test different statistical models and hypotheses directly in their browser, without the commitment to a single model implementation.

		@@ -0,0 +1,21 @@
		# Compilation server setup

		These instructions are only required if you want to set up your own compilation server. If you are content with using the public server, you can skip this section.


		In the menu bar, you can choose to use either the public server or your local server. If you opt for the local server, the default port is 8083. If you change this port or use a different host, update your settings in the "Custom server" option.

		To compile a Stan model, click the "compile" button at the top of the Stan file editor. After compilation, you can input JSON data to run the sampling. The results will be displayed directly in the browser, and there is also an option to download them.

		@@ -0,0 +1,3 @@
		# How is this different from the previous stan-playground?

		The [previous version of stan-playground](https://discourse.mc-stan.org/t/old-introducing-stan-playground-a-web-based-platform-for-stan-programming-and-collaboration/31653) also provided a mechanism for running Stan models through the browser. However, that project relied on server-side processing for sampling. In contrast, this iteration of stan-playground (despite sharing the same name) performs all sampling directly within the browser, enhancing user control and privacy.


		Except where noted, these can also be combined. Here is a link that provides a Stan model, data.json file, and sets the title and the number of warmup draws:
		In addition to the built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists), you can also manually prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters).

-In addition to the built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists), you can also manually prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters).
+Stan Playground offers a built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists). This makes it easy to share your work with collaborators, students, forum users, and many other audiences.
+Additionally, you can also prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters). For more information, see [URL Parameters](./docs/url_parameters.md),

		@@ -0,0 +1,25 @@
		# URL Parameters

		In addition to the built-in sharing feature which integrates with [Github Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists), you can also manually prepare links which will pre-populate each portion of Stan Playground when clicked by using [URL Parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#parameters).

reorganize readme #232

reorganize readme #232

Conversation

magland commented Oct 30, 2024

WardBrian 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

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

jsoules commented Oct 30, 2024

magland commented Oct 30, 2024