{"id":32200486,"url":"https://github.com/markegge/fhwa_pm3","last_synced_at":"2025-10-22T03:49:11.370Z","repository":{"id":37488848,"uuid":"366108267","full_name":"markegge/fhwa_pm3","owner":"markegge","description":"Functions for calculating FHWA System Reliability, Freight and CMAQ Congestion performance measures using NPMRDS Probe Data.","archived":false,"fork":false,"pushed_at":"2024-06-12T23:22:11.000Z","size":11768,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-22T03:49:03.027Z","etag":null,"topics":["hpms","pm3","tmc"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markegge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-10T16:31:57.000Z","updated_at":"2025-04-08T19:46:36.000Z","dependencies_parsed_at":"2024-06-13T04:53:24.867Z","dependency_job_id":null,"html_url":"https://github.com/markegge/fhwa_pm3","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/markegge/fhwa_pm3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markegge%2Ffhwa_pm3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markegge%2Ffhwa_pm3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markegge%2Ffhwa_pm3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markegge%2Ffhwa_pm3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markegge","download_url":"https://codeload.github.com/markegge/fhwa_pm3/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markegge%2Ffhwa_pm3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280376536,"owners_count":26320276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hpms","pm3","tmc"],"created_at":"2025-10-22T03:49:10.443Z","updated_at":"2025-10-22T03:49:11.364Z","avatar_url":"https://github.com/markegge.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Federal Transportation Performance Management Data Processing Tools\n\n### This package provides NPMRDS Processing Tools for Assessing System Performance, Freight Movement, and CMAQ Improvement Program\n\nThis repository provides some scripts and tools written in R for effectively working with voluminous NPMRDS data for calculating the FHWA Transportation Performance Management (TPM) PM3 System Reliability, Freight, and CMAQ Congestion Performance  Performance Measures. For use with NPMRDS (2016 – Present) downloaded from https://npmrds.ritis.org/\n\nThe package consists of the following:\n\n* The `lottr` and `tttr` functions calculate TMC-segment Level of Travel Time Reliability (LOTTR) and Truck Travel Time Reliability (TTTR) metric scores. These are used to calculate Interstate / Non-Interstate NHS Percent of Person Miles Reliable and TTTR Index performance measures (see example code)\n* The `phed` function calculates the Annual Hours of Peak Hour Excessive Delay per Capita performance measure\n* The `hpms` function generates an HPMS Submittal File based on the [HPMS Field Manual Supplemental Guidance](https://www.fhwa.dot.gov/tpm/guidance/pm3_hpms.pdf)\n\n\n## Installation\n\nInstall from CRAN:\n```r\ninstall.packages(\"tpm\")\n```\n\nOr, for the latest build, install from source:\n```r\nlibrary(devtools)\ndevtools::install_github(\"markegge/fhwa_pm3\")\n```\n\n### A Minimal Example\n\n_To run the example below, create a RITIS NPMRDS export using the instructions below or copy `Readings.csv`, `TMC_Identification.csv` and `speed_limits.csv` from `tests/testthat` into your working directory. Note, the example below uses the same readings file is used for both the LOTTR and TTTR metrics. In the real world, the LOTTR metric should use All Vehicles travel time data, and the TTTR metric should use Trucks travel time data._\n\n```R\nlibrary(data.table)\nlibrary(tpm)\n\n# Calculate segment-level LOTTR and TTTR scores\n# Using \"All Vehicles\" readings file only for demo purposes\nlottr_scores \u003c- lottr(\"Readings.csv\")\ntttr_scores \u003c- tttr(\"Readings.csv\")\n\n# Read in TMC attributes from RITIS export\ntmcs \u003c- fread(\"TMC_Identification.csv\")\n\ntmcs[, nhs_miles := miles * nhs_pct * 0.01]\ntmcs[, vmt := ifelse(faciltype == 1, 1.0, 0.5) * aadt * nhs_miles]\ntmcs[, system := ifelse(f_system == 1, \"Interstate\", \"Non-Interstate NHS\")]\n\n# Merge the scoress table to the TMCs attribute table\ntmcs \u003c- merge(tmcs, lottr_scores, by.x = \"tmc\", by.y= \"tmc_code\")\ntmcs \u003c- merge(tmcs, tttr_scores, by.x = \"tmc\", by.y= \"tmc_code\", all.x = TRUE)\n\n# Calculate LOTTR scores\ntmcs[!is.na(vmt), .(pct_reliable = sum(vmt * reliable) / sum(vmt)), by = system]\n#\u003e                system pct_reliable\n#\u003e 1: Non-Interstate NHS    0.7545984\n#\u003e 2:         Interstate    1.0000000\n\n# Calculate TTTR score\ntmcs[f_system == 1, .(tttr_index = sum(max_tttr * nhs_miles) / sum(nhs_miles))]\n#\u003e    tttr_index\n#\u003e 1:       1.08\n\n# Calculating Peak Hour Excess Delay\nphed_scores \u003c- phed(travel_time_readings = \"Readings.csv\",\n                    tmc_identification = \"TMC_Identification.csv\",\n                    speed_limits = fread(\"speed_limits.csv\"),\n                    urban_code = 56139,\n                    population = 52898)\n#\u003e Peak Hour Excess Delay per Capita for 2020: 0.13 hours\n\n# Generate an HPMS Submittal File\n# Requires verbose = TRUE for LOTTR and TTTR scores\nhpms(\"TMC_Identification.csv\",\n     lottr(\"Readings.csv\", verbose = TRUE), \n     tttr(\"Readings.csv\", verbose = TRUE), \n     phed_scores)\n#\u003e Writing output to hpms_2021.txt\n```\n\n## Calculating LOTTR and TTTR Metric Scores\n\nTo calculate LOTTR or TTTR Metric scores:\n\n1. Log in to RITIS [https://npmrds.ritis.org/analytics/](https://npmrds.ritis.org/analytics/)\n2. Go to Massive Data Downloader\n3. Choose the appropriate \"TMC segments from\" value (e.g. \"NPMRDS INRIX 2019\")\n4. Choose your region (e.g. Wyoming) click Add\n5. Specify appropriate date range, e.g 01/01/2019 – 12/31/2019\n![Massive Data Downloader Region and Dates](man/figures/mdd_1.png)\n6. Select data sources and measures: \n    * \"NPMRDS form INRIX (Trucks and Passenger Vehicles): Travel Time\" for LOTTR Measure (the other fields are optional)\n    * \"NPMRDS from Inrix (Trucks): Travel Time\" for TTTR Measure\n9. Set averaging to 15 minutes (per PM3 Final Rule) and Submit\n![Massive Data Downloader Data Sources and Units](man/figures/mdd_2.png)\n10. Download and extract the resulting dataset\n11. Calculate scores using `lottr` and `tttr`. Monthly scores may be calculated using `monthly = TRUE` \n\n## Calculating PHED Scores\n\nThe package `phed()` function implements the calculation procedures in FHWA's guidance:\n[National Performance Measures for Congestion, Reliability, and Freight, and CMAQ Traffic Congestion (CMAQ PHED Calculation Procedures)](https://www.fhwa.dot.gov/tpm/guidance/hif18040.pdf)\n\nUsage:\n\n```R\nphed(\n  travel_time_readings,\n  tmc_identification,\n  speed_limits,\n  urban_code,\n  pm_peak = 3,\n  avo_cars = 1.7,\n  avo_trucks = 1,\n  avo_buses = 10.7,\n  moy_factor = moy_factor_default,\n  dow_factor = dow_factor_default,\n  hod_profile = hod_profile_default,\n  population = NA\n)\n```\n### Speed Limits\n\nAt a minimum, the `phed()` function requires speed limits for all TMC segments. The speed limits should be provided in a data.frame-like object in the following format:\n\n|tmc|speed_limit|\n|---|-----------|\n|000+10001|65|\n|000-10002|65|\n|000+10003|55|\n\n### Urban Code\n\nAn urbanized area code must by provided to filter the travel time observations to only the TMC segments within the matching urban area. (The easiest way to determine the urban area is to open the TMC shapefile and select a segment within the urban area to look up the urban_area field value.)\n\n### Peak Hours\n\nPer FHWA's guidance, the morning peak traffic hours occur between 6 am and 10 am. Agencies may choose their afternoon peak period as either 3 – 7 pm or 4 – 8 pm. For 3 – 7 pm, use `phed(..., pm_peak = 3)`. For 4 – 8 pm, use `phed(..., pm_peak = 4)`.\n\n### Occupancy Factors\n\nAverage vehicle occupancies are used to estimate person hours for delayed vehicles.\n\nDefault average vehicle occupancy (AVO) factors are provided (AVO Cars = 1.7, AVO Trucks = 1, AVO Buses = 10.7) based on FHWA guidance.  Default occupancy for cars is 1.7, trucks is 1, and buses = 10.7. Using AVO factors that are specific to your urban area are recommended. Urban-area specific data may be obtained via a local survey or from the NHTS. More details on obtaining local occupancy factors is provided by FHWA: [Average Vehicle Occupancy Factors for Computing Travel Time Reliability Measures and Total Peak Hour Excessive Delay Metrics (April 2018)](https://www.fhwa.dot.gov/tpm/guidance/avo_factors.pdf)\n\n\n### Traffic Volume Factors\n\nAdditionally, traffic volume factors and profiles are used to traslate AADT values (included in the NPMRDS `TMC_Identification.csv` file from HPMS) to hourly estimated \"persons\". Default profiles have been built into the function, but users are encouraged to use profiles that are specific the urbanized area. Factors must be provided for both freeway and non_freeway facilities (though these may be the same).\n\nFactors must be provided in the format below:\n\n#### Month of Year Factors\n\nFactors should correspond the mutliplicative factor to make an AADT value specific to the month.\n\n|month|freeway|non_freeway|\n|-----|-------|-----------|\n|1|0.95|0.96|\n|2|0.9|0.92|\n|...|...|...|\n|12|1.01|0.99|\n\n#### Day of Week Factors\n\nDay of week factors must be provided for weekdays using integer values for weekdays for a 7-day week beginning on Sundays (e.g. Monday = 2, Tuesday = 3, Wednesday = 4, Thursday = 5, Friday = 6).\n\n|day|freeway|non_freeway|\n|-----|-------|-----------|\n|2|1.05|1.05|\n|3|1.05|1.05|\n|...|...|...|\n|6|1.10|1.10|\n\n#### Hourly Volume Distribution Profile\n\nThe hourly volume profile must be provided for peak hours integer values for hours of the day (e.g. 6:00 am = 6). Note, values for freeway and non_freeway should correspond to the percent of daily traffic occuring during the hour. The profile may be provided for all 24 hours, or for selected peak hours only.\n\n|hour|freeway|non_freeway|\n|-----|-------|-----------|\n|6|0.05|0.05|\n|7|0.08|0.075|\n|...|...|...|\n|19|0.08|0.07|\n\nIf the population argument is provided, the function will output the calculated PHED per capita measure. The function returns a data.table with PHED per TMC.\n\n## Creating an HPMS Submittal File\n\nThe `hpms()` function outputs a .txt file in the appropriate format for HPMS submission. See the (HPMS Supplemental Guidance for PM3)[https://www.fhwa.dot.gov/tpm/guidance/pm3_hpms.pdf]\n\nIf the optional PHED scores are not provided (not required for all states), the PHED value is set to 0 (in accordance with FHWA guidance).\n\nThe input `lottr` and `tttr` scores *must* be generated with verbose = TRUE.\n\nThe output is generated for the year corresponding to the TMCs in the TMC Identification file.\n\n\n```R\n# Calculating Peak Hour Excess Delay\nspeed_limits \u003c- speed_limits = fread(\"speed_limits.csv\")\nphed_scores \u003c- phed(\"data/all_vehicles/Readings.csv\",\n                    \"TMC_Identification.csv\",\n                    speed_limits,\n                    urban_code = 56139)\n\n# Generate an HPMS Submittal File\nhpms(\"TMC_Identification.csv\",\n     lottr(\"data/all_vehicles/Readings.csv\", verbose = TRUE),\n     tttr(\"data/trucks/Readings.csv\", verbose = TRUE),\n     phed_scores)\n```\n\n\n## PM3 Guidance\n\nThe PM3 Performance measures are best described in [FHWA's June 1, 2017 PM3 Webinar Presentation](https://www.fhwa.dot.gov/tpm/rule/170601pm3.pdf)\n\nFWHA has also provided two sets of guidance on calculating the LOTTR and TTTR performance metrics:\n\n* [General Guidance and Step-by-Step Metric Calculation Procedures for National Performance Measures for Congestion, Reliability, and Freight, and CMAQ Traffic Congestion](https://www.fhwa.dot.gov/tpm/guidance/hif18040.pdf) \n* [FHWA Computation Procedure for Travel Time Based and Percent Non-Single Occupancy Vehicle (non-SOV) Travel Performance Measures](https://www.fhwa.dot.gov/tpm/guidance/hif18024.pdf)\n\nYou can also reference the definitive [Federal Register PM3 Final Rule](https://www.federalregister.gov/documents/2018/05/31/2018-11652/national-performance-management-measures-assessing-performance-of-the-national-highway-system).\n\n## TMC Network and Traffic Volumes\n\nEach year the TMC network is updated. This reflects improvements in TTI's conflation methodolgies, corrections submitted by users, as well as changes in the underlying attribute data.\n\nThe NPMRDS TMC network is a set of INRIX/HERE TMC segments to which selected HPMS attribtues have been conflated. There is a *two year lag* between the TMC network and the HPMS data. For example, the 2019 NPMRDS TMC network reflects AADT values based on 2017 HPMS. Since FHWA only requires traffic counts once every three years, some AADT values reported in the 2019 NPRMDS TMC network may be based on 2014 traffic counts. The NPMRDS reported AADT values should be calculating PM3 Performance Measures, but for other analysis it is better to use more recent sources of traffic counts. \n\nFor a method for estimating order-of-magnitude traffic volumes using NPMRDS data itself, see [this repository](https://bitbucket.org/high-street/npmrds_probe_counts/).\n\n## Attribution\n\nPackage author: Mark Egge, High Street (egge@highstreetconsulting.com)\n\nLicense: Mozilla Public License Version 2.0\n\n## What's New\n* 2.0.2 (5/30/2024): hpms() function now requires a `file` argument, e.g. (`hpms(\"hpms_2023.txt\", ...)`). \n* May 2024: Renamed package from \"pm3\" to \"tpm.\" Updated for compatibility with R 4.4+\n* June 15, 2022: Refactored function calls to provide greater consistency between measures. LOTTR and TTTR are now scored using `lottr()` and `tttr()` respectively, rather than `score()`. HPMS function now accepts PHED scores.\n* June 10, 2022: Added PHED function to calculate PHED given a travel time readings file and speed limits\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkegge%2Ffhwa_pm3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkegge%2Ffhwa_pm3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkegge%2Ffhwa_pm3/lists"}