Misc. clarification in the documentation & other improvements

[raph-p]

Hi @xoolive,

Thank you so much for the hard work building this library. I've been using it extensively for 2 weeks and I have several feedback to provide, alongside the improvements you already listed. I can take the lead in some of them but I honestly don't know when I will be able to do something.

• Clarify the documentation for the Flight and Traffic APIs, what columns are expected, for what features/methods, and their respective units. I get that OpenAP expects some unit (e.g. to compute the phases(), it requires an altitude and the vertical rate), though if find their documentation not really clear
• Implement other engine performance models (psmodel, bada), I find OpenAP a bit glitchy when extracting the phases, for instance.
• Implement a proper semantic versioning strategy (i.e. in the CI/CD), especially when releasing a breaking change to the public API (see latest release v2.12, which should have been a major bump, v3.0 IMHO)

Nice to have:

• Implement retry strategies when fetching data from the internet (weather/METAR, airports, etc.)
• Facilitate conversion from/to pycontrails Flights objects.
• A bit advanced: I'd like to have a proper way to reconstruct flight tracks on ground, when ADS-B coverage is bad. I tried the KalmanFilter but it only works for taxiways, and

---

Please follow these steps to make it more efficient to respond to your feature request.

• [ ✅ ] Search for duplicate issues.
• [ ✅ ] Refer the latest version of traffic, ideally the HEAD of the github.
• [ ✅ ] Are you willing to give it a try with some guidance and submit a pull request later?

[xoolive]

Thank you for the feedback @raph-p

I will try to reply to all items, there are a lot of comments in your message:

• dataframes behind Flight and Traffic structures can have pretty much any column. icao24 and timestamp must be the only really minimal phases. In order to run some methods, more columns may be expected, so it is hard to reply here. Nautical units are expected as per the ADS-B standard definitions: altitudes in ft, speeds in kts, vertical rate in ft/min (and angles in degrees)
• If you have a better implementation for flight phases, you can wrap it in a class, with a method apply(self, flight: Flight) -> Flight, then you pass an instance of this class as a parameter of the flight.phases() method. If it's really good, we can add it to phases.py file next to the OpenAP implementation.
• Same with performance models, flight.fuelflow() accepts any instance with a estimate(self, flight: Flight) -> Flight method. If you implement something with pyBADA for instance, that's the way (and of course we can consider adding your class in the end)
• Surface trajectories: there's a KalmanTaxiway class somewhere (with the paper explaining it here), and we are working on a better implementation

Most of your comments are valid, but I am also running after time with other aspects of my work/life. I add things when I need them for my work, and in general, I am happy to include any code that fixes existing code or that has a “good enough” level of maturity.