Path & Directory Structure

soundDENA relies on the regularity of the NSNSD file structure and naming scheme to be able to locate file types across multiple sites. In order to be easily reconfigurable to future changes or different systems, however, the expected layout of this file structure is defined in just one place: the paths submodule. soundDENA.paths defines many constants that specify where different directories can be found, as well as functions for mapping between site identifiers. Because the rest of the library only uses these methods and constants, never assuming the format of names or folders, adapting to a new naming convention only requires modifying simple code in this file.

Terms & Formats

Term	Format	Example	Description
unit	AAAA	DENA	Four-character alphanumeric code for the unit (park) of the site
site	AAAA	FANG	Four-character alphanumeric code for the site itself
year	9999	2013	Four-character numeric code for the year of sampling of the site
siteID	UNITSITEYEAR	DENAFANG2013	A string identifier for a unique sampling of data. siteID is used throughout soundDENA as the standard way to identify and refer to a site across many contexts.
dataDir	YEAR UNITSITE <title>	2013 DENAFANG Fang Mountain	The root directory containing raw and analyzed data for a particular site

Name-Formatting Methods

soundDENA.paths.dataDir(unit, site, year, title='')

Formats unit, site, year, and title into the name of a data directory (i.e. 2014 DENABACK Backside Lake)

soundDENA.paths.dataDirs(sites, quiet=True)

Generator that returns paths to raw data directories corresponding to the given sites.

Sites can be a pandas DataFrame or Series, in which case its index is used as the site IDs. Otherwise, an iterable or singleton string of site ID(s) also works. Paths are yielded in the same order the sites are given (though some may be missing if data is not available).

Yields a tuple of (pathlib.Path, unit, site, year) for the directories that contian raw data for the sites.

soundDENA.paths.getDataDirPath(*args)

Given a site ID string, or unit, site, and year, returns a pathlib.Path to that site’s data directory.

Raises ValueError for invalid site identifiers, or IOError for non-existent sites.

soundDENA.paths.siteID(unit, site, year)

Formats unit, site, and year into a site ID (UNITSITEYEAR, i.e. DENAUPST2015)

soundDENA.paths.splitDataDir(dataDir)

Returns a 4-tuple of unit, site, year, and title for a data directory (pathlib.Path, or string). Data directory names are formatted as: YEAR UNITSITE <title>, i.e. 2014 GAARNWAL North Walker Lake

soundDENA.paths.splitSiteID(siteID)

Returns a 3-tuple of unit, site, and year for a site ID string. Site IDs are formatted as UNITSITEYEAR, i.e. DENAUPST2015

Base Absolute Locations

soundDENA.paths.t_analysis = WindowsPath('T:/ResMgmt/WAGS/Sound/Analysis')

soundDENA.paths.derivedData = WindowsPath('T:/ResMgmt/WAGS/Sound/Analysis/DENA Parkwide Derived Data 2015 09 15 T.xls')

soundDENA.paths.metadata = WindowsPath('T:/ResMgmt/WAGS/Sound/Analysis/Complete_Metadata_AKR_2001-2015 T.xlsx')

soundDENA.paths.rawdata = WindowsPath('E:/AKRO Soundscape Data')

Directory Structure Constants

soundDENA.paths.data = WindowsPath('01 DATA')

soundDENA.paths.nvspl = WindowsPath('01 DATA/NVSPL')

soundDENA.paths.audio = WindowsPath('01 DATA/AUDIO')

soundDENA.paths.photos = WindowsPath('01 DATA/PHOTOS')

soundDENA.paths.partial_nvspl = WindowsPath('01 DATA/PartialDays_NVSPL')

soundDENA.paths.analysis = WindowsPath('02 ANALYSIS')

soundDENA.paths.spl = WindowsPath('02 ANALYSIS/SPL Analysis')

soundDENA.paths.wav = WindowsPath('02 ANALYSIS/WAV Analysis')

soundDENA.paths.computed = WindowsPath('02 ANALYSIS/Computational Outputs')

soundDENA.paths.microarray = WindowsPath('02 ANALYSIS/WAV Analysis/Microarray')