{"id":17860145,"url":"https://github.com/dbetchkal/acousticrecord","last_synced_at":"2026-02-15T15:01:30.991Z","repository":{"id":160105458,"uuid":"204069163","full_name":"dbetchkal/AcousticRecord","owner":"dbetchkal","description":"Simulating observation of an acoustic environment, while retaining noise and natural sound as independent components of the system.","archived":false,"fork":false,"pushed_at":"2022-12-22T00:15:21.000Z","size":1096,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-13T22:21:31.918Z","etag":null,"topics":["acoustics","ambient-sounds","detection-model","simulation"],"latest_commit_sha":null,"homepage":"","language":"Python","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/dbetchkal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-08-23T20:59:09.000Z","updated_at":"2024-05-18T11:14:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"d2ad37c4-1d95-4a64-9e5c-75ca6925f28b","html_url":"https://github.com/dbetchkal/AcousticRecord","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dbetchkal/AcousticRecord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbetchkal%2FAcousticRecord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbetchkal%2FAcousticRecord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbetchkal%2FAcousticRecord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbetchkal%2FAcousticRecord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbetchkal","download_url":"https://codeload.github.com/dbetchkal/AcousticRecord/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbetchkal%2FAcousticRecord/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29481924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T11:35:25.641Z","status":"ssl_error","status_checked_at":"2026-02-15T11:34:57.128Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["acoustics","ambient-sounds","detection-model","simulation"],"created_at":"2024-10-28T07:22:46.259Z","updated_at":"2026-02-15T15:01:30.966Z","avatar_url":"https://github.com/dbetchkal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AcousticRecord\n\n\u003eA model is not a load of mathematics, as some people think; nor is it some unrealizable ideal, as others believe. It is simply an account expressed as you will – of *the actual organization of a real system.* Without a model of the system to be regulated, you cannot have a regulator.\n\u003e\n\u003e— Stafford Beer, [Designing Freedom 1973](https://archive.org/details/DesigningFreedom_CBC_Lectures), pg. 11\n\n\u003cbr\u003e\n\nThis repository contains a very simple Python class. It allows users to simulate observation of an acoustic environment; what we might call an 'audio recording' or simply a 'record'. Specifically, it simulates time series that conform to [National Park Service measurement standards](https://www.nps.gov/subjects/sound/upload/NSNSDTrainingManual_AcousticalAmbientMonitoring-508.pdf): one-second averages of broadband sound level [ *Leq, 1s (12.5Hz - 20kHz)* ]. \u003cbr\u003e\n\nWithin the ecological paradigm of acoustics, the system we're describing (the acoustic environment) has two separate components: **natural sound** and **noise**. These signals are necessarially superposed when they arrive at the microphone. Therefore it is of great interest to have the means to control each component indepenantly. Especially so if we can describe effects on observation of acoustic metrics once the signals have been superposed.\u003cbr\u003e\n\nThe main assumption of the model? **Noise is created by an ideal acoustic point source.** That's it. Most other attributes of the system can be user defined (within reason.) The observed phenomena then follow from physical principle.\u003cbr\u003e\n\n----\n\n## Downloading and using this module\n\nUse [git](https://git-scm.com/) to clone the repository.  Using the path to the repository on your local disk, import the `AcousticRecord` class: \n\n```\nimport sys\nsys.path.append(r\"\\*\\*\\AcousticRecord\")\n\nfrom AcousticRecord import AcousticRecord\n```\n\n`AcousticRecord` requires `numpy`. Work with the module is [highly enhanced through the use of `soundDB`](https://github.com/gjoseph92/soundDB) to load empirical observations.\n\n\u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by/4.0/\"\u003e\u003cimg alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by/4.0/88x31.png\" /\u003e\u003c/a\u003e\u003cbr /\u003eThis work is licensed under a \u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by/4.0/\"\u003eCreative Commons Attribution 4.0 International License\u003c/a\u003e.\n\n\n----\n\n## The `AcousticRecord` class\n\n### Initializing a record\nWe begin by initializing a record. Records must have:\n\n- a length, in days\n- a certain number of vehicles moving past the mic location (*regardless of whether they are audible or not*)\n\nHere's how you would initialize a 28 day record with 2000 aircraft moving past the mic:\n```\nrec = AcousticRecord(28, 2000)\n```\nAt this point the object has no associated time series. It does have attributes which can be useful for setting up a simulation:\n\nThe length of the record in seconds:\n```\n\u003e\u003e\u003e rec.duration \n2419200\n```\n\nThe number of days we just entered:\n```\n\u003e\u003e\u003e rec.n_days \n28\n```\n\nThe number of events we just entered:\n```\n\u003e\u003e\u003e rec.n_events \n2000\n```\nTraffic properties have also been initialized using default values as follows.\n\nA numpy array representing the maximum Leq, 1s for each of our 2000 aircraft overflights:\n```\n\u003e\u003e\u003e rec.Lmax_distribution\narray([64.8, 58.1, 73.5, ..., 46.7, 20.7, 59.8]) \n```\n\nA numpy array representing the 'full-width at half maximum' duration of each overflight, in seconds:\n```\n\u003e\u003e\u003e rec.fwhm_duration_distribution\narray([ 78.15853618, 130.0608868 , 129.35119917, ..., 152.25337917,\n       156.49251599, 130.17474321])\n```\n\nA numpy array representing the time at which Lmax occurs for each overflight, in seconds elapsed:\n```\n\u003e\u003e\u003e rec.center_times\narray([1939102,  425068, 2067604, ...,  474626, 1192696, 1974440])\n```\n\n\nThese all can be (and for most useful purposes, *should* be) reassigned by the user! A trivial modification example: reset all the durations to a constant value, 100 seconds:\n```\nrec.fwhm_duration_distribution = np.full(shape=rec.n_events, fill_value=100)\n```\n\n---\n\n### Natural Ambient Acoustic Energy\n\n**Noise has *no physical meaning* outside of the natural ambient acoustic energy it is embedded in.** So we must add some ambience to our record. It can be done in several ways.\n\u003cbr\u003e\n\nFor quick sketches, you can use a constant, scalar value:\n```\nrec.add_ambience(25.6)\n```\n\u003cimg src=\"https://github.com/dbetchkal/AcousticRecord/blob/master/AcousticRecord_figure1.png\" alt=\"figure1\" class=\"inline\"/\u003e\n\nHowever, it's often more realistic to simulate ambience as a temporal process. The following example simulates an acoustic environment where atmospheric refraction causes conditions to become more energetic in the early hours of the morning:\n```\n# remember A sin(Bx) + D, where A is the amplitude, B/2pi is the period, and D is the vertical offset\nB = (2*np.pi)/(24*3600) # one oscillation takes 24 hours\n\nnocturnal_increase = 5*np.sin(B*np.arange(rec.duration))+25.6\nrec.add_ambience(nocturnal_increase)\n```\n\u003cimg src=\"https://github.com/dbetchkal/AcousticRecord/blob/master/AcousticRecord_figure2.png\" alt=\"figure1\" class=\"inline\"/\u003e\n\n---\n### An acoustic record: the superposition of natural ambience and noise\n\nOnce ambience has been added we have array access to three time series: \n\nThe natural ambience we just defined...\n```\n\u003e\u003e\u003e rec.ambient\narray([25.6, 25.6, 25.6, ..., 25.6, 25.6, 25.6]) \n```\n\n...a time series of noise, including overlap (if it occurs):\n```\n\u003e\u003e\u003e rec.event_record\narray([0., 0., 0., ..., 0., 0., 0.])\n```\nThe superposition of noise and ambient accounting for masking. \u003cbr\u003e Importantly **this approximates what a microphone would record**:\n```\n\u003e\u003e\u003e rec.full_record\narray([25.61194502, 25.61194502, 25.61194502, ..., 25.61194502,\n       25.61194502, 25.61194502])\n```\nWe also have access to the bounds of noise and quiet as they would be *observed*. These are based off the intervals of time where noise was greater in amplitude than the ambient.\n\nStart and end times of noise:\n```\n\u003e\u003e\u003e rec.noise_intervals\narray([[   1425,    1657],\n       [   1964,    2161],\n       [   8643,    8828],\n       ..., \n       [2414790, 2415052],\n       [2415857, 2416100],\n       [2416441, 2416683]], dtype=int64)\n```\n\nStart and end times of quietude:\n```\n\u003e\u003e\u003e rec.noise_free_intervals\narray([[      0,    1425],\n       [   1657,    1964],\n       [   2161,    8643],\n       ..., \n       [2415052, 2415857],\n       [2416100, 2416441],\n       [2416683, 2419200]], dtype=int64)\n```\n\n---\n\n### Access to acoustic metrics\n\nThough the binarized noise/non-noise time periods are helpful for detailed use cases, more commonly a user may want a few metrics without the fuss of performing the calculations oneself. `AcousticRecord` automatically calculates many of these metrics when the `.add_ambience()` method is used. This gives us three attributes:\n\nA summary of energy-based metrics:\n```\n\u003e\u003e\u003e rec.SPL_summary_metrics\n```\nwhich results in a 2D numpy array of the following values\n\u003e[0] one-second broadband sound pressure levels for each noise event \u003cbr\u003e\n\u003e[1] the equivalent sound pressure level over the duration of the event (Leq, \u0026ast;) \u003cbr\u003e\n\u003e[2] the sound exposure level of the event \u003cbr\u003e\n\u003e[3] the median sound pressure level of the event \u003cbr\u003e\n\u003e[4] the maximum one-second sound pressure level of the event (maximum Leq, 1s) \u003cbr\u003e\n\u003e[5] the time at which the maximum one-second sound pressure level occurred\n\nA summary of duration-based metrics:\n```\n\u003e\u003e\u003e rec.duration_summary_metrics\n```\nwhich results in a 2D numpy array of the following values\n\u003e[0] a list of each event's duration \u003cbr\u003e\n\u003e[1] the mean duration \u003cbr\u003e\n\u003e[2] the standard deviation of the durations \u003cbr\u003e\n\u003e[3] the median duration \u003cbr\u003e\n\u003e[4] the median absolute deviation of the durations\n\nFinally there is a very simple list of noise-free intervals:\n```\n\u003e\u003e\u003e rec.nfi_list\n```\n\nThese can be exceptionally helpful for analyzing the effects of changing human and/or natural conditions on acoustic metrics.\nFor example, it can be used to show how changing ambient biases the observed distribution of Sound Exposure Levels: \u003cbr\u003e\u003cbr\u003e\n\u003cimg src=\"https://github.com/dbetchkal/AcousticRecord/blob/master/SEL_CDFs_with_changing_natural_ambience.png\" alt=\"figure1\" class=\"inline\"/\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbetchkal%2Facousticrecord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbetchkal%2Facousticrecord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbetchkal%2Facousticrecord/lists"}