Refactor repository for clarity and geographic flexibility, v2.0.0 re…

…lease (#6)

* Ground truth (#4)

Project restructure and ground truthing and utils modules

* fix EarlyADSB bug

* Active space (#5)

Creation of Active Space Module

* initialize v2 README

* an active space map example

* add image with accompanying text

* Add order of operations to NPS-ActiveSpace README

* Delete README.md

* Delete README.md

* `EarlyAdsb` - correct altitude in feet to meters

* minor map symbology modifications

* create CITATION.cff 

Initialize prior to v2.0.0 release. (Will need update with DOI number post-release.)

Co-authored-by: dzucker7 <[email protected]>

.gitignore

@@ -0,0 +1,19 @@
+# Pycharm
+.idea
+
+# venv
+.venv*
+
+# python
+**/__pycache__
+*.pyc
+
+# pyenv
+.python-version
+
+# .egg-info
+*.egg-info/
+
+# config files
+_DENA/config/*
+!_DENA/config/template.config

CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+title: NPS-ActiveSpace
+message: >-
+  This software was created by the United States
+  government and is in the public domain. Please cite
+  as below:
+type: software
+authors:
+  - given-names: Davyd Halyn
+    family-names: Betchkal
+    email: [email protected]
+    affiliation: U.S. National Park Service
+  - given-names: Adina
+    family-names: Zucker
+    affiliation: U.S. National Park Service
+  - given-names: Kirby
+    family-names: Heck
+    affiliation: U.S. National Park Service
+repository-code: 'https://github.com/dbetchkal/NPS-ActiveSpace'
+version: v2.0.0
+date-released: '2022-12-23'

README.md

@@ -1,49 +1,53 @@
-# NPS-ActiveSpace
+# NPS Active Space
 
-Authors: <br>
-Kirby Heck (Denali 2021 SIP - Computing) <br>
-Davyd Betchkal
+An ***active space*** is a well-known concept in bioacoustics ([Marten and Marler 1977](https://www.jstor.org/stable/pdf/4599136.pdf)). It represents a geographic volume whose radii correspond to the limit of audibility for a specific signal. In other words, an active space provides an answer to the question, *"how far can you hear a given sound at a specific place on Earth's surface?"*
 
+This repository is designed to estimate active spaces for fixed-wing aircraft noise within the U.S. National Park System. Aircraft are powerful noise sources audible over vast areas. Thus [considerable NPS management efforts have focused on protecting natural quietude from aviation noise](https://www.nps.gov/subjects/sound/overflights.htm). `NPS-ActiveSpace` provides a quantitative tool to support managers in monitoring park resource condition. 
 
-The NPS-ActiveSpace repository includes two components: overflight audiblity ground-truthing and creation and analysis of a representative 'active space' corresponding to propeller noise for a geographic region. 
+Consider an example active space, below. It was computed using data from a long term acoustic monitoring site in Denali National Park, DENAUWBT Upper West Branch Toklat ([Withers 2012](https://irma.nps.gov/DataStore/Reference/Profile/2184396)). The bold black polygon delineates an active space estimate for flights at 3000 meters altitude. Points interior to the polygon are predicted to be audible, those exterior inaudible. <br> 
 
-NPS-ActiveSpace has several dependencies. Dependencies are found at the Github links below: 
-  > Iyore: <a href="https://github.com/nationalparkservice/iyore">NPS/Iyore</a> <br>
-  > NMSIM-Python: <a href="https://github.com/dbetchkal/NMSIM-Python">dbetchkal/NMSIM-Python</a> <br>
-  > soundDB: <a href="https://github.com/gjoseph92/soundDB">gjoseph92/soundDB</a> <br>
-  > GDAL Translate: <a href="https://apps.nationalmap.gov/raster-conversion/gdal-installation-and-setup-guide.html">USGS Instructions</a>
+Superposed over the polygon are colored flight track polylines. `NPS-ActiveSpace` includes an application that leverages the acoustic record to ground-truth audibility of co-variate vehicle tracks from GPS databases. Ground-truthing is used to "tune" an active space to the appropriate geographic extent.<br>
+<br>
+<img src="https://github.com/dbetchkal/NPS-ActiveSpace/blob/v2/nps_active_space/img/NPS-ActiveSpace_example.png" alt="active space polygon example" width="300">
 
-Additionally, overflights are queried from a databased developed by <a href="https://github.com/smHooper/flightsdb">smHooper</a>. 
 
-The DENA_overflights repository holds two function libraries `active_space_utils.py` and `noise_metrics.py`. 
+## Packages
 
+This project is made up of four packages:
 
-## Ground Truthing
+`utils`: diverse utilities - file I/O, geoprocessing computations, acoustic propagation modelling, and detection statistics
+
+`ground-truthing`: a `tkinter`-based ground-truthing application
 
-Ground truthing involves loading existing flight tracks (either GPS or ADS-B) on top of an existing acoustic record from soundDB. The ground truthing user interface loads flights from a study area around microphone coordinates and plots the (sparse) tracks on a map with a highlighted region of (dense, spline-fit) points. On the right, a spectrogram from the acoustic record shows the noise for the same temporal bounds. Moving the sliders allows the user to annotate when a flight is audible (in the time domain) and _see_ the result in the spatial domain. Accounts for the speed of sound (assumed to be 343 m/s). 
-![truthing](https://user-images.githubusercontent.com/8905274/130698861-3172948d-217b-4d4d-ad5e-7bd8b4a8c00c.png)
+`active-space`: generate and tune active space polygons
 
-The ground truthing results in a saved annotations file that can be loaded in later to distinguish between audible and inaudible points. The goal is to create a shape in NMSim that best fits the 'audible' region without including too much of the 'inaudible' region; this region is dubbed the _active space_. 
+`analysis`: estimate acoustic metrics from the intersection of an active space polygon and vehicle tracks
 
-Note that the active space is truly a three-dimensional space and not a two-dimensional plane; that is, the area of a planar slice of the active space is dependent on its elevation (or flight altitude). Additionally, the active space corresponds to a particular noise source or aircraft; the active space for a helicopter is not the same as the active space for a fixed-wing aircraft or a commercial jet. 
+Also included are noise source [data](https://github.com/dbetchkal/NPS-ActiveSpace/tree/v2/nps_active_space/data) for tuning active space polygons.
 
-A sample inventory of ground truthing sites in Denali performed in 2021: 
-![inventory](https://user-images.githubusercontent.com/8905274/130700132-c95aba5c-00e6-4707-8be3-fea9ba28ba90.png)
+***For more specific information on each package, view their individual READMEs.***
 
+## Order of Operations
 
-## Active Space Creation
+While each package can be used and run individually, the project was designed so that outputs of one package work seamlessly as the inputs for another. 
 
-There are three key components to active space creation: acoustic ambience levels, noise source file, and digital elevation model (DEM). NMSim is a sound propagation model that simulates the propagation of sound from a noise source over terrain; comparing NMSim results to the acoustic ambience (either third-octave bands _or_ broadband) will determine whether or not the flight is audible in a given location. This usage of NMSim is certainly <a href="https://nwtteis.com/portals/nwtteis/files/references/Ikelheimer_2004_NMSim_User_Manual.pdf">outside of its realm of intended use</a> but does an astoundingly good job regardless. The process for creating an active space looks a bit like the following: 
-![algorithm](https://user-images.githubusercontent.com/8905274/130701270-c6c26f0a-ff7d-4812-95d3-e93640b00fe5.png)
+Packages were designed to be run in the following order:
 
-Because broadband ambience is a viable comparison to detect audibility (although from 2021 ground truthing, it was determined that a noise source of around +23 dB should be used to compensate), park-wide or state-wide broadband models can be used to compute the active space for _any_ location given a DEM. 
+1. `ground-truthing`
+2. `active-space`
+3. `analysis`
 
+## License
 
-## Noise Impact Analysis and Metrics
+**Authors**: <br>Kirby Heck<br>Adina Zucker<br>Davyd Halyn Betchkal
 
-This final step is under development. The end goal is to quantify the noise impact of _real overflights_ given the theoretical active space with one grand assumption: if a flight is within the active space, then it is audible. For active spaces with landings (e.g. into basecamp on Denali or in the Ruth amphitheater), we will see that this is not a good assumption, but this is future work. 
+### Public domain
 
-Given a flight track, interpolating/densifying points resolves when a flight crosses into and out of an active space. The time inside an active space is therefore a noise interval, and a single track could theoretically pass in and out of an active space multiple times in one flight. The noise impacts can be derived most simply by counting the number of non-overlapping noise events (intervals), and more complicated metrics can be derived from the noise-free intervals (times where there are no noise intervals) or even factoring in the distance of the overflight (energy based metrics). 
+This project is in the worldwide [public domain](LICENSE.md):
 
-Note that this method of quantifying noise impacts only uses flight tracks and computational effort... no microphones in the field! Here is an example from the Triple Lakes trail on a particularly noisy afternoon in June, 2021: 
-![metrics](https://user-images.githubusercontent.com/8905274/130703201-efd366cc-5a04-4443-9a02-6a8ba702f490.png)
+> This project is in the public domain within the United States,
+> and copyright and related rights in the work worldwide are waived through the
+> [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
+>
+> All contributions to this project will be released under the CC0 dedication.
+> By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.