Convert markdown tutorial to jupyter tutorial #101 #135
Conversation
Inital commit to convert exisitng tutorial format from md to jupyter tutorial
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #135 +/- ##
=======================================
Coverage ? 91.78%
=======================================
Files ? 11
Lines ? 1680
Branches ? 0
=======================================
Hits ? 1542
Misses ? 138
Partials ? 0 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
try building the documentation to see if it gives a correct output. in case of errors, make the necessary adjustments |
Error is fixed for tutorial "Running the model" cell, which used to display distribution stats
@adamamer20 "running the model" cell tutorial example is fixed, looking into performance comparison |
Updated Performance comparison code for support for jupyter based markdown page
|
@adamamer20 updated the tutorial page along with running code, please review and suggest if missing anything |
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughThis pull request introduces an introductory tutorial for the Boltzmann Wealth Model using the mesa-frames library. The notebook explains the model's functionality, simulates wealth distribution among agents, and demonstrates the implementation of several new classes for managing agents and model behavior. It includes variants for both pandas and Polars data handling, provides concise and native implementations, and introduces a helper function to run the simulation over specified steps. The tutorial further presents performance comparisons between the two backends, emphasizing the improved efficiency of the mesa-frames approach. Changes
Sequence Diagram(s)sequenceDiagram
participant U as User
participant RS as run_simulation
participant M as MoneyModelDF
participant A as MoneyAgent (Multiple Variants)
U->>RS: Invoke simulation(model_class, n_agents, n_steps)
RS->>M: Instantiate MoneyModelDF with agent data
M->>A: Initialize agents (pandas/Polars variations)
loop Simulation Steps
M->>A: Agents execute give_money operations
end
M-->>RS: Return final wealth distribution
RS-->>U: Provide simulation results and performance stats
Poem
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/general/user-guide/2_introductory-tutorial.ipynb (2)
22-23: Remove unused imports.The imports of
attr.validatorsandnumbadon't appear to be used anywhere in the notebook.-from attr.validators import instance_of -from numba import typeof from mesa_frames import ModelDF, AgentSetPandas, AgentSetPolars
453-453: Remove unused variable assignment.The assignment
a=1is never used in the code.n_agents_list = [100000, 300000, 500000, 700000] n_steps = 100 -a=1 print("Execution times:")
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/general/user-guide/2_introductory-tutorial.ipynb(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: build (windows, 3.12)
🔇 Additional comments (11)
docs/general/user-guide/2_introductory-tutorial.ipynb (11)
27-39: LGTM! ModelDF implementation looks good.The
MoneyModelDFclass is well-structured with clear initialization, step, and run_model methods that will work with both pandas and Polars implementations.
67-82: LGTM! MoneyAgentPandas implementation is correct.The implementation properly handles agent selection, money transfer, and wealth updates using pandas operations.
103-118: LGTM! MoneyAgentPolars implementation is correct.The implementation correctly adapts the pandas approach to use Polars-specific methods like
group_by,len(), andwith_replacement.
139-148: LGTM! Code for running the model is clear and functional.The code correctly shows how to instantiate the model with a chosen agent class, run it for 100 steps, and display the final wealth distribution statistics.
204-262: LGTM! Polars concise implementation with clear comments.The
MoneyAgentPolarsConciseclass is well-commented with alternative approaches, making it educational for users learning the API.
264-297: LGTM! Native Polars implementation looks efficient.The
MoneyAgentPolarsNativeclass uses Polars' native operations for better performance.
300-340: LGTM! Pandas concise implementation with clear comments.Similar to the Polars implementation, the
MoneyAgentPandasConciseclass is well-documented with alternative approaches.
343-373: LGTM! Native pandas implementation follows good practices.The
MoneyAgentPandasNativeclass correctly uses pandas' native operations for performance.
392-428: LGTM! Standard Mesa implementation for comparison.The traditional Mesa implementation is correctly structured for performance comparison.
486-567: LGTM! Performance comparison output is comprehensive.The documentation of performance results is thorough and clearly demonstrates the speed advantages of mesa-frames over the original mesa implementation.
575-583: LGTM! Excellent conclusion summarizing key findings.The conclusion effectively summarizes the performance advantages of using mesa-frames, especially with the Polars backend.
There was a problem hiding this comment.
The documentation seems to build correctly but the overall objective is to have the notebook be executed when the documentation is being built and give the output.
Follow the necessary steps from the reference here: https://github.com/danielfrg/mkdocs-jupyter#readme
Adding execute to true in yml to make sure the notebooks run when doc is build and generate output
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
mkdocs.yml (2)
47-48: Enable Execution in mkdocs-jupyter PluginThe updated configuration now explicitly sets
execute: truefor themkdocs-jupyterplugin. This is a crucial change ensuring that when the documentation is built, any embedded Jupyter notebooks (such as the newly converted introductory tutorial) will be executed to generate live outputs. Please verify that executing these notebooks during build does not introduce performance issues or side effects in your documentation pipeline.
107-114: Verify Navigation File ReferencesAlthough not part of the explicit diff, the navigation section still references the tutorial as
user-guide/2_introductory-tutorial.md. Since this PR’s objective is to convert the tutorial to Jupyter Notebook format, please confirm that the navigation entry is updated to reflect the correct file extension (e.g.,.ipynb) if applicable. This will ensure that users are directed to the executable notebook rather than an outdated markdown file.🧰 Tools
🪛 YAMLlint (1.35.1)
[warning] 111-111: wrong indentation: expected 6 but found 4
(indentation)
@adamamer20 Updated config in yml to make sure the notebooks run when doc is build and generate output |
updating refernce to 2_introductory-tutorial.ipynb in yml file
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
fixed mesa example code to run
Updating indentation as find pre-check failing with unexpected unindented whereas code running successfully in local system
for more information, see https://pre-commit.ci
|
@adamamer20 fix's are done and passed all checks |
|
Now it's ready to be merged! |
|
I will ask a review from coderabbit to test it out a bit @coderabbitai review |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain@adamamer20 I'll review this PR for you. Let me first check what files have been changed so I can provide a comprehensive review. 🏁 Script executed: Length of output: 70 @adamamer20 I encountered an issue with the git command. Let me try a different approach to identify the files changed in this PR. 🏁 Script executed: Length of output: 224 @adamamer20 Thanks for the information. I've identified the files changed in this PR. Now I'll examine the specific changes to conduct a proper review. 🏁 Script executed: Length of output: 15017 @adamamer20 I'll continue examining the files. Let me check if there was an original markdown file and see the configuration changes in mkdocs.yml. 🏁 Script executed: Length of output: 10307 @adamamer20 I'm continuing my review of this PR by checking the original markdown content to understand what was converted to the Jupyter notebook format. 🏁 Script executed: Length of output: 5475 @adamamer20 I've completed my review of this PR which converts the markdown tutorial to a Jupyter notebook format. Here's my assessment: What I Like
Improvements
Suggestions
Overall, this PR represents a significant improvement to the documentation. The tutorial is now more interactive and educational, providing a better experience for users learning the mesa-frames library. 🐰 CodeRabbit is happy to help with testing the new interactive documentation! |
Converted the introductory tutorial (/mesa-frames/docs/general/user-guide) from Markdown to Jupyter format, Please Review and let me know if any other files to be converted
Now code is able to run and execute in the tutorial itself and in case of success/error it is able to show the output
NOTE: I tried to run the code and all the cells above the "Running the code" cell were able to run on tutorial itself but I found when I tried to run the "Running the code" cell it gives an error, good part is I am able to see the output(error) there itself
so looks like Example code has a few error and may need fixes , would you like to create a new issue to fix the Tutorial code.
Summary by CodeRabbit