{
    "info": {
        "author": "Samuel Blake",
        "author_email": "samuelfblake@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
            "Programming Language :: Python :: 3.7"
        ],
        "description": "# pyvlog\n\n## Overview\n\n**pyvlog** is a Python package for working with traffic device data from smart intersections that adhere to the [V-Log messaging protocol](http://www.v-log.nl/). It can be used to convert sequences of device messages into time-stamped statuses for any combination of traffic devices at a smart intersection.\n\nIt converts individual device messages like this:\n```\n012018091115000000\n05000003000\n0D00000200\n090000020070A0\n0E00310102\n0600610201\n```\ninto intersection statuses like this:\n```\n{'timestamp': 1536670800.6,\n 'tijdReferentie': 1536670800.0,\n 'detectie': {0: {'OG-BG-FL': 0, 'storing': 0, 'bezet': 0},\n  1: {'OG-BG-FL': 0, 'storing': 0, 'bezet': 0},\n  2: {'OG-BG-FL': 0, 'storing': 0, 'bezet': 1}},\n 'externeSignaalgroep': {0: 0, 1: 2},\n 'deltaTijd': 0.6}\n```\n\nNaming and data conventions for the various traffic devices follow the specification provided by [Vialis](https://www.ivera.nl/wp-content/uploads/2018/04/V-Log_protocol_en_definities_v3.01_WG_techniek_changes_highlighted.pdf).\n\n## Installation\n\npyvlog can be installed via pip:\n\n```\npip install pyvlog\n```\n\n## Documentation\n\nDocumentation is available at [readthedocs](https://pyvlog.readthedocs.io/).\n\n## How to use pyvlog\n\npyvlog is designed for converting sequences of v-log messages - streamed from smart intersection traffic devices - into time-stamped statuses of all traffic devices at an intersection. These statuses can be queried by both time and device, aiding the development of functionality built around v-log data.\n\npyvlog is able to perform this conversion in two ways.\n\n_parsers_ are objects which receive messages individually and use each message to update the stored intersection status. Additionally they can identify when a status is \"complete\" (all values are known for a specific timestamp) and can log these completed statuses. They are suited to converting realtime streams of v-log messages.\n\n_converters_ are functions which take a sequence of v-log messages and return a sequence of statuses. They are suited to (batch) converting data dumps of historic v-log messages.\n\n### Parse sequences of v-log data\n\nThe parsing of individual v-log messages is always done by the `VLogParser` class. At its simplest, you can create a `VLogParser()` object and call its `.parse_message()` method one message at a time on a sequence of messages. The object stores the intersection status as a dictionary in the attribute `.status`. This is the intersection status after the last message was received.\n\n```python\nfrom pyvlog.parsers import VLogParser\n\nvlogger = VLogParser()\n\nmessages = ['012018091115000000', '05000003000', '0D00000200', '090000020070A0', '0E00310102', '0600610201']\nfor m in messages:\n    vlogger.parse_message(m)\n\nprint(vlogger.status)\n```\n\nWhen converting a sequence of v-log messages you may well want to know the status of the intersection for all timestamps spanned by the sequence of messages, not just the final status. The `VLogParser` class identifies when a status is complete (there is not a one-to-one correspondence between messages and statuses) and logs this status by calling the method `.log_status()`.\n\nThe base `VLogParser` class does not store these logged statuses anywhere, however two child classes are provided, `VLogParserToList` and `VLogParserToJson`, which log the statuses to a list and a JSON file respectively.\n\n```python\nfrom pyvlog.parsers import VLogParserToList\n\nstatus_list = []\nvlogger = VLogParserToList(status_list)\n\nmessages = ['012018091115000000', '05000003000', '0D00000200', '090000020070A0', '0E00310102', '0600610201']\nfor m in messages:\n    vlogger.parse_message(m)\n\nprint(status_list)\n```\n\nInstructions on writing your own parser classes are provided below.\n\n### Convert v-log files to historic statuses\n\nA number of converter functions are provided for converting complete sets of v-log messages into their corresponding time-stamped statuses. These convert from a file or list of v-log messages to a JSON file, list or pandas dataframe of historic statuses (e.g. `file_to_file` or `list_to_dataframe`). Status data is written in JSON format, using UltraJSON.\n\n```python\nfrom pyvlog.converters import file_to_json\n\nvlog_file = \"test.vlg\"\nout_file = \"test.json\"\nfile_to_json(vlog_file, out_file)\n```\n\nFor conversion to pandas dataframes the status dictionary is flattened (with \"\\_\" joining the keys) and timing fields are converted to datetime / timedelta.\n\n```python\nfrom pyvlog.converters import list_to_dataframe\n\nmessages = ['012018091115000000', '05000003000', '0D00000200', '090000020070A0', '0E00310102', '0600610201']\ndf = list_to_dataframe(messages)\n\nprint(df.head())\n```\n\n### Write custom v-log parsers for your projects\n\nCustom parser classes can be created for any number of different logging routines, simply by inheriting the base `VLogParser` class and defining a new `.log_status()` method, plus any additional arguments. The two additional classes defined in the `parsers` module, `VLogParserToList` and `VLogParserToJson`, illustrate how such a custom parsing class may be created.\n\n### Traffic device coverage\n\nThis package is developed for the processing of realtime v-log messages from a small number of smart intersections. As such not all types of v-log messages were available during its development. The message types currently parsed are given by the keys of `messagetypes.MESSAGE_TYPE_DICT` and are repeated below (with the v-log message prefix given in brackets).\n\n#### Message types parsed:\n- _tijdReferentie_ (1)\n- _vlogInformatie_ (4)\n- _detectie_ (5,6)\n- _overigeIngangen_ (7,8)\n- _interneFaseCyclus_ (9,10)\n- _overigeUitgangenGUS_ (11,12)\n- _externeSignaalgroep_ (13,14)\n- _overigeUitgangenWUS_ (15,16)\n- _gewensteProgrammaStatus_ (17,18)\n- _werkelijkeProgrammaStatus_ (19,20)\n- _thermometer_ (23,24)\n- _instructieVariabelen_ (32)\n- _OVHulpdienstInformatie_ (34)\n\nBy default only _detectie_ and _externeSignaalgroep_ are parsed (plus _tijdReferentie_, which is always parsed in order to calculate the timestamp). Both the parser classes and converter functions take an argument `logged_types`, which specifies which message types to log.\n\n```python\nfrom pyvlog.parsers import VLogParser\n\nvlogger = VLogParser(logged_types=[\"detectie\", \"externeSignaalgroep\", \"interneFaseCyclus\"])\n\nmessages = ['012018091115000000', '05000003000', '0D00000200', '090000020070A0', '0E00310102', '0600610201']\nfor m in messages:\n    vlogger.parse_message(m)\n\nprint(vlogger.status)\n```\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/HAL24K/pyvlog",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "pyvlog",
        "package_url": "https://pypi.org/project/pyvlog/",
        "platform": "",
        "project_url": "https://pypi.org/project/pyvlog/",
        "project_urls": {
            "Homepage": "https://github.com/HAL24K/pyvlog"
        },
        "release_url": "https://pypi.org/project/pyvlog/0.1/",
        "requires_dist": [
            "ujson (>=1.35)",
            "pandas (>=0.25.1)"
        ],
        "requires_python": "",
        "summary": "Python package for working with the V-Log traffic control data protocol",
        "version": "0.1"
    },
    "last_serial": 5788626,
    "releases": {
        "0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "73528ca2da583a89fe66abe7eb270b83",
                    "sha256": "1d30785163ed94e75d40059be32aa230c7deede6f0976173a4040e56caf6e813"
                },
                "downloads": -1,
                "filename": "pyvlog-0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "73528ca2da583a89fe66abe7eb270b83",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 23684,
                "upload_time": "2019-09-05T21:56:11",
                "url": "https://files.pythonhosted.org/packages/00/9f/b54574b0c00a676f27a837513cd5c347dfd1285619504aff6e85ce82e7c0/pyvlog-0.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "2b7a282f8480bd795eca9380d311b1a3",
                    "sha256": "fc8acd5bad06232f6af99bbd2d684186f2041205e8694392e5aed35883fa2b03"
                },
                "downloads": -1,
                "filename": "pyvlog-0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "2b7a282f8480bd795eca9380d311b1a3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10630,
                "upload_time": "2019-09-05T21:56:14",
                "url": "https://files.pythonhosted.org/packages/6f/bb/beb0715dcf410d1a698d0b4fbac3f71dd093f7139bed900c522871259097/pyvlog-0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "73528ca2da583a89fe66abe7eb270b83",
                "sha256": "1d30785163ed94e75d40059be32aa230c7deede6f0976173a4040e56caf6e813"
            },
            "downloads": -1,
            "filename": "pyvlog-0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "73528ca2da583a89fe66abe7eb270b83",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 23684,
            "upload_time": "2019-09-05T21:56:11",
            "url": "https://files.pythonhosted.org/packages/00/9f/b54574b0c00a676f27a837513cd5c347dfd1285619504aff6e85ce82e7c0/pyvlog-0.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "2b7a282f8480bd795eca9380d311b1a3",
                "sha256": "fc8acd5bad06232f6af99bbd2d684186f2041205e8694392e5aed35883fa2b03"
            },
            "downloads": -1,
            "filename": "pyvlog-0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "2b7a282f8480bd795eca9380d311b1a3",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 10630,
            "upload_time": "2019-09-05T21:56:14",
            "url": "https://files.pythonhosted.org/packages/6f/bb/beb0715dcf410d1a698d0b4fbac3f71dd093f7139bed900c522871259097/pyvlog-0.1.tar.gz"
        }
    ]
}