Add option to choose 'or' mode in TimeSeries.gaps()

[hrzn]

Right now for multivariate TS, gaps are only considered if all components are nan, but it should be possible to treat periods where any value is nan as gap too.

to be discussed with @pennfranc

[ghost]

The code bolow adds the option to TimeSeries.gaps() The code will also return an empty DataFrame in case no gaps are found. I did not include the code in a pull request because:

• I did no proper testing and
• Implications on other parts of the library are not investigated. In particular the additional change that the gaps function can return an empty pd.DataFrame (in case no gaps are availabe - issue TimeSeries.gaps() not working if there are no gaps #647) will trow an exception if you use it with darts.utils.missing_values.extract_subseries
  Hope the code can still be of value for somebody...

def gaps(self, mode:str='all') -> pd.DataFrame:
    """
    A function to compute and return gaps in the TimeSeries. Works only on deterministic time series (1 sample).
    Parameters
    ----------
    mode
         Only relevant for multivariate time series. The mode defines how gaps are defnind. Set to 
         'any' in if periods where any value is Nan should be considere as as gaps. 'all' will only 
         consider periods where all values are NaN. Defaults to 'all'. 
    Returns
    -------/
    pd.DataFrame
        A pandas.DataFrame containing a row for every gap (rows with all-NaN values in underlying DataFrame)
        in this time series. The DataFrame contains three columns that include the start and end time stamps
        of the gap and the integer length of the gap (in `self.freq` units if the series is indexed
        by a DatetimeIndex).
    """

    df = self.pd_dataframe()

    if mode == 'all':
        is_nan_series = df.isna().all(axis=1).astype(int)
    elif mode == 'any':
        is_nan_series = df.isna().any(axis=1).astype(int)
    else:
        raise_log(ValueError(f"Keyword mode accepts only 'any' or 'all'. Provided {mode}"), logger)
    diff = pd.Series(np.diff(is_nan_series.values), index=is_nan_series.index[:-1])
    gap_starts = diff[diff == 1].index + self._freq
    gap_ends = diff[diff == -1].index

    if is_nan_series.iloc[0] == 1:
        gap_starts = gap_starts.insert(0, self.start_time())
    if is_nan_series.iloc[-1] == 1:
        gap_ends = gap_ends.insert(len(gap_ends), self.end_time())

    gap_df = pd.DataFrame(columns=['gap_start', 'gap_end'])

    if gap_starts.size == 0:
        return gap_df
    else:
        def intvl(start, end):
            if self._has_datetime_index:
                return pd.date_range(start=start, end=end, freq=self._freq).size
            else:
                return start - end
        
        gap_df['gap_start'] = gap_starts
        gap_df['gap_end'] = gap_ends
        gap_df['gap_size'] = gap_df.apply(
            lambda row: intvl(start=row.gap_start, end=row.gap_end), axis=1
        )

        return gap_df

[hrzn]

Thank you @phubermi and sorry for the late reaction. I think your message somehow slipped through..
Would you be willing to turn this into a PR?

[mukkla]

@madtoinou: Thank's a lot for taking care of it!