with weights = 'equal', mne.combine_evoked computes sum, not mean

Following up on a strange variation in the scale of my evokeds, I realized that mne.combine_evoked computes the sum, rather than the mean when weights = ‘equal’ (mne version: ‘0.21.dev0’):

evoked.py, line 876:

naves = np.array([evk.nave for evk in all_evoked], float)
  if isinstance(weights, str):
      _check_option('weights', weights, ['nave', 'equal'])
      if weights == 'nave':
          weights = naves / naves.sum()
      else:
          weights = np.ones_like(naves)
  else:
      weights = np.array(weights, float)

Shouldn’t it be weights = np.ones_like(naves) / len(all_evoked) instead of weights = np.ones_like(naves) ?

The documentation says

The weights to apply to the data of each evoked instance. Can also be ‘nave’ to weight according to evoked.nave, or “equal” to use equal weighting (each weighted as 1/N).

[drammock]

it seems to me like the definitive question here is “what is a more common use case: equally-weighted sum, or equally-weighted average?” Both are possible, it’s a question of which we want to make easy for users with a string argument to weights. It is my impression that equally-weighted average is more common, and is also slightly more difficult for users to implement themselves:

equal_weighted_sum = combine_evokeds(evks, weights=np.ones(len(evks)))
equal_weighted_avg = combine_evokeds(evks, weights=np.ones(len(evks)) / len(evks))

Therefore I’m preparing a PR to make the code align with the docstring for weights='equal' and also to change the docstring’s recommendation about how to do a subtraction, since it will no longer be correct to use weights='equal' for subtraction after that change.

[drammock]

There is definitely something wrong here. If I recall correctly the discussion among myself, @jasmainak, @jona-sassenhagen, and @agramfort, it was decided that weights='equal' should work the way it does in order for subtractions of evokeds to work sensibly. I think between that concern and trying hard to get the nave computation correct, we lost sight of the common use case where users want 1/N weighting. For a quick work-around you could pass an array of 1/N values as weights, but then nave will be wrong. I think it’s time to re-think this implementation so that the most common use cases are correct, obvious, and hard to mess up.