Better exception message in get_states for too-early start arg

taldcroft commented 2 years ago

Description

This improves the exception message to provide better feedback to the user in the case when an early start time makes it not possible to establish continuity.

The suggestion in #239 was to make it that the returned states start when available data allow, similar to how cheta functions when fetching telemetry. This is a good idea, but due to the way dynamic command states are built up on the fly from continuity, implementing this would not be straightforward. The effective start time depends on when all of the required commands to define a particular state or states have been issued.

Instead, this just gets the user on the right track more quickly by highlighting the problem and a workaround.

Fixes #239

Interface impacts

Testing

Unit tests

[x] Mac

Independent check of unit tests by [REVIEWER NAME]

[ ] [PLATFORM]:

Functional tests

In [1]: from kadi.commands import states

In [2]: states.get_states('2002:001', '2003:001', state_keys = ['orbit_point'])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
~/git/kadi/kadi/commands/states.py in get_states(start, stop, state_keys, cmds, continuity, reduce, merge_identical, scenario)
   1331         try:
-> 1332             continuity = get_continuity(start, state_keys, scenario=scenario)
   1333         except ValueError as exc:

~/git/kadi/kadi/commands/states.py in get_continuity(date, state_keys, lookbacks, scenario)
   1608         if missing_keys:
-> 1609             raise ValueError('did not find transitions for state key(s)'
   1610                              ' {} within {} days of {}.  Maybe adjust the `lookbacks` argument?'

ValueError: did not find transitions for state key(s) {'orbit_point'} within 1000 days of 2002:001:00:00:00.000.  Maybe adjust the `lookbacks` argument?

During handling of the above exception, another exception occurred:

ValueError                                Traceback (most recent call last)
<ipython-input-2-bccec27564a3> in <module>
----> 1 states.get_states('2002:001', '2003:001', state_keys = ['orbit_point'])

~/git/kadi/kadi/commands/states.py in get_states(start, stop, state_keys, cmds, continuity, reduce, merge_identical, scenario)
   1333         except ValueError as exc:
   1334             if 'did not find transitions' in str(exc):
-> 1335                 raise ValueError(
   1336                     f'no continuity found for {start=}. Need to have state '
   1337                     f'transitions following first command at {cmds[0]["date"]} '

ValueError: no continuity found for start='2002:001:00:00:00.000'. Need to have state transitions following first command at 2002:007:13:35:57.743 so use a later start date.

Gregg140 commented 2 years ago

Why not also figure out the earliest time one can search for states and put that in the documentation as well. Right now the documentation says:

Commands and states

Commands

The Commands archive is a table of every load command that has been run, or is currently approved to be run, on the spacecraft since 2002.

Figure out the earliest time where all state items are populated and publish that in the docs, right at the top, in place of "2002".

You can mention that some state items might be populated prior to that time.

I doubt it will change.

And also put it in the error messages.

taldcroft commented 2 years ago

The earliest possible date a user can specify, where all states have been populated, ought to be listed in the documentation.

The problem is that "all states" is not well-defined. Since states are dynamically computed and there are many of them (including more obscure or user-defined ones that are not in the legacy standard list), there is no single answer if you want to push the boundaries.

I could conservatively say that a query starting in 2003:001 will always succeed and declare that as the beginning.

sot / kadi