add faq #197

mastoffel · 2024-03-04T16:39:02Z

Adding user FAQ and a few smaller changes to the docs.

resolves #188

review-notebook-app · 2024-03-04T16:39:08Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

mastoffel · 2024-03-04T16:40:54Z

@kallewesterling @bryanlimy if you had some time to look over this, that would be great.

github-actions · 2024-03-04T16:42:38Z

Coverage report

This PR does not seem to contain any modification to coverable code.

kallewesterling

I think it looks good as a start but a few comments from my side :)

kallewesterling · 2024-03-05T09:40:46Z

docs/community/faq/faq-contributors.md

@@ -1,5 +1,7 @@
 # First-Time Contributors' Frequently Asked Questions

+**TODO**


What do you think is needed here? An intro to the page, perhaps?

Reading through the answers, perhaps we should add "You need to be familiar with..." and then list what prerequisites there are for the package. For instance, a good understanding of machine learning concepts, and NumPy as a package?

I just put a todo to include it but show that it's not ready, and I'm not sure we can get this done this week.

About the prerequisites list: Yes, I think that's a good idea!

kallewesterling · 2024-03-05T09:41:09Z

docs/community/faq/faq-users.md

   <!-- Information on the knowledge or data required to effectively use AutoEmulate, such as familiarity with Python, machine learning concepts, or specific data formats. -->
+   - `AutoEmulate` is designed to be easy to use. The user has to first generat a dataset of simulation inputs `X` and outputs `y`, and optimally have a basic understanding of Python and machine learning concepts.


generat --> generate

kallewesterling · 2024-03-05T09:42:40Z

docs/community/faq/faq-users.md

   <!-- Guidance on understanding the output of the software, including any metrics or visualizations it produces. -->
+   - See the [tutorial](../../tutorials/01_start.ipynb) for an example of how to interpret the results from `AutoEmulate`. Briefly, `X` and `y` are first split into training and test sets. Cross-validation and/or hyperparameter optimisation are performed on the training data. After comparing the results from different emulators, the user can evaluate the chosen emulator on the test set with `autoemulate.evaluate_model()`, and plot test set predictions with `autoemulate.plot_model()`. 


We could link autoemulate.evaluate_model() and autoemulate.plot_model() here to the API docs maybe?

yes, doing that now. @kallewesterling do you know whether there is a way to directly link to a class method (instead of just the class?)

kallewesterling · 2024-03-05T09:42:57Z

docs/community/faq/faq-users.md

   <!-- Details on the software's capabilities to leverage multi-threading, distributed computing, or HPC resources to speed up computations. -->
+   - Yes, `setup()` has an `n_jobs` parameter which allows to parallelise cross-validation and hyperparameter optimisation.


Let's link setup() to the API docs like above!

Linking now to the autoemulate.compare module, as I'm currently not sure how to link to a method within the module. I think this needs modification of the rst file, but i don't know whether this should be done manually.

kallewesterling · 2024-03-05T09:44:03Z

docs/community/faq/faq-users.md

   <!-- A list of frequently encountered problems with suggested solutions, possibly linked to a more extensive troubleshooting guide. -->
+   - TODO


Maybe @bryanlimy can be helpful here in coming up with commonly-run-into problems?

Once we have an option to adjust the verbosity of the codebase than that would be one way to see the underlying error/issue. RIght now I don't think there is easy way to debug the package (from a user perspective) without digging into the source code of both the codebase and the packages we use.

PR #200 now adds the option to log everything to a file or to print all logs to screen, and should capture the complete traceback when models fail. Will add this here.

kallewesterling · 2024-03-05T09:45:51Z

docs/community/faq/faq-users.md

   <!-- Instructions on the proper channels for reporting issues or suggesting enhancements, including any templates or information to include. -->
+   - Please open an issue using the [bug issue template](https://github.com/alan-turing-institute/autoemulate/issues/new/choose).


This actually links to the page where the user can open a bug issue report OR request a new feature, so good to have the link here but suggestion to write something like (this isn't great so feel free to edit): "You can report a bug or request new features through the issue templates in our GitHub repository. Head on over there and choose one of the templates for your purpose and get started."

Yes, agree, changed the text to your suggestion!

kallewesterling · 2024-03-05T09:46:30Z

docs/community/faq/faq-users.md

   <!-- Information on community-led projects, study groups, or collaborative research initiatives involving AutoEmulate. -->
+   - TODO


Always good to connect people up.. I wonder if we could mention for folks to reach out if they want invites to the Slack channel. That might be helpful for others, and we could invite them as guests to the channel.

Can we invite people from outside the Turing to the Slack channel?

I've added a sentence to reach out to you or me for now!

bryanlimy

LGTM for first release

bryanlimy · 2024-03-05T21:19:35Z

docs/community/faq/faq-users.md

   <!-- A list of frequently encountered problems with suggested solutions, possibly linked to a more extensive troubleshooting guide. -->
+   - TODO


Once we have an option to adjust the verbosity of the codebase than that would be one way to see the underlying error/issue. RIght now I don't think there is easy way to debug the package (from a user perspective) without digging into the source code of both the codebase and the packages we use.

codecov-commenter · 2024-03-06T11:18:12Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.68%. Comparing base (aa81a13) to head (f6476e1).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #197   +/-   ##
=======================================
  Coverage   90.68%   90.68%           
=======================================
  Files          45       45           
  Lines        2264     2264           
=======================================
  Hits         2053     2053           
  Misses        211      211

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

mastoffel · 2024-03-11T14:20:16Z

@kallewesterling do mind having a second look at this?

kallewesterling · 2024-03-11T15:30:46Z

I think it looks good as a start -- then we can iterate on improving the FAQ when we are done with AI UK! :)

mastoffel · 2024-03-11T15:41:43Z

I think it looks good as a start -- then we can iterate on improving the FAQ when we are done with AI UK! :)

