Add type hints and comprehensive docstrings to utility functions in util.py

[aadi-9]

Problem

Hi,
As a new user interested in this project for GSOC 2026, I noticed several utility functions in malariagen_data/util.py lack complete type hints and/or have minimal or missing docstrings. This makes the code harder to understand, maintain, and use in new functionality—especially for natural-language interfaces and other tools that need to understand parameter and return types.

Affected functions:

• _true_runs()
• _hash_params()
• _jitter()
• _value_error()
• _da_concat()
• _jackknife_ci()
• _pdist_abs_hamming()

Proposed Solution

Add type hints (PEP 484) and NumPy-style docstrings to all listed functions, following the project's numpydoc format.

Impact

•Improves code clarity and IDE support
•Helps contributors understand function purpose and usage
•Supports type checking tools (mypy)
•Enables better natural-language interface development
•Aligns with project code style guidelines

This contributes to overall code quality and maintainability

[khushthecoder]

Hi @jonbrenas,

Why this is important & The Impact

While these are internal functions, explicitly defining their parameter boundaries and return types is highly impactful for new contributors and downstream tooling. It drastically improves IDE support (auto-completion, inline hints), enables better static analysis (like mypy), and makes the codebase much easier to interpret without needing to parse the underlying logic. Ultimately, it lowers the barrier to entry for reading and maintaining util.py.

My approach

I've opened a PR to add strict PEP 484 type hints and NumPy-style docstrings to the 7 affected functions. My main priority was ensuring zero behavioral changes:

• Standard Python functions: Used the most precise pragmatic types (e.g., Sequence[da.Array] for concatenation, NoReturn for error helpers)
• Numba-jitted functions (_true_runs, _pdist_abs_hamming): Carefully stuck to base np.ndarray typing rather than overconstraining them in ways that could accidentally break the Numba compiler — shape and rank rules are defined in the docstrings instead

I'd love your feedback! I have submitted PR #1213 addressing this issue — could you please review it when you get a chance?

[jonbrenas]

Hi @khushthecoder, could you help @aadi-9 improve his PR (assuming you think yours is an improvement)?

[khushthecoder]

Hi @jonbrenas, absolutely — happy to help!

I've compared both PRs and here's a summary of the differences:

@aadi-9's PR #1142 covers 4 functions with good docstrings, but is missing type hints on the function signatures for _jitter, _hash_params, and _value_error (only _da_concat had existing hints). It also doesn't include return type annotations.

My PR #1213 covers all 7 functions mentioned in #1141 (including _true_runs, _jackknife_ci, and _pdist_abs_hamming), adds full PEP 484 type hints and return types on every signature, adds the necessary typing imports (Any, NoReturn, Sequence), and includes extra Notes sections for edge cases (e.g., Numba-safe annotations, non-determinism in _jitter).

---

@aadi-9, I'd be happy to collaborate! Here are some suggestions to bring your PR up to full coverage:

1. Add type hints to the signatures of _jitter, _hash_params, and _value_error — including return types like -> NoReturn for _value_error and -> Tuple[str, str] for _hash_params
2. Cover the remaining 3 functions: _true_runs, _jackknife_ci, and _pdist_abs_hamming — these are also listed in Add type hints and comprehensive docstrings to utility functions in util.py #1141
3. Add the typing imports at the top of the file: Any, NoReturn, and Sequence

Feel free to reference my PR for the exact annotations and docstring text — happy for you to use any of it. Let me know if you'd like me to push suggestions directly to your branch, or if there's another way you'd prefer to collaborate!

[aadi-9]

Hi @jonbrenas @khushthecoder ,

I went through @khushthecoder's PR regarding this issue and have updated my PR #1142 to include his helpful suggestions.
I have specified the type hints and updated the docstrings for all the 7 functions accordingly, including the 3 additional functions : _true_runs, _jackknife_ci, and _pdist_abs_hamming
Thank you for your input!

Summary of Changes

1. Import Statement Reorganization

• Expanded imports to include additional types: Any, NoReturn, and Sequence
• Formatted typing imports on separate lines for better readability

2. Function Signature Improvements

Function	Changes
_da_concat()	Changed List[da.Array] → Sequence[da.Array]; Added **kwargs: Any
_value_error()	Added full type hints: name: str, value: object, expectation: str → NoReturn
_hash_params()	Added params: Any → Tuple[str, str]
_jitter()	Added a: Union[np.ndarray, pd.Series], fraction: float → Union[np.ndarray, pd.Series]
_jackknife_ci()	Added all parameter types and return type Tuple[float, float, float, float, float, float]

3. Enhanced Docstrings

Added or improved NumPy-style docstrings for several functions:

• _value_error() - Added "Returns" section clarifying it never returns
• _hash_params() - Added "Notes" section explaining stable JSON serialization
• _jitter() - Improved descriptions and added edge-case note about zero range
• _jackknife_ci() - Added specific types for all return values
• _true_runs() - New comprehensive docstring (Parameters, Returns, Notes)
• _pdist_abs_hamming() - New comprehensive docstring with performance notes

4. Type Consistency

• Replaced generic List with more flexible Sequence where appropriate
• Added specific return type annotations (NoReturn for functions that always raise)
• Improved parameter type specificity (object for generic values)

[khushthecoder]

Hi @aadi-9, awesome work on the updates! Thanks for being so quick and open to collaboration. Your summary of changes looks comprehensive and spot on.

@jonbrenas — since @aadi-9's PR (#1142) now successfully covers all 7 functions and incorporates the type hints and docstrings we discussed for #1141, I'll go ahead and close my PR (#1213) in favor of his to keep the review queue clean.

Thanks both for the smooth collaboration! Let me know if there's anything else I can help with here.