refactor: replace hyperpixel terminology with region

[dhalmazna]

Note to reviewers:
⚠️ This is part of a stacked PR. Please review the PR #13 first. I accidentally created this PR first, even though it depends on #13.

Context:
This PR updates the terminology across the entire codebase, replacing the custom term "hyperpixel" with the more standard and intuitive term "region".

What's Changed:

• Renamed classes & types: HyperpixelResult -> RegionResult.
• Renamed functions: e.g., build_all_hyperpixels -> build_all_regions, calculate_hyperpixel_deltas -> calculate_region_deltas.
• Renamed files: ciao/scoring/hyperpixel.py -> ciao/scoring/region.py.
• Updated variable names, docstrings, and the README.md to reflect the new terminology.

Note:
This is a pure naming refactoring PR. There are no changes to the underlying algorithmic logic or mathematical operations.

Related Task:
XAI-29

Summary by CodeRabbit

• Refactor
  • Updated explainer API: max_hyperpixels parameter renamed to max_regions
  • Changed explanation result structure: results now use regions field instead of hyperpixels

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR renames the terminology from "hyperpixels" to "regions" across the codebase, affecting function names, parameters, return types, dataclass fields, and documentation. Changes span the algorithm, scoring, explainer, and typing modules without altering control flow or logic.

Changes

Cohort / File(s)	Summary
Documentation README.md	Updated text and project structure comments to replace "hyperpixels" with "regions" and hyperpixel.py with region.py.
Algorithm Module Exports & Utilities ciao/algorithm/__init__.py, ciao/algorithm/context.py, ciao/algorithm/graph.py	Renamed exported functions (build_all_hyperpixels → build_all_regions, build_hyperpixel_greedy_lookahead → build_region_greedy_lookahead) and updated docstrings to reference "regions" instead of "hyperpixels".
Algorithm Builder ciao/algorithm/builder.py	Renamed entry point, parameters, and internal variables from hyperpixel-based names to region-based names; return type changed from HyperpixelResult to RegionResult.
Algorithm Lookahead ciao/algorithm/lookahead.py	Renamed function from build_hyperpixel_greedy_lookahead to build_region_greedy_lookahead, updated return type to RegionResult, and replaced scoring function calls from calculate_hyperpixel_deltas to calculate_region_deltas.
Scoring Module Exports & Definitions ciao/scoring/__init__.py, ciao/scoring/region.py	Removed hyperpixel-based re-exports and added region-based equivalents; renamed dataclass HyperpixelResult → RegionResult and functions (calculate_hyperpixel_deltas → calculate_region_deltas, select_top_hyperpixels → select_top_regions).
Scoring Surrogate Dataset ciao/scoring/segments.py	Updated delta computation call from calculate_hyperpixel_deltas to calculate_region_deltas.
Explainer API & Methods ciao/explainer/ciao_explainer.py, ciao/explainer/explanation_methods.py	Changed ExplanationResult field from hyperpixels: list[HyperpixelResult] to regions: list[RegionResult]; updated CIAOExplainer.explain() parameter from max_hyperpixels to max_regions; updated lookahead method factory to return RegionResult.
Type Definitions ciao/typing.py	Updated type-only import and return type of ExplanationMethodFn from HyperpixelResult to RegionResult.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: implement CIAO explainer pipeline and strategy pattern for configurations #10: Directly introduced the symbols being renamed in this PR (e.g., build_all_hyperpixels, HyperpixelResult, build_hyperpixel_greedy_lookahead).
• feat: add greedy lookahead algorithm with rolling horizon for hyperpixel building #9: Originally implemented the greedy lookahead builder that is being renamed and refactored here.
• refactor: add search helpers and rename parameters #8: Performed overlapping refactors on scoring deltas, image graph utilities, and search helpers that are touched in this rename.

Suggested reviewers

• vejtek
• vojtech-kur
• Adames4

Poem

🐰 Hoppy refactoring, a naming spree so grand,
From "hyperpixels" to "regions" across the land!
Terminology clearer, consistency crowned,
In every module, the new terms are found. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 76.92% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor: replace hyperpixel terminology with region' clearly and concisely describes the main objective of the pull request—a global terminology refactor replacing hyperpixel with region across the codebase.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/hyperpixel-to-region

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request implements a project-wide refactoring to rename 'hyperpixel' to 'region' across documentation, function signatures, and class names. The review feedback identifies opportunities to further improve consistency and clarity by removing redundant terminology in the README and renaming internal variables and lambda parameters that still reference the old naming convention.

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

ciao/scoring/region.py (1)

157-167: Use region-aligned local naming in sorter for consistency.

The lambda variable hp still carries old terminology. Renaming it improves clarity and completes the terminology sweep.

♻️ Suggested cleanup

     return sorted(
         regions,
-        key=lambda hp: abs(hp.score),
+        key=lambda region_result: abs(region_result.score),
         reverse=True,
     )[:max_regions]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@ciao/scoring/region.py` around lines 157 - 167, The sorter in
select_top_regions uses an outdated lambda parameter name `hp`; rename that
parameter to a region-aligned name (e.g., `region` or `r`) in the key lambda
(key=lambda region: abs(region.score)) to match current terminology and improve
clarity when locating the function select_top_regions and its sorting logic.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@ciao/algorithm/__init__.py`:
- Around line 3-7: The package removed legacy exported symbols (e.g.,
build_all_regions, SearchContext, ImageGraph, build_region_greedy_lookahead,
is_terminal) which is a breaking API change; restore backward compatibility by
re-exporting the old names in ciao.algorithm.__init__ as aliases to the new
implementations and emit a DeprecationWarning when those legacy names are
accessed (use warnings.warn with category=DeprecationWarning inside the module
or property wrappers) so consumers get a migration notice; alternatively, if you
intend a breaking release, update the package documentation/release notes with
clear migration steps for each symbol instead of adding aliases.

