Skip to content

DFT datatypes

C pynasonde.digisonde.datatypes.dftdatatypes — DopplerSpectralBlock, DopplerSpectra, DftHeader, SubCaseHeader

Dataclasses modeling DFT-format headers and spectral blocks.

pynasonde.digisonde.datatypes.dftdatatypes

DFT datatypes used by the Digisonde DFT parser.

This module defines small dataclass containers that mirror the on-disk DFT record structures used by Digisonde DFT-format files. The classes are lightweight holders for parsed fields and provide small normalization steps in __post_init__ where appropriate.

These types are intended to be used by the parser code under pynasonde.digisonde.parsers.dft and by higher-level utilities that need structured access to the parsed header and spectral data.

DopplerSpectralBlock dataclass

Top-level block containing a DFT header and associated spectra.

Attributes:

Name Type Description
header DftHeader

DftHeader instance describing block-level metadata.
spectra_line List[DopplerSpectra]

List of DopplerSpectra instances (one per height/frequency sample) contained in the block.
Source code in pynasonde/digisonde/datatypes/dftdatatypes.py 
230
231
232
233
234
235
236
237
238
239
240
241
@dataclass
class DopplerSpectralBlock:
    """Top-level block containing a DFT header and associated spectra.

    Attributes:
        header: `DftHeader` instance describing block-level metadata.
        spectra_line: List of `DopplerSpectra` instances (one per
            height/frequency sample) contained in the block.
    """

    header: DftHeader = None
    spectra_line: List[DopplerSpectra] = None

DopplerSpectra dataclass

Container for a single Doppler spectrum.

Attributes:

Name Type Description
amplitude np.array

Array-like amplitude values for the Doppler bins.
phase np.array

Array-like phase values for the Doppler bins.
Source code in pynasonde/digisonde/datatypes/dftdatatypes.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
@dataclass
class DopplerSpectra:
    """Container for a single Doppler spectrum.

    Attributes:
        amplitude: Array-like amplitude values for the Doppler bins.
        phase: Array-like phase values for the Doppler bins.
    """

    amplitude: np.array = None
    phase: np.array = None

    def __post_init__(self):
        """Apply small amplitude scaling used by the original format.

        The parser historically scales amplitude values by 3/8 to convert
        to the units expected by downstream code (historical dB-like scale).
        This operation is performed in-place on the amplitude array when
        present.
        """
        if self.amplitude is not None:
            try:
                self.amplitude *= 3 / 8  # to dB-like units (parser convention)
            except Exception:
                # If amplitude is not numeric-array-like, skip scaling.
                pass
        return

__post_init__()

Apply small amplitude scaling used by the original format.

The parser historically scales amplitude values by 3/8 to convert to the units expected by downstream code (historical dB-like scale). This operation is performed in-place on the amplitude array when present.

Source code in pynasonde/digisonde/datatypes/dftdatatypes.py 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
def __post_init__(self):
    """Apply small amplitude scaling used by the original format.

    The parser historically scales amplitude values by 3/8 to convert
    to the units expected by downstream code (historical dB-like scale).
    This operation is performed in-place on the amplitude array when
    present.
    """
    if self.amplitude is not None:
        try:
            self.amplitude *= 3 / 8  # to dB-like units (parser convention)
        except Exception:
            # If amplitude is not numeric-array-like, skip scaling.
            pass
    return

DftHeader dataclass

Top-level header for a DFT record block.

This dataclass collects the primary header fields found at the beginning of a DFT data block. Field names follow the original parser naming where possible; values are stored as integers or small numeric types and may require interpretation by the consumer (units are parser-dependent).

Attributes:

Name Type Description
record_type int

int Numeric record type identifier.
year int

int Year of the measurement.
doy int

int Day-of-year timestamp component.
hour int

int Hour of day.
minute int

int Minute component of timestamp.
second int

int Second component of timestamp.
schdule int

int (Parser-specific) schedule or run identifier.
program int

int Program id or code recorded in the header.
drift_data_flag hex

hex Drift-data flag field (raw representation).
journal hex

hex Journal / log field (raw representation).
first_height_sampling_winodw int

int First height sampling window index (raw).
height_resolution int

int Height resolution or bin size.
number_of_heights int

int Number of height bins contained in the block.
start_frequency int

int Start frequency of the scan (format-dependent units).
disk_io hex

