raphaelvallat/yasa

hypnogram simulation updates for new Hypnogram class

remrama opened this issue · 1 comments

I'd like to implement some quick updates to yasa.hypno.simulate_hypno that accommodate the new Hypnogram class (see #105). I'd wait until #116 is merged, just noting now for discussion.

  1. Return a yasa.Hypnogram instance instead of an integer array.
  2. Fix annoying issue when using the trans_probas argument. Because of reindexing to get all stages in order, if a stage was allowed but not included in trans_probas, the reindexing makes a row of zeros and this fails the assertion check that all rows sum to 1.
  3. Change reindexing to strings (because more easily accessible in yasa.Hypnogram, now YASA leans slightly more towards string hypno reps).
  4. Add option to sprinkle in some randomly-placed Art/Uns in simulated hypnograms, specifically for testing other functions (because I often forget about having to handle these!).
  5. Add yasa.Hypnogram.simulate_similar() method. See below.

The only slightly controversial thing I'm suggesting is the last idea. Here's how I think it would look:

class Hypnogram:
    ...
    def simulate_similar(self, jitter_tib=False):
        """Return a simulated hypnogram based on properties of the current hypnogram."""
        tib = hypno.sleep_statistics()["TIB"]
        if jitter_tib:
            tib += np.random.randint(-10, 10)
        sim_values = yasa.simulate_hypno(
            tib=tib,
            sf=hypno.sampling_frequency,
            n_stages=hypno.n_stages,
            trans_probas=self.transition_matrix()[1],
        )
        sim_hypno = yasa.Hypnogram(
            values=sim_values,
            n_stages=hypno.n_stages,
            freq=hypno.freq,
            start=hypno.start,
            scorer=hypno.scorer,
        )
        return sim_hypno

All sounds great! For 5, instead of jitter_tib, why not directly specify tib=? if "None", then the tib is the same as the current hypnogram.

We should also add TIB/total duration of the hypnogram as a property of the class.