brukeropus.file.labels

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