Yes, maybe I've got some time before too.

add faq

abbef46

mastoffel requested review from kallewesterling and bryanlimy March 4, 2024 16:40

kallewesterling requested changes Mar 5, 2024

View reviewed changes

bryanlimy approved these changes Mar 5, 2024

View reviewed changes

address comments

1a6d0ca

mastoffel requested a review from kallewesterling March 6, 2024 11:13

prevent merge conflicts

5c8c396

resolve merge conflicts

f6476e1

kallewesterling approved these changes Mar 11, 2024

View reviewed changes

mastoffel merged commit 3caf548 into main Mar 11, 2024
6 checks passed

mastoffel deleted the faq branch March 11, 2024 15:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add faq #197

add faq #197

mastoffel commented Mar 4, 2024 •

edited

Loading

review-notebook-app bot commented Mar 4, 2024

mastoffel commented Mar 4, 2024

github-actions bot commented Mar 4, 2024 •

edited

Loading

kallewesterling left a comment

kallewesterling Mar 5, 2024

kallewesterling Mar 5, 2024

mastoffel Mar 6, 2024

kallewesterling Mar 5, 2024

kallewesterling Mar 5, 2024

mastoffel Mar 6, 2024 •

edited

Loading

kallewesterling Mar 5, 2024

mastoffel Mar 6, 2024

kallewesterling Mar 5, 2024

bryanlimy Mar 5, 2024

mastoffel Mar 6, 2024

kallewesterling Mar 5, 2024

mastoffel Mar 6, 2024

kallewesterling Mar 5, 2024

mastoffel Mar 6, 2024

mastoffel Mar 6, 2024

bryanlimy left a comment

bryanlimy Mar 5, 2024

codecov-commenter commented Mar 6, 2024 •

edited

Loading

mastoffel commented Mar 11, 2024

kallewesterling commented Mar 11, 2024

mastoffel commented Mar 11, 2024

		@@ -1,5 +1,7 @@
		# First-Time Contributors' Frequently Asked Questions

		TODO

		<!-- Information on the knowledge or data required to effectively use AutoEmulate, such as familiarity with Python, machine learning concepts, or specific data formats. -->
		- `AutoEmulate` is designed to be easy to use. The user has to first generat a dataset of simulation inputs `X` and outputs `y`, and optimally have a basic understanding of Python and machine learning concepts.

		<!-- Guidance on understanding the output of the software, including any metrics or visualizations it produces. -->
		- See the [tutorial](../../tutorials/01_start.ipynb) for an example of how to interpret the results from `AutoEmulate`. Briefly, `X` and `y` are first split into training and test sets. Cross-validation and/or hyperparameter optimisation are performed on the training data. After comparing the results from different emulators, the user can evaluate the chosen emulator on the test set with `autoemulate.evaluate_model()`, and plot test set predictions with `autoemulate.plot_model()`.

		<!-- Details on the software's capabilities to leverage multi-threading, distributed computing, or HPC resources to speed up computations. -->
		- Yes, `setup()` has an `n_jobs` parameter which allows to parallelise cross-validation and hyperparameter optimisation.

		<!-- A list of frequently encountered problems with suggested solutions, possibly linked to a more extensive troubleshooting guide. -->
		- TODO

		<!-- Instructions on the proper channels for reporting issues or suggesting enhancements, including any templates or information to include. -->
		- Please open an issue using the [bug issue template](https://github.com/alan-turing-institute/autoemulate/issues/new/choose).

		<!-- Information on community-led projects, study groups, or collaborative research initiatives involving AutoEmulate. -->
		- TODO

add faq #197

add faq #197

Conversation

mastoffel commented Mar 4, 2024 • edited Loading

review-notebook-app bot commented Mar 4, 2024

mastoffel commented Mar 4, 2024

github-actions bot commented Mar 4, 2024 • edited Loading

Coverage report

kallewesterling 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

mastoffel Mar 6, 2024 • edited Loading

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

bryanlimy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov-commenter commented Mar 6, 2024 • edited Loading

Codecov Report

mastoffel commented Mar 11, 2024

kallewesterling commented Mar 11, 2024

mastoffel commented Mar 11, 2024

mastoffel commented Mar 4, 2024 •

edited

Loading

github-actions bot commented Mar 4, 2024 •

edited

Loading

mastoffel Mar 6, 2024 •

edited

Loading

codecov-commenter commented Mar 6, 2024 •

edited

Loading