Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarity of reference times in documentation #20

Open
bwmeyers opened this issue Mar 22, 2021 · 2 comments
Open

Clarity of reference times in documentation #20

bwmeyers opened this issue Mar 22, 2021 · 2 comments
Labels
documentation Improvements or additions to documentation question Further information is requested

Comments

@bwmeyers
Copy link
Contributor

One thing I noted in the recent PR #19 was there's some ambiguity in the metadata requested and how it's used.

Specifically, the arrival times are to be given in seconds, but seconds since what reference epoch? Is that what the times_bin0 is used for? What time format is times_bin0 assumed to be in? Is the arrival_time relative to times_bin0 or some other reference epoch? Internally we know it's relative to times_bin0 since we create a times array from 0 to num_times * res_time seconds, but best to broadcast that.

e.g., "a floating-point scalar indicating the value of time bin at index 0, in seconds" is ambiguous - we should be very explicit: is it Unix time, MJD, JD, etc.?

@bwmeyers bwmeyers added documentation Improvements or additions to documentation question Further information is requested labels Mar 22, 2021
@emmanuelfonseca
Copy link
Collaborator

emmanuelfonseca commented Mar 22, 2021

this is a very good point @bwmeyers, one i somewhat realized recently but the ambiguity wasn't bugging me just yet. nonetheless, i agree we should settle this now.

i think one way to do this is that we require the values of time_bin0 and arrival_time to be in MJD; we then load these values in astropy.time.TIme() objects so that we can obtain datetime representations and then take the difference, which gives a datetime.timedelta() object. finally, we can use the datetime.timedelta().total_seconds() method to obtain the total number of seconds relative to the reference time (time_bin0). this allows use to use both variables and still ensure that the units under the hood are in seconds. the following is an example in rough code:

from astropy.time import Time

# initialize timestamps.
time_bin0 = 59295.64141165053
t0 = Time(time_bin0, format="mjd")
t1 = TIme(time_bin0 + 9.259259259259259e-07, format="mjd") # 80 s after time_bin0

# now compute difference.
dt = t1.datetime - t0.datetime
arrival_time = dt.total_seconds()

does this make sense?

@bwmeyers
Copy link
Contributor Author

Having time_bin0 be in MJD makes a lot of sense. I guess it then follows that arrival_time should also be an MJD. Although if the data is dispersed still, then that arrival time would necessarily be the arrival time at the reference frequency.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation question Further information is requested
Projects
None yet
Development

No branches or pull requests

2 participants