In `@ciao/algorithm/builder.py`:
- Around line 20-23: Add a fast-fail guard for the max_regions parameter: at the
start of the function whose signature ends with "max_regions: int,
desired_length: int = 30, batch_size: int = 64,) -> list[RegionResult]" (and the
other occurrence with the same parameter) validate that max_regions > 0 and
raise a ValueError with a clear message (e.g. "max_regions must be > 0") if not;
place the check before any processing so invalid configs fail fast.

In `@ciao/scoring/__init__.py`:
- Around line 3-7: The public API removed legacy exported names causing
import-time breakage; restore compatibility by adding aliases in
ciao.scoring.__init__ that map the old symbols to the new ones (e.g., set
OldRegionResult = RegionResult, old_calculate_region_deltas =
calculate_region_deltas, old_select_top_regions = select_top_regions based on
the legacy names removed) and emit a DeprecationWarning via warnings.warn when
those legacy names are present, and update __all__ to include both new and
aliased legacy names so downstream users continue to import while being informed
to migrate.

In `@README.md`:
- Line 3: The opening description contains a duplicated phrase "important
regions (regions)"; update the sentence to remove the redundant parenthetical so
it reads smoothly (for example change "important regions (regions)" to just
"important regions" or provide an alternative clarification like "important
regions (segments)"). Edit the README's introductory sentence accordingly to
eliminate the duplication.

---

Nitpick comments:
In `@ciao/scoring/region.py`:
- Around line 157-167: The sorter in select_top_regions uses an outdated lambda
parameter name `hp`; rename that parameter to a region-aligned name (e.g.,
`region` or `r`) in the key lambda (key=lambda region: abs(region.score)) to
match current terminology and improve clarity when locating the function
select_top_regions and its sorting logic.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 69409fe2-6990-445a-a3e3-48f80b736f16

📥 Commits

Reviewing files that changed from the base of the PR and between 8752ffa and b9d5649.

📒 Files selected for processing (11)

• README.md
• ciao/algorithm/__init__.py
• ciao/algorithm/builder.py
• ciao/algorithm/context.py
• ciao/algorithm/graph.py
• ciao/algorithm/lookahead.py
• ciao/explainer/ciao_explainer.py
• ciao/explainer/methods.py
• ciao/scoring/__init__.py
• ciao/scoring/region.py
• ciao/scoring/segments.py

[Copilot]

Pull request overview

This PR standardizes terminology across the CIAO codebase by replacing the custom term “hyperpixel” with the more conventional “region”, updating type names, function names, module names, and documentation accordingly.

Changes:

• Renamed core scoring/result APIs from Hyperpixel* to Region* (including module rename to ciao.scoring.region).
• Renamed algorithm entrypoints and explanation method wiring to *_region_* equivalents.
• Updated docstrings and README to reflect the new “region” terminology.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
ciao/typing.py	Updates ExplanationMethodFn to return RegionResult.
ciao/scoring/segments.py	Switches surrogate dataset delta computation to calculate_region_deltas.
ciao/scoring/region.py	Introduces/renames region-centric result type and scoring helpers.
ciao/scoring/__init__.py	Updates scoring package exports to region-based API names.
ciao/explainer/explanation_methods.py	Updates lookahead method factory to return RegionResult via renamed builder.
ciao/explainer/ciao_explainer.py	Renames explainer params/results from hyperpixels to regions and updates builder call.
ciao/algorithm/lookahead.py	Renames greedy lookahead builder and uses region delta function/result type.
ciao/algorithm/graph.py	Updates docstrings to “region” terminology.
ciao/algorithm/context.py	Updates SearchContext docstring to “region” terminology.
ciao/algorithm/builder.py	Renames orchestrator to build_all_regions and updates internal variable naming.
ciao/algorithm/__init__.py	Updates algorithm package exports to region-based API names.
README.md	Replaces “hyperpixel” wording with “region” in documentation and structure overview.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

The base branch was changed.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@ciao/explainer/ciao_explainer.py`:
- Around line 20-28: The rename of the public API breaks callers: restore
deprecated aliases so both names work for one release by adding a shim on
ExplanationResult that preserves the old dataclass field name hyperpixels
(backing it to regions) and update CIAOExplainer.explain to accept the legacy
kwarg max_hyperpixels and map it to max_regions (with a deprecation warning when
max_hyperpixels is used); ensure the alias supports both read and write access
for ExplanationResult.regions/hyperpixels and emit a clear warning in
CIAOExplainer.explain when the legacy kwarg is supplied.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5748c934-4de8-481b-9c84-27282370b0ee

📥 Commits

Reviewing files that changed from the base of the PR and between b9d5649 and 319b2aa.

📒 Files selected for processing (12)

• README.md
• ciao/algorithm/__init__.py
• ciao/algorithm/builder.py
• ciao/algorithm/context.py
• ciao/algorithm/graph.py
• ciao/algorithm/lookahead.py
• ciao/explainer/ciao_explainer.py
• ciao/explainer/explanation_methods.py
• ciao/scoring/__init__.py
• ciao/scoring/region.py
• ciao/scoring/segments.py
• ciao/typing.py

✅ Files skipped from review due to trivial changes (5)

• ciao/algorithm/graph.py
• ciao/algorithm/context.py
• README.md
• ciao/algorithm/init.py
• ciao/typing.py

🚧 Files skipped from review as they are similar to previous changes (5)

• ciao/scoring/segments.py
• ciao/scoring/init.py
• ciao/algorithm/lookahead.py
• ciao/algorithm/builder.py
• ciao/scoring/region.py