Add "how" argument to add_nested

[wilsonbb]

Change Description

Adds a how argument in add_nested to align with a traditional pandas join and in preparation from the change from add_nested to join_nested (see #120)

• My PR includes a link to the issue that I am addressing

Solution Description

The previous add_nested implementation packed the nested frame into a single column which is then assigned to our base layer. Here we simply add this column using a traditional join and then make use of the join's how argument. Since our previous implementation produces the same results as the "left" argument, I was concerned that replacing the single column assignment with a join might decrease performance. However a preliminary benchmarking shows no notable change.

Also of note here is that for the case of how="right", the nature of the packer still means that the result is implicitly using the index of our base layer but now drops values from it that were not present in the index of our "right" nested layer.

Code Quality

• I have read the Contribution Guide
• My code follows the code style of this project
• My code builds (or compiles) cleanly without any errors or warnings
• My code contains relevant comments and necessary documentation

Project-Specific Pull Request Checklists

New Feature Checklist

• I have added or updated the docstrings associated with my feature using the NumPy docstring format
• I have updated the tutorial to highlight my new feature (if appropriate)
• I have added unit/End-to-End (E2E) test cases to cover my new feature
• My change includes a breaking change
  • My change includes backwards compatibility and deprecation warnings (if possible)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.44%. Comparing base (bcaf1b8) to head (183b1b9).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #125      +/-   ##
==========================================
- Coverage   99.44%   99.44%   -0.01%     
==========================================
  Files          14       14              
  Lines         898      896       -2     
==========================================
- Hits          893      891       -2     
  Misses          5        5              

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

[github-actions]

Before [bcaf1b8]	After [1714c0a]	Ratio	Benchmark (Parameter)
29.9±0.8ms	32.3±3ms	1.08	benchmarks.AssignSingleDfToNestedSeries.time_run
9.01±0.2ms	9.59±0.1ms	1.06	benchmarks.NestedFrameAddNested.time_run
6.30±0.08ms	6.62±0.07ms	1.05	benchmarks.NestedFrameQuery.time_run
57.4±1ms	59.1±2ms	1.03	benchmarks.ReassignHalfOfNestedSeries.time_run
91.5M	92.2M	1.01	benchmarks.NestedFrameQuery.peakmem_run
90.2M	90.9M	1.01	benchmarks.NestedFrameReduce.peakmem_run
1.11±0ms	1.12±0ms	1.01	benchmarks.NestedFrameReduce.time_run
278M	281M	1.01	benchmarks.ReassignHalfOfNestedSeries.peakmem_run
260M	261M	1	benchmarks.AssignSingleDfToNestedSeries.peakmem_run
86.9M	87.3M	1	benchmarks.NestedFrameAddNested.peakmem_run

Click here to view all benchmarks.

[dougbrn]

Nice looks good!