hex Disk I/O flag or raw indicator.
freq_search_enabled bin

bin Frequency-search enabled flag (raw/bin representation).
fine_frequency_step int

int Fine frequency step value.
number_small_steps_scan_abs int

int Absolute number of small frequency steps.
number_small_steps_scan int

int Number of small steps in the scan.
start_frequency_case int

int Case-specific start frequency index.
coarse_frequency_step int

int Coarse frequency step value.
end_frequency int

int End frequency of the scan (format-dependent units).
bottom_height int

int Bottom height index or value for the block.
top_height int

int Top height index or value for the block.
unused int

int Reserved / unused field.
stn_id int

int Station identifier.
phase_code int

int Phase code or modulation identifier.
multi_antenna_sequence int

int Multi-antenna sequencing flag/identifier.
cit_length int

int CIT (control info) length field.
num_doppler_lines int

int Number of Doppler spectral lines per sample.
pulse_repeat_rate int

int Pulse repeat rate of the measurement.
waveform_type int

int Waveform type identifier.
delay int

int Inter-pulse or processing delay.
frequency_search_offset int

int Frequency search offset used during scanning.
auto_gain int

int Automatic gain control setting.
heights_to_output int

int Number of heights to output or include.
num_of_polarizations int

int Number of polarization channels recorded.
start_gain int

int Start gain setting for the receiver.
subcases List[SubCaseHeader]

List[SubCaseHeader] Optional list of SubCaseHeader entries describing per-frequency subcases within this DFT block.

Note: Many additional fields present in the original format are kept as attributes to preserve full fidelity. Consult the parser implementation for exact byte-to-field mappings.

Source code in pynasonde/digisonde/datatypes/dftdatatypes.py 
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
@dataclass
class DftHeader:
    """Top-level header for a DFT record block.

    This dataclass collects the primary header fields found at the
    beginning of a DFT data block. Field names follow the original parser
    naming where possible; values are stored as integers or small numeric
    types and may require interpretation by the consumer (units are
    parser-dependent).

    Attributes:
        record_type: int
            Numeric record type identifier.
        year: int
            Year of the measurement.
        doy: int
            Day-of-year timestamp component.
        hour: int
            Hour of day.
        minute: int
            Minute component of timestamp.
        second: int
            Second component of timestamp.
        schdule: int
            (Parser-specific) schedule or run identifier.
        program: int
            Program id or code recorded in the header.
        drift_data_flag: hex
            Drift-data flag field (raw representation).
        journal: hex
            Journal / log field (raw representation).
        first_height_sampling_winodw: int
            First height sampling window index (raw).
        height_resolution: int
            Height resolution or bin size.
        number_of_heights: int
            Number of height bins contained in the block.
        start_frequency: int
            Start frequency of the scan (format-dependent units).
        disk_io: hex
            Disk I/O flag or raw indicator.
        freq_search_enabled: bin
            Frequency-search enabled flag (raw/bin representation).
        fine_frequency_step: int
            Fine frequency step value.
        number_small_steps_scan_abs: int
            Absolute number of small frequency steps.
        number_small_steps_scan: int
            Number of small steps in the scan.
        start_frequency_case: int
            Case-specific start frequency index.
        coarse_frequency_step: int
            Coarse frequency step value.
        end_frequency: int
            End frequency of the scan (format-dependent units).
        bottom_height: int
            Bottom height index or value for the block.
        top_height: int
            Top height index or value for the block.
        unused: int
            Reserved / unused field.
        stn_id: int
            Station identifier.
        phase_code: int
            Phase code or modulation identifier.
        multi_antenna_sequence: int
            Multi-antenna sequencing flag/identifier.
        cit_length: int
            CIT (control info) length field.
        num_doppler_lines: int
            Number of Doppler spectral lines per sample.
        pulse_repeat_rate: int
            Pulse repeat rate of the measurement.
        waveform_type: int
            Waveform type identifier.
        delay: int
            Inter-pulse or processing delay.
        frequency_search_offset: int
            Frequency search offset used during scanning.
        auto_gain: int
            Automatic gain control setting.
        heights_to_output: int
            Number of heights to output or include.
        num_of_polarizations: int
            Number of polarization channels recorded.
        start_gain: int
            Start gain setting for the receiver.
        subcases: List[SubCaseHeader]
            Optional list of `SubCaseHeader` entries describing
            per-frequency subcases within this DFT block.

    Note: Many additional fields present in the original format are kept as
    attributes to preserve full fidelity. Consult the parser implementation
    for exact byte-to-field mappings.
    """

    record_type: int = None
    year: int = None
    doy: int = None
    hour: int = None
    minute: int = None
    second: int = None
    schdule: int = None
    program: int = None
    drift_data_flag: hex = None
    journal: hex = None
    first_height_sampling_winodw: int = None
    height_resolution: int = None
    number_of_heights: int = None
    start_frequency: int = None
    disk_io: hex = None
    freq_search_enabled: bin = None
    fine_frequency_step: int = None
    number_small_steps_scan_abs: int = None
    number_small_steps_scan: int = None
    start_frequency_case: int = None
    coarse_frequency_step: int = None
    end_frequency: int = None
    bottom_height: int = None
    top_height: int = None
    unused: int = None
    stn_id: int = None
    phase_code: int = None
    multi_antenna_sequence: int = None
    cit_length: int = None
    num_doppler_lines: int = None
    pulse_repeat_rate: int = None
    waveform_type: int = None
    delay: int = None
    frequency_search_offset: int = None
    auto_gain: int = None
    heights_to_output: int = None
    num_of_polarizations: int = None
    start_gain: int = None

    subcases: List[SubCaseHeader] = None

    def __post_init__(self):
        """Optional normalization after construction.

        Parsers may choose to perform small unit conversions or sanity checks
        here. The method is intentionally lightweight to avoid surprising
        side-effects during object construction.
        """
        # Example: if timestamp fields were zero-padded strings they could
        # be converted to ints here. Keep processing minimal.
        return

