brukeropus.file.labels

  1import warnings
  2from brukeropus.file.constants import TYPE_CODE_LABELS, PARAM_LABELS, CODE_3_ABR
  3
  4
  5__docformat__ = "google"
  6
  7
  8def get_param_label(param: str):
  9    '''Returns a short but descriptive label for 3-letter parameters. For example, bms returns Beamsplitter.
 10
 11    The 3-letter parameter input is not case sensitive.  This package includes the majority of parameters that OPUS
 12    uses, but in the event a parameter label is not known, this function will return: "Unknown XXX" where XXX is the
 13    unknown 3-letter parameter.
 14
 15    Args:
 16        param: three letter parameter code (e.g. bms, src, npt, etc.) [not case sensitive]
 17
 18    Returns:
 19        label (str): Human-readable string label for the parameter.
 20    '''
 21    try:
 22        return PARAM_LABELS[param.upper()]
 23    except KeyError:
 24        return 'Unknown ' + param.upper()
 25
 26
 27def get_type_code_label(pos_idx: int, val: int):
 28    '''Returns the type code label of a file block given the position index and value of the type code.
 29    
 30    **Depreciation Warning:** function will be removed soon. Functionality has been integrated into `BlockType` class.
 31
 32    The file blocks on an OPUS file feature six-integer type codes, for example (3, 1, 1, 2, 0, 0), that categorize the
 33    contents of the file block. The positional index defines the category, while the value at that index defines the
 34    specific type of that category.  For example, the first integer (pos_idx=0), describes the type of data in the
 35    block, if applicable:
 36
 37        0: Undefined or N/A,
 38        1: Real Part of Complex Data,
 39        2: Imaginary Part of Complex Data,
 40        3: Amplitude
 41
 42    This package includes the majority of type codes that OPUS uses, but in the event a type code label is not known,
 43    this function will return: "Unknown 0 4" where the first number is the position index, and the second is the
 44    unknown value integer.
 45
 46    Args:
 47        pos_idx: positional index of the type code (0 - 5)
 48        val: value of the type code
 49
 50    Returns:
 51        label (str): human-readable string label that describes the type code.
 52    '''
 53    warnings.warn('Depreciation warning: get_type_code_label will soon be removed. This functionality has moved to BlockType class')
 54    try:
 55        return TYPE_CODE_LABELS[pos_idx][val]
 56    except KeyError:
 57        return 'Unknown ' + str(pos_idx) + ' ' + str(val)
 58
 59
 60def get_block_type_label(block_type: tuple):
 61    '''Converts a six-integer tuple block type into a human readable label.
 62    
 63    **Depreciation Warning:** function will be removed soon. Functionality has been integrated into `BlockType` class.
 64
 65    Args:
 66        block_type: six integer tuple found in the OPUS file directory that describes the block type
 67
 68    Returns:
 69        label (str): human-readable string label
 70    '''
 71    warnings.warn('Depreciation warning: get_block_type_label will soon be removed. This functionality has moved to BlockType class')
 72    labels = [get_type_code_label(idx, val) for idx, val in enumerate(block_type) if val > 0
 73              and get_type_code_label(idx, val) != '']
 74    return ' '.join(labels)
 75
 76
 77def get_data_key(block_type: tuple):
 78    '''Returns a shorthand key for a given data block type: sm, rf, igsm, a, t, r, etc.
 79
 80    Determines if the data block type is an interferogram, single-channel, absorption, etc. and whether it is associated
 81    with the sample or reference channel and returns a shortand key-like label: sm, rf, igsm, igrf, a, t, r, etc.  For
 82    the full data label (e.g. Sample Spectrum, Absorbance) use: get_block_type_label.
 83    This package includes the majority of type codes that OPUS uses, but in the event a type code label is not known,
 84    this function will return: "_33" or "sm_33" where 33 will change to the unkown block_type integer value.
 85
 86    Args:
 87        block_type: six integer tuple found in the OPUS file directory that describes the block type
 88
 89    Returns:
 90        key (str): shorthand string label that can be utilized as a data key (e.g. "sm", "igrf", "a")'''
 91    if block_type[3] in CODE_3_ABR.keys():
 92        key = CODE_3_ABR[block_type[3]]
 93        if block_type[1] == 1:
 94            key = merge_key(key, 'sm')
 95        elif block_type[1] == 2:
 96            key = merge_key(key, 'rf')
 97        elif block_type[1] > 3:
 98            key = key + '_' + str(block_type[1])
 99    else:
100        key = '_' + str(block_type[3])
101        if block_type[1] == 1:
102            key = 'sm' + key
103        elif block_type[1] == 2:
104            key = 'rf' + key
105        elif block_type[1] > 3:
106            key = '_' + str(block_type[1]) + key
107    if block_type[5] == 4:
108        key = key + '_c'
109    return key
110
111
112def merge_key(key: str, sm: str):
113    '''Merges "sm" or "rf" into an abreviated data key.  For special cases like ig or pw, the addition is appended
114    (e.g. igsm, phrf), but for other cases, the addition is prepended (e.g. sm_2ch, rf_3ch)'''
115    if key[:2] in ['ig', 'ph', 'pw']:
116        return key[:2] + sm + key[2:]
117    else:
118        return sm + key