Package: gpsdio
AIS I/O with Python, dictionaries, and theGPSd AIVDMschema.This project is still evolving but will calm down once it hitsv0.1.  We
would love to hear from you’re using, or would like to use, this project, both
so we don’t make any unexpected changes, and to get outside opinions on AIS
processing.OverviewVessels use a ship-to-ship Automated Identification System (AIS) to avoid
collisions by broadcasting information about who they are, where they are, and
what they are doing.  These messages are broadcast asNMEA 0183orNMEA 2000sentences and are
constantly being collected by terrestrial and satellite receivers.NMEA is very large and difficult to work with natively, so the solution is to
parse it and store as another format.  Rather than spend time developing our
own schema we chose to adopt theGPSd AIVDMschema, which clearly defines all message types.  Messages map well to Python
dictionaries due to how fields vary type-to-type, so that’s whatgpsdiouses.This project aims to make AIS data easier to work with by providing I/O and a
small set of useful transforms, and was built with large-scale data processing
pipelines in mind.Example I/OHere’s a small example of how to read data stored asnewline delimited JSON,
add a field, and write as GZIP compressedMsgPack.
The driver and compression are explicitly given but can also be detected from the file path.
For more information on whatgpsdio.open()returns, see the section onmessages.importgpsdiowithgpsdio.open('sample-data/types.json')assrc:withgpsdio.open('with-num-fields.msg.gz','w',driver='MsgPack',compression='GZIP')asdst:formsginsrc:msg['num_fields']=len(msg)Parsing NMEA Sentencesgpsdiodoes not yet support reading NMEA directly, although it will hopefully
in the near future.  In the meantime,libaishas anaisdecodeutility with an optional--gpsdformat that produces data
readable by this library.Commandline InterfaceThis project also offers agpsdiocommandline utility for common tasks like
inspecting and transforming data.  See theCLI docsfor more information.MessagesNOTE:Message validation and transformation has not quite settled and will
change forv0.1.  The description below is currently mostly relevant, although
some fields may be placed into an__invalid__key on read or write.gpsdio.open()returns a file-like object calledStream()that is
responsible for taking a dictionary from the underlying driver and transforming
it into a well formed message.Normally I/O libraries perform some strict validation while reading and before
writing data, but working with AIS usually involves adding some custom fields.
Rather than tellinggpsdio.open()what additional fields it may encounter
every time a file is opened, message validation only happens when requested.
This may seem backwards, but the idea is that validation really only needs to
happen as data parsed and brought into thegpsdioworld.  After that the
user knows far more about their data and is likely adding additional fields
during processing.Seesample-datafor some datagpsdiocan immediately read and write.CLI PluginsDevelopers can create their owngpsdiocommands withclick-plugins.gpsdioloads plugins from asetuptools entry pointcalledgpsdio.cli_plugins, so in yoursetup.py:setup(entry_points='''
        [gpsdio.cli_plugins]
        name=package.module:click_command
    ''')For a more in-depth description see theclick-pluginsdocumentation.  Additionally, seegpsdio-densityfor an example, or one of the other plugins listed in theplugin registry.Driver PluginsExternal drivers should be registered to the entry-pointgpsdio.driver_pluginsand
must subclassgpsdio.base.BaseDriverorgpsdio.base.BaseCompressionDriver.
See the docstrings on those two objects for subclassing information.InstallationWith pip:$pipinstallgpsdioFrom source:$gitclonehttps://github.com/SkyTruth/gpsdio$cdgpsdio$pythonsetup.pyinstallDeveloping$gitclonehttps://github.com/SkyTruth/gpsdio.git$cdgpsdio$virtualenvvenv$sourcevenv/bin/activate$pipinstall-e.[dev]$py.testtests--covgpsdio--cov-reportterm-missingChangelogSeeCHANGES.mdLicenseSeeLICENSE.txt