feat: allow NaN in targets when masks are provided for metric computation

[haoyu-haoyu]

Summary

Implements the feature requested in #708 (and attempted in the now-closed PR #707).

When evaluating imputation on irregularly sampled time series, the ground truth (targets) itself may contain NaN values at naturally missing positions. Previously, _check_inputs() rejected any NaN in targets unconditionally, blocking this legitimate workflow.

Why PR #707 failed

The previous attempt used logical_not incorrectly (reversed mask semantics — PyPOTS convention is mask=1 for observed, mask=0 for missing) and didn't complete tests before being auto-closed.

The hidden trap: NaN * 0 = NaN

Simply removing the NaN assertion is not sufficient. In both NumPy and PyTorch, NaN * 0 produces NaN, not 0. So even when the mask correctly zeroes out NaN positions, the arithmetic (predictions - targets) * masks will propagate NaN through the result. The fix must replace NaN with 0 in targets before any arithmetic.

Solution

_check_inputs() now returns (lib, targets, masks) instead of just lib:

# When masks provided AND targets contain NaN:
# 1. Extend mask to exclude NaN positions
nan_free = (~isnan(targets)).to(masks.dtype)
masks = masks * nan_free

# 2. Replace NaN with 0 to prevent NaN * 0 = NaN propagation
targets = where(isnan(targets), zeros_like(targets), targets)

Three behaviors:

Scenario	Result
targets NaN-free	Unchanged (backward compatible)
targets has NaN + masks provided	Auto-extend mask + replace NaN with 0
targets has NaN + no masks	ValueError with clear message

Example

import numpy as np
from pypots.nn.functional import calc_mae

predictions = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
targets = np.array([1.0, np.nan, 3.0, 4.0, np.nan])  # NaN at positions 1, 4
masks = np.array([1, 1, 1, 1, 1])  # Initially all observed

# Before: AssertionError ("targets mustn't contain NaN")
# After:  mae = 0.0 (NaN positions auto-masked, remaining values match)
mae = calc_mae(predictions, targets, masks)

Files changed

File	Change
pypots/nn/functional/error.py	_check_inputs returns (lib, targets, masks), all calc_* functions updated

Test plan

import numpy as np, torch
from pypots.nn.functional import calc_mae, calc_mse, calc_rmse, calc_mre

# Backward compat — NaN-free targets work as before
calc_mae(np.array([1,2,3]), np.array([1,2,4]))  # ✓

# NaN targets with masks — new behavior
t = np.array([1.0, np.nan, 3.0])
p = np.array([1.0, 99.0, 3.0])
m = np.array([1, 1, 1])
assert calc_mae(p, t, m) == 0.0  # NaN position auto-excluded

# NaN targets without masks — clear error
try:
    calc_mae(p, t)  # ValueError: targets contains NaN but no masks
except ValueError:
    pass  # ✓

# Works with PyTorch too
calc_mae(torch.tensor(p), torch.tensor(t), torch.tensor(m, dtype=torch.float))  # ✓

Fixes #708

[WenjieDu]

Hi @haoyu-haoyu, please add unit testing cases for your updates. Thanks :)

[haoyu-haoyu]

Hi @WenjieDu, thanks for the feedback! Unit tests added in tests/nn/error_metrics.py:

9 test cases covering all scenarios:

1. Backward compatibility — NaN-free inputs produce same results
2. NaN-free inputs with masks — same results
3. NaN targets + masks (numpy) — auto-exclude NaN positions
4. NaN targets + masks (torch) — same behavior
5. NaN targets without masks — raises ValueError
6. All-NaN targets — metric returns ~0
7. MSE/RMSE/MRE — no NaN propagation
8. Predictions with NaN — still rejected
9. Masks already exclude NaN — same result as auto-exclude

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coveralls]

Pull Request Test Coverage Report for Build 23260746779

Details

• 15 of 15 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.03%) to 79.948%

---

Totals
Change from base Build 23238548275:	0.03%
Covered Lines:	15187
Relevant Lines:	18996

---

💛 - Coveralls

[github-actions]

This pull request had no activity for 14 days. It will be closed in 1 week unless there is some new activity.

[haoyu-haoyu]

@WenjieDu Friendly ping — unit tests were added per your feedback (9 test cases, 100% coverage on new code, CI green, SonarCloud passed). Would you have a chance to take another look? Happy to address any further feedback. Thanks!

[haoyu-haoyu]

Note: the CI failure on Python 3.11 + PyTorch 2.3.0 is a pre-existing environment issue unrelated to this PR:

Disabling PyTorch because PyTorch >= 2.4 is required but found 2.3.0
ImportError: cannot import name 'GenerationMixin' from 'transformers.generation'

The transformers library requires PyTorch >= 2.4, but the CI matrix pins PyTorch 2.3.0. The Python 3.9 + PyTorch 2.3.0 job passes with a compatible transformers version. This PR's changes (in pypots/nn/functional/) are not involved in the import chain that fails.

[github-actions]

This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 10 days.

[github-actions]

This PR was closed because it has been stalled for 10 days with no activity.