feder 0.2.2__tar.gz

feder-0.2.2/.gitignore

@@ -0,0 +1,132 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+/.dir-locals.el
+/config*.toml

feder-0.2.2/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: feder
+Version: 0.2.2
+Summary: Feder client API
+Author-email: Ian Ross <iross@mit.edu>
+Requires-Python: >=3.12

feder-0.2.2/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "feder"
+version = "0.2.2"
+description = "Feder client API"
+readme = "README.md"
+authors = [
+    { name = "Ian Ross", email = "iross@mit.edu" }
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/feder"]

feder-0.2.2/src/feder/__init__.py

@@ -0,0 +1,124 @@
+"""# Feder flight data collection system
+
+Feder is a system for collecting flight data from a range of sources into a
+consolidated database for applications that need easy access to historical
+flight data for statistical or flight attribution purposes. It comes in two
+main parts:
+
+1. An API (published as a Python package) for querying the collected data.
+   This data is stored in SQLite3 database files, and the API provides a
+   simple interface for making efficient queries to these database files.
+
+2. A set of server processes that collaborate to collect and integrate data
+   from different flight data sources, plus infrastructure to deploy these
+   server processes so that they work correctly together.
+
+**The name**: *Feder* is the German word for "feather" and is also supposed to
+give the feeling of **F**light **D**ata **R**ecorder. It's short and unique
+and easy to say ("fay-der", more or less).
+
+## Concepts: positions vs. trajectories
+
+Flight data is usually provided by data sources like FlightAware's Firehose or
+the OpenSky network as individual flight *state vectors*, encoding a single
+snapshot in time of a flight's position. These state vectors are not *exactly*
+individual ADS-B position fixes, because most data provides filter the raw
+ADS-B fixes to reduce data volumes, but they do represent individual position
+fixes at a single point in time. For most applications, it is more useful to
+provide access to *flight trajectories*, i.e. all the position fixes for a
+given flight (possibly restricted to a selected temporal or spatial domain).
+
+The Feder API works in terms of these trajectories (or parts of trajectories),
+and the server processes generate trajectory records for full flights by
+collecting position fixes until it appears that a flight is complete and then
+saving a full trajectory record for the flight. As well as being a more natural
+way to think about this data for most applications, this also makes storing and
+querying the flight data much more efficient than a solution that deals only
+with individual position fixes. Applications that need to work with exactly
+those waypoints in a trajectory that lie within a given temporal or spatial
+range may use the waypoint filtering option of the `feder.FlightQuery` class.
+
+## Data units
+
+All data values are reported from Feder exactly as they come from the flight
+data providers. [Experiments have
+shown](https://github.mit.edu/iross/flight-data-project/blob/main/experiments/flight-data-comparison/flight-data-comparison.pdf)
+that the different data providers (at least FlightAware and the Contrails API)
+provide comparable data, in the sense that the data is exactly what is sent by
+the aircraft's ADS-B transponder. (FlightAware does some data cleaning using
+other sources, but they make the result look as though it came from the ADS-B
+transponder, just with any anomalous values being cleaned up.)
+
+For the user of data from Feder, what this means is:
+
+ - Latitude and longitude values are "normal" WGS-84 latitudes and longitudes;
+
+ - The `alt` field of `feder.Point` contains uncorrected [pressure
+   altitude](https://en.wikipedia.org/wiki/Pressure_altitude) in feet
+   (relative to 1013 hPa) as reported in ADS-B messages;
+
+ - The `alt_gnss` field of `feder.Point` contains GNSS height in feet relative
+   to the WGS-84 datum.
+
+
+## API quickstart
+
+There is a detailed tutorial for the API [here](feder/tutorial.html), but to
+get started quickly and check that things are working, you can do this in the
+shell:
+
+``` shell
+pip install --extra-index-url https://www.mit.edu/~iross/pypi feder
+export FEDER_DATA_DIR=/home/mcast/data/feder
+```
+
+and then this in Python:
+
+``` python
+from datetime import datetime, timedelta
+from feder import FlightQuery
+t1 = datetime(2025, 5, 22, 20, 0)
+t2 = t1 + timedelta(minutes=30)
+flights = list(FlightQuery(t1, t2).with_orig('KBOS').run())
+
+```
+
+This will return a Python array of 10
+[`Trajectory`](doc/api-reference.md#Trajectory) objects of flights crossing
+the given latitude/longitude bounding box in the one hour window starting at
+the given time (all times in UTC).
+
+The API efficiently supports a range of query options and data return formats.
+See the [tutorial](feder/tutorial.html) or the API reference documentation
+below for details.
+
+## API documentation
+
+"""
+
+from .query import get_flights, FlightQuery  # noqa
+from .available import available_days, available_times, available_sources  # noqa
+from .common.models import DataSource, Point, Trajectory  # noqa
+from .common.db import BoundingBox, TemporalQueryType, SpatialQueryType  # noqa
+from .common.version import get_feder_version  # noqa
+
+# The following is needed just to build the documentation.
+import feder.tutorial  # noqa
+
+__all__ = [
+    'get_flights',
+    'FlightQuery',
+    'available_days',
+    'available_times',
+    'available_sources',
+    'DataSource',
+    'Point',
+    'Trajectory',
+    'BoundingBox',
+    'TemporalQueryType',
+    'SpatialQueryType',
+    'get_feder_version',
+    'tutorial'
+]
+
+__version__ = '0.2.2'

feder-0.2.2/src/feder/available.py

@@ -0,0 +1,87 @@
+from datetime import date, datetime, timezone
+import glob
+import itertools
+from operator import itemgetter
+import os
+
+from feder.common import DB, DataSource
+
+
+def available_days() -> list[tuple[date, date]]:
+    """Get a list of available days in the data directory."""
+    data_dir = os.environ.get('FEDER_DATA_DIR')
+    if data_dir is None:
+        raise ValueError('environment variable FEDER_DATA_DIR must be set')
+
+    days = sorted([
+        datetime.strptime(os.path.basename(p)[:8], '%Y-%j').date().toordinal()
+        for p in glob.iglob(os.path.join(data_dir, '????/*.sqlite'))
+    ])
+    ranges = []
+    for _, g in itertools.groupby(enumerate(days), lambda x: x[0] - x[1]):
+        g = list(g)
+        ranges.append((date.fromordinal(g[0][1]), date.fromordinal(g[-1][1])))
+    return ranges
+
+
+def available_sources(day: date) -> set[DataSource]:
+    """Return data sources in use on a given day."""
+    data_dir = os.environ.get('FEDER_DATA_DIR')
+    if data_dir is None:
+        raise ValueError('environment variable FEDER_DATA_DIR must be set')
+
+    # Get all data sources from the database.
+    return DB(data_dir, day).data_sources()
+
+
+def available_times(day: date) -> list[tuple[datetime, datetime]]:
+    """Get a list of available times for a given day."""
+    data_dir = os.environ.get('FEDER_DATA_DIR')
+    if data_dir is None:
+        raise ValueError('environment variable FEDER_DATA_DIR must be set')
+
+    # Get all min, max timestamps pairs from the database.
+    try:
+        timestamp_ranges = DB(data_dir, day).timestamp_ranges()
+    except FileNotFoundError:
+        return []
+
+    # Union the timestamp ranges.
+    minval = int(datetime.combine(day, datetime.min.time(), tzinfo=timezone.utc).timestamp())
+    maxval = int(datetime.combine(day, datetime.max.time(), tzinfo=timezone.utc).timestamp())
+    merged = union_of_ranges([clamp_range(r, minval, maxval) for r in timestamp_ranges])
+
+    # Convert to datetime values and clip to the given day.
+    return [
+        (datetime.fromtimestamp(r[0], tz=timezone.utc),
+         datetime.fromtimestamp(r[1], tz=timezone.utc))
+        for r in merged
+    ]
+
+
+def clamp_range(r: tuple[int, int], minval: int, maxval: int) -> tuple[int, int]:
+    """Clamp a range to the given min and max values."""
+    return (min(maxval, max(minval, r[0])), min(maxval, max(minval, r[1])))
+
+
+def union_of_ranges(inp: list[tuple[int, int]]) -> list[tuple[int, int]]:
+    """Union a list of timestamp ranges."""
+    if len(inp) == 0:
+        return []
+
+    # Sort ranges by start timestamp.
+    inp.sort(key=itemgetter(0))
+
+    # Merge overlapping or contiguous ranges.
+    merged = []
+    current_start, current_end = inp[0]
+
+    for start, end in inp[1:]:
+        if start <= current_end:  # Overlapping or contiguous
+            current_end = max(current_end, end)
+        else:
+            merged.append((current_start, current_end))
+            current_start, current_end = start, end
+
+    merged.append((current_start, current_end))
+    return merged

feder-0.2.2/src/feder/common/__init__.py

@@ -0,0 +1,13 @@
+"""Code shared between the Feder public API and backend.
+
+The parts of this module relevant to the public API are:
+
+ - `feder_common.models`: Model classes for trajectories and trajectory points.
+ - `feder_common.db`: Database access code.
+"""
+from .models import *  # noqa
+from .db import *  # noqa
+from .utils import *  # noqa
+from .version import *  # noqa
+
+__version__ = '0.2.2'