__post_init__()

Optional normalization after construction.

Parsers may choose to perform small unit conversions or sanity checks here. The method is intentionally lightweight to avoid surprising side-effects during object construction.

Source code in pynasonde/digisonde/datatypes/dftdatatypes.py 
189
190
191
192
193
194
195
196
197
198
def __post_init__(self):
    """Optional normalization after construction.

    Parsers may choose to perform small unit conversions or sanity checks
    here. The method is intentionally lightweight to avoid surprising
    side-effects during object construction.
    """
    # Example: if timestamp fields were zero-padded strings they could
    # be converted to ints here. Keep processing minimal.
    return

SubCaseHeader dataclass

Header for a single frequency/height subcase inside a DFT block.

Attributes:

Name Type Description
frequency int

Raw frequency value for this subcase (parser-specific units).
height_mpa int

Height value (raw units as read from the record).
height_bin int

Height bin index used for indexing spectral data.
agc_offset int

AGC offset recorded for this subcase.
polarization int

Polarization identifier for the subcase.
Source code in pynasonde/digisonde/datatypes/dftdatatypes.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
@dataclass
class SubCaseHeader:
    """Header for a single frequency/height subcase inside a DFT block.

    Attributes:
        frequency: Raw frequency value for this subcase (parser-specific
            units).
        height_mpa: Height value (raw units as read from the record).
        height_bin: Height bin index used for indexing spectral data.
        agc_offset: AGC offset recorded for this subcase.
        polarization: Polarization identifier for the subcase.
    """

    frequency: int = None
    height_mpa: int = None
    height_bin: int = None
    agc_offset: int = None
    polarization: int = None

    def __post_init__(self):
        """Post-init hook for small normalization steps.

        Parsers can populate these fields using raw binary values; if unit
        normalization or type conversions are required they should be
        applied here. The code currently contains a commented-out example of
        scaling frequency if needed.
        """
        # Example normalization (left commented because parser decides):
        # if self.frequency is not None:
        #     self.frequency = int(self.frequency * 10)
        return

__post_init__()

Post-init hook for small normalization steps.

Parsers can populate these fields using raw binary values; if unit normalization or type conversions are required they should be applied here. The code currently contains a commented-out example of scaling frequency if needed.

Source code in pynasonde/digisonde/datatypes/dftdatatypes.py 
38
39
40
41
42
43
44
45
46
47
48
49
def __post_init__(self):
    """Post-init hook for small normalization steps.

    Parsers can populate these fields using raw binary values; if unit
    normalization or type conversions are required they should be
    applied here. The code currently contains a commented-out example of
    scaling frequency if needed.
    """
    # Example normalization (left commented because parser decides):
    # if self.frequency is not None:
    #     self.frequency = int(self.frequency * 10)
    return