DONT_MERGE: GSOC26: Add beginner-friendly examples for nesting and .eval()

[het1803]

I am Het and I've updated the documentation to address Issue #153.

I noticed that while the library has powerful features like .eval() and nested packing, the tutorials were missing simple, relatable examples for beginners.

In this PR, I have added:

1. A star-brightness scenario to demonstrate how to pack flat data into nested columns.
2. Practical examples of using .eval() to perform calculations within nested columns (Issue Use custom resolver for query and eval with nested frames. #150).
3. Examples of combining flat columns with nested aggregations like .median().

This should make the library much more accessible to new users.

[hombit]

@het1803 thanks for the submission. I've tried to copy, paste, and run the code, and it failed. Could you please fix it?

[het1803]

Hi @hombit , I apologize for the inconvenience. I am looking into the indentation of the code snippets right now and will push a fix in a few minutes. Thanks for the quick feedback!

[het1803]

Hi @hombit ,

I have updated the documentation to include the beginner-friendly .eval() examples as requested.I also checked and corrected the documentation issues.I noticed that the automated build failed with an error, but looking at the logs, it seems to be a transient network issue during the git clone step (Error while cloning the repository...).Let me know if any further tweaks are needed.
Thanks!

[hombit]

@het1803 Yes, there is some issue with GitHub right now. I've manually re-run the ReadTheDocs pipeline, and it builds now. However, the code example you put there still doesn't work.
I also don't see why the examples should go to the tutorials index page. Could you please find a better place for them?

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[het1803]

Hi @hombit, thank you for the feedback. I have updated the PR with the following changes:

Location: Moved the .eval() examples from the index page (tutorials.rst) to the end of the docs/tutorials/data_manipulation.ipynb notebook, as it is a more appropriate place for these examples.

Code Fix: I verified the previous code was failing because DataFrameGroupBy does not support the .nested accessor for packing in this version. I have updated the example to use npd.NestedFrame.from_flat(), which works correctly.

Variable Injection: Replaced the @variable syntax with a Python f-string to properly pass the local variable into the .eval() method.

I have tested these snippets locally, and they generate the expected nested structures without any errors. Let me know if everything looks good now!

[hombit]

@het1803 It runs now, thank you! Let's change "brightness" to more astronomical terminology, e.g., "magnitude"?

[het1803]

Hi @hombit, I've updated the notebook to use astronomical terminology (mag instead of brightness) and ensured all examples use the from_flat method and f-strings for consistency.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.30%. Comparing base (6f02f6c) to head (0e2fcc9).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #461   +/-   ##
=======================================
  Coverage   97.30%   97.30%           
=======================================
  Files          19       19           
  Lines        2156     2156           
=======================================
  Hits         2098     2098           
  Misses         58       58           

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Before [1f834d0]	After [a1e3435]	Ratio	Benchmark (Parameter)
168±80ms	152±90ms	~0.91	benchmarks.ReadFewColumnsHTTPS.time_run
1.10±0.03s	1.14±0.04s	1.04	benchmarks.ReadFewColumnsS3.time_run
137M	141M	1.03	benchmarks.CountNestedBy.peakmem_run
257M	258M	1.01	benchmarks.AssignSingleDfToNestedSeries.peakmem_run
10.7±0.02ms	10.8±0.1ms	1.01	benchmarks.NestedFrameQuery.time_run
66.5±0.8ms	66.5±0.3ms	1.00	benchmarks.CountNestedBy.time_run
105M	105M	1.00	benchmarks.NestedFrameAddNested.peakmem_run
110M	110M	1.00	benchmarks.NestedFrameQuery.peakmem_run
109M	109M	1.00	benchmarks.NestedFrameReduce.peakmem_run
50.1±1ms	50.3±0.4ms	1.00	benchmarks.ReassignHalfOfNestedSeries.time_run

Click here to view all benchmarks.

[hombit]

@het1803 thank you! Could you please fix the pre-commit CI failure?

[het1803]

@hombit, I have fixed the pre-commit CI failures locally by clearing the notebook outputs and formatting the code using ruff. I'm pushing the clean version now. Thanks for pointing it out!

[hombit]

@het1803 thanks, I consider this PR as finished!

[het1803]

Thank you @hombit! Happy to see this PR finalized.

Since I'm very interested in the project, I'd love to contribute further. Are there any other high-priority issues, hidden bugs, or areas in the documentation (like more complex .eval() or .query() examples) that you’d like me to look into?

I'm also open to helping with any refactoring or unit tests if needed!

[het1803]

Hi @hombit, I have marked the PR as Ready for Review. Please let me know if there's anything else needed before merging!

[hombit]

@het1803 we are not merging any of the PRs until the end of the GSoC proposal period. We will keep it as a draft and unmerged until then. You are welcome to submit other PRs without "GSOC26" in the title, only the first one (this one) will be considered during the GSoC contributor selection.
Please see Slack for more details.