A function for computing the minimum distance between two dihedral angles

[xiki-tempula]

Is your feature request related to a problem? Please describe.
It is quite common that one might want to know the absolute difference between two dihedral angles or between two dihedral angle n-dimensional arrays, so it would be nice if such a function exists in scipy.stats similar to scipy.stats.circmean or scipy.stats.circvar.

Describe the solution you'd like

def circdelta(sample1, sample2, high=2*pi, low=0, nan_policy='propagate'):
    """
    Compute the circular difference between sample1 and sample2 in a range.
    Parameters
    ----------
    samples1 : array_like
        Input array 1.
    samples2 : array_like
        Input array 2.
    high : float or int, optional
        High boundary for circular delta range.  Default is ``2*pi``.
    low : float or int, optional
        Low boundary for circular delta range.  Default is 0.
    nan_policy : {'propagate', 'raise', 'omit'}, optional
        Defines how to handle when input contains nan. 'propagate' returns nan,
        'raise' throws an error, 'omit' performs the calculations ignoring nan
        values. Default is 'propagate'.
    Returns
    -------
    circdelta : array_like
        Circular delta.
    Examples
    --------
    >>> circdelta(0.1, 5)
    1.38
    >>> circdelta([0.1, 2], [5, 3])
    [1.38, 1]
    """

[tupui]

Hi! Are you proposing to implement this feature yourself?

[xiki-tempula]

Hi @tupui,
I was wondering if such a function exist?
I think It would be nice if scipy could implement this function.

[tupui]

I don't think it exists no. You could try to ask on the mail list or if you're confident this is actually wanted propose a PR.

astropy seem to have more options: https://docs.astropy.org/en/stable/stats/circ.html

[V0lantis]

I am not very aware of the subject. Could you share some papers / formula which explains how to compute this difference?

[xiki-tempula]

@V0lantis It is just the minimum image convention.
A naive implementation would be:

def circdelta(sample1, sample2, high=2*pi, low=0, nan_policy='propagate'):
    period = high - low
    sample1_treated = sample1 % period
    sample2_treated = sample2 % period
    return min(abs(sample1_treated-sample2_treated), abs(sample1_treated-sample2_treated+period), abs(sample1_treated-sample2_treated-period))

[V0lantis]

Ok thank you, I found a lot of interesting articles :-).
Is this one a relevant one ?

[xiki-tempula]

@V0lantis Yes, it looks like a reasonable one to me. Thank you.

[mdhaber]

I'm not sure that scipy.stats is the most appropriate place for this as described, as it seems like elementwise subtraction on a circular domain. (If there were, for instance, a paired-sample hypothesis test to be performed, I would see the connection.) If you're interested in seeing this added, please send an email to the mailing list explaining why this is fundamental, useful across multiple domains, and important to add despite the simple implementation in terms of existing functions. I'd suggest including well-cited references as support, and please open the discussion about where it would belong.