Method Chaining & Return Values

H3Toolkit is designed around the method chaining pattern for a fluent, readable API. Understanding the return values of different methods is key to using the toolkit effectively.

Design Philosophy

The toolkit follows this principle:

• Most methods return `H3Toolkit` (self) to enable method chaining

• `get_result()` returns the processed DataFrame/GeoDataFrame

• `show()` intelligently returns based on usage: - Returns pydeck.Deck when displaying maps in Jupyter - Returns H3Toolkit when saving to HTML files

This design allows you to chain operations naturally while still being able to extract results or visualize data.

Method Return Values

Data Processing & Configuration

These methods perform operations on the H3Toolkit’s internal data and return self:

• `set_aggregation_strategy()` – Configure aggregation functions for data processing

• `set_hbase_client()` – Configure HBase connection parameters

• `process_from_vector()` – Convert vector geometry to H3 indexes

• `process_from_raster()` – Convert raster data to H3 indexes

• `process_from_h3()` – Aggregate or rescale H3 data to different resolutions

• `fetch_from_hbase()` – Fetch H3 data from HBase storage

• `send_to_hbase()` – Write H3 data to HBase storage

• `apply()` – Apply custom Polars transformations to data

Return type: H3Toolkit (enables chaining)

Result Extraction

• `get_result(return_geometry=False)` – Extract the final processed data

  • Return type: polars.DataFrame or geopandas.GeoDataFrame

  • Use this at the end of a chain to get your actual data

Visualization

• `show(target_col, classifier=’NaturalBreaks’, k=5, cmap=’Oranges’, save_to=None, **pydeck_kwargs)`

  • When `save_to=None` (display map): - Return type: pydeck.Deck - Automatically renders as interactive map in Jupyter notebooks

  • When `save_to=’file.html’` (save map): - Return type: H3Toolkit (self) - Enables continued method chaining after saving

Usage Patterns

Complete Chaining Workflow

Process data through multiple steps, then extract results:

from h3_toolkit import H3Toolkit
from h3_toolkit.aggregation import SumUp

result_df = (
    toolkit
    .set_aggregation_strategy({'population': SumUp()})
    .process_from_vector(geo_df, resolution=12)
    .process_from_h3(target_resolution=10)
    .get_result()  # Extract DataFrame at the end
)

Visualization with Chaining

Chain operations, then visualize or save the map:

# Display interactive map in Jupyter
toolkit.show('population', classifier='Quantiles', k=5)

# Or save map to HTML file and continue chaining
result = (
    toolkit
    .process_from_vector(geo_df)
    .show('population', save_to='map.html')  # Returns toolkit
    .get_result()  # Can still continue chaining
)

Complete Workflow

Chain everything from data loading to visualization:

result = (
    toolkit
    .set_aggregation_strategy({'p_cnt': SumUp()})
    .process_from_vector(geo_df, resolution=12)
    .process_from_h3(target_resolution=10)
    .show('p_cnt', cmap='viridis', save_to='output.html')  # Returns toolkit
    .apply(lambda df: df.filter(pl.col('p_cnt') > 1000))  # Filter data
    .get_result()  # Get final filtered DataFrame
)

Return Value Summary Table

H3Toolkit Method Return Values

Method Group	Return Type	Purpose
Data Processing	H3Toolkit	Enable method chaining
process_from_vector()	H3Toolkit	Convert vector → H3
process_from_raster()	H3Toolkit	Convert raster → H3
process_from_h3()	H3Toolkit	Aggregate/rescale H3 data
Data Source	H3Toolkit	Enable method chaining
fetch_from_hbase()	H3Toolkit	Load data from HBase
send_to_hbase()	H3Toolkit	Write data to HBase
Configuration	H3Toolkit	Enable method chaining
set_aggregation_strategy()	H3Toolkit	Configure aggregations
set_hbase_client()	H3Toolkit	Configure HBase client
apply()	H3Toolkit	Apply custom transformations
Result Extraction	DataFrame	Get final data
get_result()	DataFrame or GeoDataFrame	Extract processed data
Visualization	Deck or H3Toolkit	Display or save map
show(save_to=None)	pydeck.Deck	Display map in Jupyter
show(save_to=’file’)	H3Toolkit	Save map + enable chaining

Benefits of This Design

1. Fluent API – Chain operations naturally, left-to-right

2. Readable Code – Operations read like a pipeline

3. Flexible Extraction – Extract data at any point in the chain

4. Smart Visualization – Return values adapt to your use case

# Easy to read and understand
result = (
    toolkit
    .process_from_vector(geo_df)
    .show('value')  # Displays map immediately
)

# Same code, different intent – save instead
result = (
    toolkit
    .process_from_vector(geo_df)
    .show('value', save_to='map.html')  # Saves to file
    .get_result()  # Get data
)