Source code for

Modules for Reading/Writing the International Consortium for Atmospheric
Research on Transport and Transformation (ICARTT) file format standards V2.0

    ICARTT V2.0 Standards/Conventions:

import xarray as xr

    import icartt

    _format = icartt.Formats.FFI1001
except ImportError:
    _format = None

[docs]def read_icartt(filename, format=_format, return_None=False, **kwargs): """ Returns `xarray.Dataset` with stored data and metadata from a user-defined query of ICARTT from a single datastream. Has some procedures to ensure time is correctly fomatted in returned Dataset. Parameters ---------- filename : str Name of file to read. format : str ICARTT Format to Read: FFI1001 or FFI2110. return_None : bool, optional Catch IOError exception when file not found and return None. Default is False. **kwargs : keywords keywords to pass on through to icartt.Dataset. Returns ------- ds : xarray.Dataset (or None) ACT Xarray dataset (or None if no data file(s) found). Examples -------- This example will load the example sounding data used for unit testing. .. code-block :: python import act ds = print(ds.attrs['_datastream']) """ if not _ICARTT_AVAILABLE: raise ImportError("ICARTT is required to use to read ICARTT files but is not installed") ds = None # Create an exception tuple to use with try statements. Doing it this way # so we can add the FileNotFoundError if requested. Can add more error # handling in the future. except_tuple = (ValueError,) if return_None: except_tuple = except_tuple + (FileNotFoundError, OSError) try: # Read data file with ICARTT dataset. ict = icartt.Dataset(filename, format=format, **kwargs) except except_tuple as exception: # If requested return None for File not found error if type(exception).__name__ == 'FileNotFoundError': return None # If requested return None for File not found error if type(exception).__name__ == 'OSError' and exception.args[0] == 'no files to open': return None # Define the Uncertainty for each variable. Note it may not be calculated. # If not calculated, assign 'N/A' to the attribute uncertainty = ict.normalComments[6].split(':')[1].split(',') # Define the Upper and Lower Limit of Detection Flags ulod_flag = ict.normalComments[7].split(':')[1] ulod_value = ict.normalComments[8].split(':')[1].split(',') llod_flag = ict.normalComments[9].split(':')[1] llod_value = ict.normalComments[10].split(':')[1].split(',') # Convert ICARTT Object to Xarray Dataset ds_container = [] # Counter for uncertainty/LOD values counter = 0 # Loop over ICART variables, convert to Xarray DataArray, Append. for key in ict.variables: # Note time is the only independent variable within ICARTT # Short name for time must be "Start_UTC" for ICARTT files. if key != 'Start_UTC': if key == 'qc_flag': key2 = 'quality_flag' else: key2 = key da = xr.DataArray([key], coords=dict(time=ict.times), name=key2, dims=['time']) # Assume if Uncertainity does not match the number of variables, # values were not set within the file. Needs to be string! if len(uncertainty) != len(ict.variables): da.attrs['uncertainty'] = 'N/A' else: da.attrs['uncertainty'] = uncertainty[counter] # Assume if ULOD does not match the number of variables within the # the file, ULOD values were not set. if len(ulod_value) != len(ict.variables): da.attrs['ULOD_Value'] = 'N/A' else: da.attrs['ULOD_Value'] = ulod_value[counter] # Assume if LLOD does not match the number of variables within the # the file, LLOD values were not set. if len(llod_value) != len(ict.variables): da.attrs['LLOD_Value'] = 'N/A' else: da.attrs['LLOD_Value'] = llod_value[counter] # Define the meta data: da.attrs['units'] = ict.variables[key].units da.attrs['mvc'] = ict.variables[key].miss da.attrs['scale_factor'] = ict.variables[key].scale da.attrs['ULOD_Flag'] = ulod_flag da.attrs['LLOD_Flag'] = llod_flag # Append to ds container ds_container.append(da.to_dataset(name=key2)) # up the counter counter += 1 # Concatenate each of the Xarray DataArrays into a single Xarray DataSet ds = xr.merge(ds_container) # Assign ICARTT Meta data to Xarray DataSet ds.attrs['PI'] = ict.PIName ds.attrs['PI_Affiliation'] = ict.PIAffiliation ds.attrs['Platform'] = ict.dataSourceDescription ds.attrs['Mission'] = ict.missionName ds.attrs['DateOfCollection'] = ict.dateOfCollection ds.attrs['DateOfRevision'] = ict.dateOfRevision ds.attrs['Data_Interval'] = ict.dataIntervalCode ds.attrs['Independent_Var'] = str(ict.independentVariable) ds.attrs['Dependent_Var_Num'] = len(ict.dependentVariables) ds.attrs['PI_Contact'] = ict.normalComments[0].split('\n')[0].split(':')[-1] ds.attrs['Platform'] = ict.normalComments[1].split(':')[-1] ds.attrs['Location'] = ict.normalComments[2].split(':')[-1] ds.attrs['Associated_Data'] = ict.normalComments[3].split(':')[-1] ds.attrs['Instrument_Info'] = ict.normalComments[4].split(':')[-1] ds.attrs['Data_Info'] = ict.normalComments[5][11:] ds.attrs['DM_Contact'] = ict.normalComments[11].split(':')[-1] ds.attrs['Project_Info'] = ict.normalComments[12].split(':')[-1] ds.attrs['Stipulations'] = ict.normalComments[13].split(':')[-1] ds.attrs['Comments'] = ict.normalComments[14].split(':')[-1] ds.attrs['Revision'] = ict.normalComments[15].split(':')[-1] ds.attrs['Revision_Comments'] = ict.normalComments[15 + 1].split(':')[-1] # Assign Additional ARM meta data to Xarray DatatSet ds.attrs['_datastream'] = filename.split('/')[-1].split('_')[0] # Return Xarray Dataset return ds