offset for ALEX period?

[tritemio]

Current situation

Currently the us-ALEX excitation periods are defined on the histogram of:

timestamps MOD alex_period

Since the acquisition and start of alternation have a delay, this histogram can start at any fraction of the alternation period. To overcome this we define both internal and external ranges for the donor and acceptor alternation (see docs).

Alternative

An alternative is defining an additional offset parameter so that the alex histogram is computed from:

(timestamps - offset) MOD alex_period

The alex hist bins will still go from 0 to alex_period but with a different phase. When offset is defined the alex_period_donor and alex_period_acceptor values depends on the offset (as a side note, these fields will be renamed soon, see #16).

What can we do?

1. Add offset and leave both internal and external ranges so the user can decide which convention to follow to define the periods.
2. Add offset and remove the external ranges. This renders mandatory to always define an offset that makes possible defining the alternation with only internal ranges. On the pro side, the internal ranges are more intuitive and easier to explain than the external ones.
3. Don't add offset.

[tritemio]

Proposed Name 1

alex_offset

Proposed Name 2

alex_period_offset

[smXplorer]

I use an offset to present an histogram of timestamp that goes from offset to offset+period (modulo the period). The user still needs to define the start and stop of both excitation periods based on that histogram, but in general, once the offset is chosen for a setup, it never changes (the period boundaries might, depending on alignment, power, etc). This being said, the offset is not just a convenience for representation. It also defines where the user thinks the alternation period starts. It is probably defined at best with a few us resolution, but it has a physical meaning, therefore I think it is somehow a mandatory parameter. Therefore, it would seem that this parameter is mandatory. I have no objections with introducing a internal/external variant, but I don't see the need once we agree that the offset is a necessary information to specify the setup (even though, again, there is no simple way to define it exactly).

[tritemio]

The same information is provided by (a) ranges (internal + external) and no offset, or (b) ranges (internal only) + offset.

I agree it is cleaner to add the offset and make it "mandatatory" when the excitation ranges are specified (which is optional). I'm leaning toward removing the external range possibility in the file format.

@smXplorer, If I understand correctly, what you do is computing the histogram of:

(timestamps - offset) MOD alex_period

with bins [0..alex_period] and then shifting the bins by offset before plotting. If my interpretation is correct we are using the same definition here.

[smXplorer]

1) no. offset is an additional information which is needed to define when the global alternation period starts. There is no reason why this would be identical to any of the other boundaries. 2) correct.