RDEFpy 1.0.0__tar.gz

rdefpy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Morehead State University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rdefpy-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include src/rdefpy/prd/unpack_cyth.pyx
+recursive-include tests *.py *.prd *.obs *.hdr *.tab *.hex *.dc *.agency *.md
+recursive-include examples *.py

rdefpy-1.0.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: RDEFpy
+Version: 1.0.0
+Summary: Reader and writer for the CCSDS Delta-DOR Raw Data Exchange Format (RDEF, CCSDS 506.1-B-1).
+Author-email: Andrea Togni <antogni@moreheadstate.edu>
+License-Expression: MIT
+Project-URL: Documentation, https://rdefpy.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/atogni/RDEFpy
+Project-URL: Issues, https://github.com/atogni/RDEFpy/issues
+Keywords: CCSDS,RDEF,Delta-DOR,DSN,radio science,open-loop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Cython
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Provides-Extra: browse
+Requires-Dist: matplotlib>=3.8; extra == "browse"
+Dynamic: license-file
+
+# RDEFpy
+
+[![Documentation Status](https://readthedocs.org/projects/rdefpy/badge/?version=latest)](https://rdefpy.readthedocs.io/en/latest/)
+
+Open-source Python reader and writer for the product files of the CCSDS
+Delta-DOR Raw Data Exchange Format (RDEF), CCSDS 506.1-B-1 (June 2013), also
+published as ISO 20208:2015. It covers the standard's §5: binary one-second
+records of complex I/Q with full downconversion metadata, as recorded by
+open-loop receivers for radio science and Delta-DOR. The standard's ASCII
+observation files (§4) are read and validated; writing them, and checks
+across files (§4.2.4 version, §6.2 file names), are not supported.
+
+**Documentation: https://rdefpy.readthedocs.io/en/latest/** (user guide,
+examples, API reference).
+
+## Introduction
+
+Open-loop recordings of spacecraft signals serve radio-science experiments,
+radiometric tracking and Delta-DOR (delta differential one-way ranging), a
+navigation technique derived from very long baseline interferometry (VLBI).
+The Consultative Committee for Space Data Systems (CCSDS) defines a common
+format for these recordings, the Delta-DOR Raw Data Exchange Format (RDEF):
+one-second binary records of complex in-phase/quadrature (I/Q) samples with
+their downconversion metadata, required when stations of different agencies
+share an observation. To our knowledge no licensed open-source library reads
+and writes RDEF, so each station or research group builds and validates its
+own; VLBI stations, which record in the VLBI Data Interchange Format (VDIF),
+face this before joining a navigation campaign. RDEFpy is a Python reader and
+writer for RDEF product files that depends on NumPy alone and decodes every
+sample size the standard defines, with tests pinning each against the
+standard's bit layout. On a laptop workstation it read recordings about
+72,000 times faster than real time for 1-kHz, 16-bit data (6 h), about 3,100
+times for 100-kHz, 16-bit data (2 h, 2.9 GB), and about 9 times for 100-MHz,
+2-bit wideband data (60 s, 3.0 GB). Records above 1 kHz stay on disk until
+accessed, so memory stays bounded on multi-gigabyte files. Stations and
+research groups can produce and consume RDEF without in-house format
+software, and a VLBI station can add it to a VDIF-based workflow without
+changing its recording or correlation pipeline.
+
+## Features
+
+- Reads and writes RDEF product files (`.prd`).
+- Decodes every record header field and the I/Q samples of all supported sample sizes.
+- Handles multi-gigabyte files: records at or below 1 kHz are loaded;
+  faster records stay on disk and are read on access, one at a time.
+- Extracts the carrier frequency before downconversion per integration
+  time: fractional Fourier transform plus Successive Parabolic
+  Interpolation (Togni et al., 2025, Signal Processing 237, 110094).
+  Blocks run in parallel within a memory budget (`memory_limit`, by default
+  half of the memory the process can still take), counted at about 400 bytes per block sample.
+- Depends on NumPy alone. An optional Cython extension speeds up I/Q
+  unpacking and carrier extraction; without a compiler the package falls
+  back to an equivalent NumPy path.
+
+## Installation
+
+RDEFpy needs Python 3.11 or later and NumPy.
+
+From PyPI:
+
+```
+pip install rdefpy
+```
+
+The prebuilt wheels include the compiled Cython extension. Where no wheel
+matches your platform, pip builds from source as below.
+
+The record browser (`rdefpy.browse`) also needs matplotlib:
+
+```
+pip install "rdefpy[browse]"
+```
+
+From GitHub, latest version:
+
+```
+pip install git+https://github.com/atogni/RDEFpy
+```
+
+or from a clone (add `-e` for an editable install when developing):
+
+```
+git clone https://github.com/atogni/RDEFpy
+cd RDEFpy
+pip install .
+```
+
+A source build compiles the optional Cython extension, which needs a C compiler:
+Microsoft C++ Build Tools on Windows, `gcc` on Linux (e.g. `build-essential`),
+or the Xcode command-line tools on macOS (`xcode-select --install`). Without
+one the build prints a warning and installs the NumPy path only. To check
+that the extension was built:
+
+```
+python -c "import rdefpy.prd.unpack_cyth"
+```
+
+No error means it is in use.
+
+## Quick start
+
+```python
+from rdefpy import read_product, write_product
+
+pf = read_product("scan.prd")  # records above 1 kHz stay on disk until accessed
+pf.info()                      # file summary: time span, rate, bits, band
+print(pf[0])                   # first record: header fields
+
+for rec in pf:                 # one one-second record at a time
+    x = rec.data.samples       # complex I + jQ, NumPy array
+    print(rec.header.timetag, rec.data.power_db)
+
+buf = None                     # faster at high rates: decode straight to complex
+for rec in pf:                 # and refill one array (copy anything you keep)
+    buf = rec.read_samples(out=buf)
+
+x = pf.samples[:1024]                    # any sample range, across records
+t = pf.timetags[:1024]                   # datetime64[ns] of each sample
+f = pf.downconversion_frequency[:1024]   # Hz, at each sample (§5.2.6)
+phi = pf.downconversion_phase[:1024]     # turns, variable part (§5.2.6.2)
+f0 = pf.record_downconversion_frequency  # Hz, at each record's first sample
+f_mean = pf.mean_downconversion_frequency  # Hz, mean over each record
+
+from rdefpy import extract_carrier       # FrFT + SPI, samples untouched
+c = extract_carrier(pf, integration_time=1.0, max_rate_hz_s=10.0)
+c["time"], c["frequency_before_downconversion"]           # one row per block; time = block midpoint
+
+part = pf.select(start_epoch="2026-02-08T12:00:00", stop_epoch="2026-02-08T12:00:10")
+write_product("part.prd", part)
+```
+
+An observation file (`.obs`) lists the product files of each scan:
+
+```python
+from rdefpy import read_observation, read_product
+
+for scan in read_observation("session.obs"):
+    for entry in scan.products:
+        pf = read_product(entry.datafile)
+```
+
+More in the [quick start](https://rdefpy.readthedocs.io/en/latest/quickstart.html)
+and the [user guide](https://rdefpy.readthedocs.io/en/latest/).
+
+## Performance
+
+Time to read a file and decode every sample to integer I/Q, by sample size,
+sample rate and recording duration. Median of 10 runs, files in the OS
+cache, 2026-11-06. Intel Core Ultra 9 285HX laptop (24 cores, 64 GB RAM),
+Windows 11, Python 3.15.0, NumPy 2.5.4, RDEFpy at commit c7b5e55 with the
+Cython extension, 16 threads.
+
+![Decode time per file](https://raw.githubusercontent.com/atogni/RDEFpy/main/docs/realtime.png)
+
+The same measurement for four typical files, with and without the compiled
+Cython extension (without it RDEFpy falls back to pure NumPy). Median of 10
+runs, same machine and versions, RDEFpy at commit 1e7991f.
+
+![Cython vs pure NumPy](https://raw.githubusercontent.com/atogni/RDEFpy/main/docs/cases.png)
+
+The ratios in the introduction come from the IVS GM2026 poster benchmark
+(Cython back-end).
+
+## Testing
+
+```
+uv run python -m pytest
+```
+
+The tests pin the low-level decoding for every sample size against the
+standard's bit layout.
+
+`tests/reference/` holds small synthetic product files with their expected
+decoding as text (headers, samples, hex dump, downconversion, DSN 0222
+agency block), written from a plain transcription of the standard, not from
+RDEFpy. Use them to check another decoder: see
+[Checking another decoder](https://rdefpy.readthedocs.io/en/latest/reference_files.html).
+
+## Contributing
+
+Issues and pull requests are welcome. The low-level decoding (the `2k+1`
+transform of §5.3.6, the bit offsets, the header struct) is the format itself
+and is meant to stay as it is; changes there need a reference to the standard.
+Performance improvements in decoding, reading, or processing data are welcome.
+
+## Publications using RDEFpy
+
+- Togni, A., Malphrus, B., Arnold, B., Mayo, D., Sanchez-Net, M., & Asmar, S.
+  (2026). Extending VLBI Station Capabilities for Delta-DOR and Navigation via
+  Open-Source RDEF Software Compliant with CCSDS Standards. Poster, 14th
+  General Meeting of the International VLBI Service for Geodesy and Astrometry
+  (IVS GM2026), Würzburg.
+  https://indico.astro.uni-wuerzburg.de/event/2/contributions/143/
+
+## License
+
+MIT. See `LICENSE`.

rdefpy-1.0.0/README.md

@@ -0,0 +1,197 @@
+# RDEFpy
+
+[![Documentation Status](https://readthedocs.org/projects/rdefpy/badge/?version=latest)](https://rdefpy.readthedocs.io/en/latest/)
+
+Open-source Python reader and writer for the product files of the CCSDS
+Delta-DOR Raw Data Exchange Format (RDEF), CCSDS 506.1-B-1 (June 2013), also
+published as ISO 20208:2015. It covers the standard's §5: binary one-second
+records of complex I/Q with full downconversion metadata, as recorded by
+open-loop receivers for radio science and Delta-DOR. The standard's ASCII
+observation files (§4) are read and validated; writing them, and checks
+across files (§4.2.4 version, §6.2 file names), are not supported.
+
+**Documentation: https://rdefpy.readthedocs.io/en/latest/** (user guide,
+examples, API reference).
+
+## Introduction
+
+Open-loop recordings of spacecraft signals serve radio-science experiments,
+radiometric tracking and Delta-DOR (delta differential one-way ranging), a
+navigation technique derived from very long baseline interferometry (VLBI).
+The Consultative Committee for Space Data Systems (CCSDS) defines a common
+format for these recordings, the Delta-DOR Raw Data Exchange Format (RDEF):
+one-second binary records of complex in-phase/quadrature (I/Q) samples with
+their downconversion metadata, required when stations of different agencies
+share an observation. To our knowledge no licensed open-source library reads
+and writes RDEF, so each station or research group builds and validates its
+own; VLBI stations, which record in the VLBI Data Interchange Format (VDIF),
+face this before joining a navigation campaign. RDEFpy is a Python reader and
+writer for RDEF product files that depends on NumPy alone and decodes every
+sample size the standard defines, with tests pinning each against the
+standard's bit layout. On a laptop workstation it read recordings about
+72,000 times faster than real time for 1-kHz, 16-bit data (6 h), about 3,100
+times for 100-kHz, 16-bit data (2 h, 2.9 GB), and about 9 times for 100-MHz,
+2-bit wideband data (60 s, 3.0 GB). Records above 1 kHz stay on disk until
+accessed, so memory stays bounded on multi-gigabyte files. Stations and
+research groups can produce and consume RDEF without in-house format
+software, and a VLBI station can add it to a VDIF-based workflow without
+changing its recording or correlation pipeline.
+
+## Features
+
+- Reads and writes RDEF product files (`.prd`).
+- Decodes every record header field and the I/Q samples of all supported sample sizes.
+- Handles multi-gigabyte files: records at or below 1 kHz are loaded;
+  faster records stay on disk and are read on access, one at a time.
+- Extracts the carrier frequency before downconversion per integration
+  time: fractional Fourier transform plus Successive Parabolic
+  Interpolation (Togni et al., 2025, Signal Processing 237, 110094).
+  Blocks run in parallel within a memory budget (`memory_limit`, by default
+  half of the memory the process can still take), counted at about 400 bytes per block sample.
+- Depends on NumPy alone. An optional Cython extension speeds up I/Q
+  unpacking and carrier extraction; without a compiler the package falls
+  back to an equivalent NumPy path.
+
+## Installation
+
+RDEFpy needs Python 3.11 or later and NumPy.
+
+From PyPI:
+
+```
+pip install rdefpy
+```
+
+The prebuilt wheels include the compiled Cython extension. Where no wheel
+matches your platform, pip builds from source as below.
+
+The record browser (`rdefpy.browse`) also needs matplotlib:
+
+```
+pip install "rdefpy[browse]"
+```
+
+From GitHub, latest version:
+
+```
+pip install git+https://github.com/atogni/RDEFpy
+```
+
+or from a clone (add `-e` for an editable install when developing):
+
+```
+git clone https://github.com/atogni/RDEFpy
+cd RDEFpy
+pip install .
+```
+
+A source build compiles the optional Cython extension, which needs a C compiler:
+Microsoft C++ Build Tools on Windows, `gcc` on Linux (e.g. `build-essential`),
+or the Xcode command-line tools on macOS (`xcode-select --install`). Without
+one the build prints a warning and installs the NumPy path only. To check
+that the extension was built:
+
+```
+python -c "import rdefpy.prd.unpack_cyth"
+```
+
+No error means it is in use.
+
+## Quick start
+
+```python
+from rdefpy import read_product, write_product
+
+pf = read_product("scan.prd")  # records above 1 kHz stay on disk until accessed
+pf.info()                      # file summary: time span, rate, bits, band
+print(pf[0])                   # first record: header fields
+
+for rec in pf:                 # one one-second record at a time
+    x = rec.data.samples       # complex I + jQ, NumPy array
+    print(rec.header.timetag, rec.data.power_db)
+
+buf = None                     # faster at high rates: decode straight to complex
+for rec in pf:                 # and refill one array (copy anything you keep)
+    buf = rec.read_samples(out=buf)
+
+x = pf.samples[:1024]                    # any sample range, across records
+t = pf.timetags[:1024]                   # datetime64[ns] of each sample
+f = pf.downconversion_frequency[:1024]   # Hz, at each sample (§5.2.6)
+phi = pf.downconversion_phase[:1024]     # turns, variable part (§5.2.6.2)
+f0 = pf.record_downconversion_frequency  # Hz, at each record's first sample
+f_mean = pf.mean_downconversion_frequency  # Hz, mean over each record
+
+from rdefpy import extract_carrier       # FrFT + SPI, samples untouched
+c = extract_carrier(pf, integration_time=1.0, max_rate_hz_s=10.0)
+c["time"], c["frequency_before_downconversion"]           # one row per block; time = block midpoint
+
+part = pf.select(start_epoch="2026-02-08T12:00:00", stop_epoch="2026-02-08T12:00:10")
+write_product("part.prd", part)
+```
+
+An observation file (`.obs`) lists the product files of each scan:
+
+```python
+from rdefpy import read_observation, read_product
+
+for scan in read_observation("session.obs"):
+    for entry in scan.products:
+        pf = read_product(entry.datafile)
+```
+
+More in the [quick start](https://rdefpy.readthedocs.io/en/latest/quickstart.html)
+and the [user guide](https://rdefpy.readthedocs.io/en/latest/).
+
+## Performance
+
+Time to read a file and decode every sample to integer I/Q, by sample size,
+sample rate and recording duration. Median of 10 runs, files in the OS
+cache, 2026-11-06. Intel Core Ultra 9 285HX laptop (24 cores, 64 GB RAM),
+Windows 11, Python 3.15.0, NumPy 2.5.4, RDEFpy at commit c7b5e55 with the
+Cython extension, 16 threads.
+
+![Decode time per file](https://raw.githubusercontent.com/atogni/RDEFpy/main/docs/realtime.png)
+
+The same measurement for four typical files, with and without the compiled
+Cython extension (without it RDEFpy falls back to pure NumPy). Median of 10
+runs, same machine and versions, RDEFpy at commit 1e7991f.
+
+![Cython vs pure NumPy](https://raw.githubusercontent.com/atogni/RDEFpy/main/docs/cases.png)
+
+The ratios in the introduction come from the IVS GM2026 poster benchmark
+(Cython back-end).
+
+## Testing
+
+```
+uv run python -m pytest
+```
+
+The tests pin the low-level decoding for every sample size against the
+standard's bit layout.
+
+`tests/reference/` holds small synthetic product files with their expected
+decoding as text (headers, samples, hex dump, downconversion, DSN 0222
+agency block), written from a plain transcription of the standard, not from
+RDEFpy. Use them to check another decoder: see
+[Checking another decoder](https://rdefpy.readthedocs.io/en/latest/reference_files.html).
+
+## Contributing
+
+Issues and pull requests are welcome. The low-level decoding (the `2k+1`
+transform of §5.3.6, the bit offsets, the header struct) is the format itself
+and is meant to stay as it is; changes there need a reference to the standard.
+Performance improvements in decoding, reading, or processing data are welcome.
+
+## Publications using RDEFpy
+
+- Togni, A., Malphrus, B., Arnold, B., Mayo, D., Sanchez-Net, M., & Asmar, S.
+  (2026). Extending VLBI Station Capabilities for Delta-DOR and Navigation via
+  Open-Source RDEF Software Compliant with CCSDS Standards. Poster, 14th
+  General Meeting of the International VLBI Service for Geodesy and Astrometry
+  (IVS GM2026), Würzburg.
+  https://indico.astro.uni-wuerzburg.de/event/2/contributions/143/
+
+## License
+
+MIT. See `LICENSE`.

rdefpy-1.0.0/examples/carrier_synthetic.py

@@ -0,0 +1,48 @@
+"""Extract the carrier frequency of a synthetic tone file, and compare with the truth.
+
+Builds three one-second records of a complex tone with a known baseband frequency,
+quantized to the 2k+1 codes of 16-bit samples (§5.3.6), writes them to a temporary
+product file and runs extract_carrier on it.
+
+    python examples/carrier_synthetic.py
+"""
+
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+from rdefpy import (
+    ProductFile, Record, RecordData, RecordHeader, extract_carrier, read_product, write_product,
+)
+
+FS = 1000
+F_TONE = 123.4567  # baseband frequency [Hz]
+FIXED = 8.4e9 + 5.0e6  # rf_to_if + if_to_channel downconversion [Hz]
+
+pf = ProductFile(name="synthetic")
+for s in range(3):
+    t = s + np.arange(FS) / FS
+    phase = 2 * np.pi * F_TONE * t
+    # 2k+1 values: odd integers, here 2*floor(v/2) + 1
+    i, q = (2 * np.floor(12000 * f(phase) / 2).astype(int) + 1 for f in (np.cos, np.sin))
+    header = RecordHeader(dict(
+        record_version_id=1, station_id=24, spacecraft_id=1,
+        sample_size=16, sample_rate=FS, validity_flag=0, agency_flag=0,
+        rf_to_if_downconv=8.4e9, if_to_channel_downconv=5.0e6,
+        time_tag_year=2026, time_tag_doy=39, time_tag_second_of_day=43200 + s,
+        time_tag_picoseconds_of_the_second=0.0, channel_accumulated_phase=0.0,
+        channel_phase_polynomial_coefficient_0=0.0, channel_phase_polynomial_coefficient_1=0.0,
+        channel_phase_polynomial_coefficient_2=0.0, channel_phase_polynomial_coefficient_3=0.0,
+    ))
+    pf.records.append(Record(header, RecordData(16, FS, i, q)))
+
+with tempfile.TemporaryDirectory() as tmp:
+    path = Path(tmp) / "tone.prd"
+    write_product(path, pf)
+    c = extract_carrier(read_product(path), integration_time=1.0, max_rate_hz_s=0.0)
+
+truth = FIXED + F_TONE
+print(f"truth frequency before downconversion {truth:.6f} Hz (baseband {F_TONE} Hz)")
+for time, f, base in zip(c["time"], c["frequency_before_downconversion"], c["frequency"]):
+    print(f"{time}  before DC {f:.6f} Hz  error {(f - truth) * 1e3:+.3f} mHz  baseband {base:.6f} Hz")

rdefpy-1.0.0/examples/downconversion.py

@@ -0,0 +1,47 @@
+"""Downconversion frequency and phase of a product file (§5.2.6).
+
+    python examples/downconversion.py
+"""
+
+from pathlib import Path
+
+import numpy as np
+
+from rdefpy import read_product
+
+np.set_printoptions(formatter={"float": "{:.3f}".format})
+data = Path(__file__).parents[1] / "tests" / "data"
+pf = read_product(data / "EXMPn001tSsDS24r01c01-26039120000.prd")
+fs = pf[0].header.sample_rate
+
+# The file has a fixed downconversion: all phase coefficients are zero.
+print("per-record [Hz]:", pf.record_downconversion_frequency)
+
+# Give the headers one frequency ramp, f_var = C1 + 2*C2*t from the first record's
+# start (headers only, the samples are untouched). Each record continues it from its
+# own start t = n s: c1 is the frequency there, and the phase reached so far is split
+# into whole turns (channel_accumulated_phase) and the fraction c0, so phase and
+# frequency are continuous from record to record (Table 5-1).
+C1, C2 = 100.0, -3.0  # turns/s, turns/s^2
+steered = pf.copy()
+for n, rec in enumerate(steered):
+    turns = C1 * n + C2 * n**2  # phase at the start of record n
+    rec.correct_header(
+        channel_accumulated_phase=float(np.floor(turns)),
+        channel_phase_polynomial_coefficient_0=float(turns - np.floor(turns)),
+        channel_phase_polynomial_coefficient_1=C1 + 2 * C2 * n,
+        channel_phase_polynomial_coefficient_2=C2,
+    )
+
+print("first sample [Hz]:", steered.record_downconversion_frequency)
+print("record mean  [Hz]:", steered.mean_downconversion_frequency)
+print("phase at first sample [turns]:", steered.record_downconversion_phase)
+
+# Per sample, across the record boundary: continuous.
+print("per-sample [Hz]:   ", steered.downconversion_frequency[fs - 1 : fs + 1])
+print("per-sample [turns]:", steered.downconversion_phase[fs - 1 : fs + 1])
+
+# Tag each mean at its record midpoint, t0 + T/2 (not the mean of the sample times).
+half = np.timedelta64(500_000_000, "ns")  # one-second records
+for rec, f in zip(steered, steered.mean_downconversion_frequency):
+    print(f"{rec.header.timetag + half}  {f:.3f} Hz")

rdefpy-1.0.0/examples/read_observation.py

@@ -0,0 +1,19 @@
+"""Read an RDEF observation file and the product files it lists.
+
+    python examples/read_observation.py
+"""
+
+from pathlib import Path
+
+from rdefpy import read_observation, read_product
+
+data = Path(__file__).parents[1] / "tests" / "data"
+obs = read_observation(data / "EXMPn000tIsDS24r01c00-26039120000.obs")
+print(obs)
+
+for scan in obs:
+    print()
+    print(scan)
+    for entry in scan.products:
+        print()
+        print(read_product(entry.datafile))

rdefpy-1.0.0/examples/read_product_summary.py

@@ -0,0 +1,19 @@
+"""Summarise an RDEF product file: file info, first record header, power per record.
+
+    python examples/read_product_summary.py
+"""
+
+from pathlib import Path
+
+from rdefpy import read_product
+
+data = Path(__file__).parents[1] / "tests" / "data"
+pf = read_product(data / "EXMPn001tSsDS24r01c01-26039120000.prd")
+
+pf.info()
+print()
+print(pf[0].header)
+
+for i, rec in enumerate(pf):
+    d = rec.data  # take it once: each access of an unloaded record may re-read the disk
+    print(f"record {i}: {rec.header.timetag}  {len(d)} samples  {d.power_db:.2f} dB  rms {d.rms:.1f}")

rdefpy-1.0.0/examples/samples_and_timetags.py

@@ -0,0 +1,31 @@
+"""Read samples across records: slices of pf.samples and pf.timetags, and a record loop.
+
+    python examples/samples_and_timetags.py
+"""
+
+from pathlib import Path
+
+import numpy as np
+
+from rdefpy import read_product
+
+data = Path(__file__).parents[1] / "tests" / "data"
+pf = read_product(data / "EXMPn001tSsDS24r01c01-26039120000.prd")
+fs = pf[0].header.sample_rate
+
+# A slice that crosses the boundary between record 0 and record 1.
+x = pf.samples[fs - 3 : fs + 3]
+t = pf.timetags[fs - 3 : fs + 3]
+for ti, xi in zip(t, x):
+    print(ti, xi)
+
+# Record by record, decoding straight into one reused complex buffer.
+buf = None
+total = 0.0
+for rec in pf:
+    buf = rec.read_samples(out=buf)
+    total += np.sum(np.abs(buf) ** 2)
+print(f"mean power {10 * np.log10(total / (len(pf) * fs)):.2f} dB")
+
+whole = pf.samples[:]
+print("loop matches pf.samples:", np.isclose(total, np.sum(np.abs(whole) ** 2)))

rdefpy-1.0.0/examples/select_and_write.py

@@ -0,0 +1,29 @@
+"""Select a time window of a product file, write it, and read it back.
+
+    python examples/select_and_write.py
+"""
+
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+from rdefpy import read_product, write_product
+
+data = Path(__file__).parents[1] / "tests" / "data"
+pf = read_product(data / "EXMPn001tSsDS24r01c01-26039120000.prd")
+fs = pf[0].header.sample_rate
+
+part = pf.select(start_epoch="2026-02-08T12:00:01", stop_epoch="2026-02-08T12:00:02")
+print(f"{len(pf)} records -> {len(part)} selected, first at {part[0].header.timetag}")
+
+with tempfile.TemporaryDirectory() as tmp:
+    out = Path(tmp) / "part.prd"
+    write_product(out, part)
+    back = read_product(out)
+    print(f"written {out.stat().st_size} bytes, read back {len(back)} record")
+    print("samples equal:", np.array_equal(back.samples[:], pf.samples[fs:]))  # the second record
+
+    # A selection of every record is byte-identical to the original file.
+    write_product(out, pf.select())
+    print("bytes equal:", out.read_bytes() == pf.path.read_bytes())