allow for optional dispersion-smearing removal during fits

[emmanuelfonseca]

the current fitburst does not account for dispersion smearing, and should/will adapt the algorithm used by CHIME/FRB (upsample + disperse + downsample).

[bwmeyers]

As a related note, fitburst should be able to know whether the data it has been given is dedispersed to some nominal DM or not, as that will of course change the initial step (i.e., dedisperse to provided guess before trying to iterate with fitting).

[emmanuelfonseca]

@zpleunis @bwmeyers my idea is to have the accounting of dispersion smearing be an optional operation indicated by the user before fitting. for example, there's a small amount of configuration of the fitburst.analysis.model.SpectrumModeler before it's loaded in the fitter class. we could add a boolean switch, something like the following:

from fitburst.analysis.model import SpectrumModeler

# set up model class.
model = SpectrumModeler()
model.compute_dispersion_smearing(True)

# now compute model
# ...

we can have the default be True and set it to False if the supplied data are coherently dedispersed. whatever we set, this boolean would dictate whether dispersion smearing is accounted for (True) or not (False) for all instances of model.compute_model(). what do you think?

[zpleunis]

I think that simplifies it too much, even though it would be fine in most cases. In practice you sometimes take data that gets coherently dedispersed to some fiducial value close to, but not quite, the actual DM of the burst and you would still want to take into account the dispersion smearing from the few DM units that your fiducial value was off from the actual value. To generalize the suite I think we should add a parameter coherent_dm which is 0.0 by default. We then calculate smearing for dm - coherent_dm. Is smearing from -DM the same as smearing from +DM?

[emmanuelfonseca]

on second though i believe you are right and my original idea is too simplistic.

as you said, there are a couple of cases we'll want to code up carefully. here are the three main cases i can think of, treated as if/else conditions:

def _remove_dispersion_smearing(self, dm_coherent: float = None):

    if self.is_dedispersed and dm_coherent is not None:
        # in this case, the input spectrum is dedispersed and the DM loaded into the SpectrumModeler is the DM offset
        # so just use this offset to compute the residual DM smearing

        dm = self.dm[0]

    elif dm_coherent is not None:
        # in this case, the input spectrum is dispersed but was coherently dedispersed in preprocessing 
        # to remove DM smearing. however, the DM value loaded in SpectrumModeler is the full DM, so 
        # compute the offset and use this to account for residual DM smearing.

        dm =  self.dm[0] - dm_coherent
        # remaining code goes here

    else:
        # in this final case, the data is either dedispersed or not, but either way were not coherently 
        # dedispersed to remove DM smearing in the channels. in this case, use the full DM.

        dm = self.dm[0]

within each block, we'd use the same algorithm to compute and smeared pulse, but with different inputs of the DM.

[emmanuelfonseca]

this was addressed in PR #57.