PyBRAMS

PyBRAMS is a Python package that allows you to access information and data from the BRAMS (Belgian RAdio Meteor Stations) project.

BRAMS is a network of radar receiving stations that use forward scattering techniques to study the meteoroid population.

This project, coordinated by the Belgian Institute for Space Aeronomy (BIRA-IASB), provides a valuable source of data for space operators, research scientists and amateur astronomers.

Contents

• Features
• Installation
• Usage
  • Command-line tool
    • Available commands
      • get
      • cache
      • config
      • spectrogram
      • wavinfo
      • optical
      • availability
      • psd
• Contributing
• License

Features

• Fetch detailed information about BRAMS stations, including their location, name, number of antennas, and more.
• Retrieve raw data files in WAV format, which can be used for in-depth analysis of meteoroid activity.
• Access PNG images representing spectrograms, making it easy to visualize meteoroid detections.
• Compute trajectories, speeds and their associated uncertainties.
• Allow validation of results with optical data.

Installation

We recommend installing PyBRAMS using uv, which makes the installation in an isolated virtual environment to prevent conflicts with other packages:

uv venv
uv pip install pybrams

To use PyBRAMS, you then need to activate the virtual environment.

On Unix-like receivers :

source .venv/bin/activate

On Windows (Powershell)

.venv\Scripts\Activate.ps1

On Windows (CMD)

.venv\Scripts\Activate.bat

Usage

This library can be used in two ways:

• As a command-line tool for quick execution.
• As a Python module for integration into custom scripts.

Command-line tool

The library provides an executable script called pybrams, which can be run from the terminal :

pybrams [options] [command]

Available options

--verbose

Some commands may take a significant amount of time to execute. The --verbose option provides detailed output and displays real-time progress.

Available commands

location

The location command displays a table of all available BRAMS locations.

$ pybrams location
            BRAMS locations             
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Location code ┃     Display name     ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│    BEBILZ     │        Bilzen        │
│    BEBOEC     │       Boechout       │
│    BEBROE     │       Broechem       │
│    BEDINA     │        Dinant        │
│    BEECON     │       Ecotron        │
│    BEFRAM     │      Frameries       │
│    BEGAVE     │        Gavere        │
│    BEGEMB     │        Gembes        │
│    BEGENK     │         Genk         │
│    BEGENT     │         Gent         │
│    BEGRIM     │      Grimbergen      │
│    [ ...]     │        [ ...]        │
└───────────────┴──────────────────────┘

receiver

The receiver command displays a table of all available BRAMS receivers.

$ pybrams receiver
            BRAMS receivers
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃  Receiver code┃     Display name     ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ BEBILZ_SYS001 │        Bilzen        │
│ BEBOEC_SYS001 │       Boechout       │
│ BEBROE_SYS001 │       Broechem       │
│ BEDINA_SYS001 │        Dinant        │
│ BEECON_SYS001 │      Ecotron 1       │
│ BEECON_SYS002 │      Ecotron 2       │
│ BEECON_SYS003 │      Ecotron 3       │
│ BEECON_SYS004 │      Ecotron 4       │
│ BEECON_SYS005 │      Ecotron 5       │
│ BEFRAM_SYS001 │      Frameries       │
│ BEGAVE_SYS001 │        Gavere        │
│    [ ...]     │        [ ...]        │
└───────────────┴──────────────────────┘

get

The get command fetches BRAMS files in WAV format and saves them in the current working directory.

pybrams get INTERVAL [receiverS...]

The INTERVAL argument must be in one of the following format :

• a single datetime in ISO 8601 format :

pybrams get 2025-01-01T03:05

• a datetime interval using ISO 8601 format, separated by / :

pybrams get 2025-02-12T03:03/2025-02-12T03:17

• a human-readable string (yesterday, last_hour, last_day or last_week) :

pybrams get yesterday

You can also provide one or multiple receiver codes to only fetch files from specific BRAMS receiver(s) :

pybrams get 2025-03-15T12:00 BESAFF_SYS001 BEHUMA_SYS001

cache

PyBRAMS uses a caching receiver to store metadata, WAV files and result files. The cache directory location depends on the OS. This improve performance by avoiding redundant calls to the BRAMS API and computations.

The cache commands allow the user to manage this cache by :

• checking the current status of the cache

$ pybrams cache status
Cache is enabled

• enabling or disabling the cache

$ pybrams cache disable
Cache is disabled
$ pybrams cache enable
Cache is enabled

• clearing the cache

$ pybrams cache clear
Cache was cleared

• get information about the cache

$ pybrams cache info
Number of files : 385
Total size : 1811688538 B
Total size : 1769227.09 KB
Total size : 1727.76 MB

• inspecting the content of the cache

$ pybrams cache inspect
 Cache Inspection                                                                              
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Cache File / Key                                                      ┃ Type / Source        ┃ Details / Payload Decryption                                   ┃     Size ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ 650fda52a51c54f72c39fcb434555bcf2c2ed71fc101c20437e763f1386b2e3b.json │ API Response         │ location.php (location_code=BEECON)                            │    235 B │
│ 81f87953dd10d4ec33757638dab8c2c41384986371af40175e014ba6bdf14d44.json │ API Response         │ receiver.php (receiver_code=BEECON_SYS001)                     │    311 B │
│ dc8331b816725bed95c4cf679560af5da583f493f8e9ea3950d85f25c03c2a0d.json │ Raw File             │ dc8331b816725bed95c4cf679560af5da583f493f8e9ea3950d85f25c03c2… │ 36.64 KB │
│ e7744b0eb6b8c155f5e689187f802a5736b8cdf2a4d56fea26963c43b2b37b42.json │ Raw File             │ e7744b0eb6b8c155f5e689187f802a5736b8cdf2a4d56fea26963c43b2b37… │ 22.32 KB │
│ RAD_BEDOUR_20260721_2355_BEECON_SYS001.wav                            │ Raw Signal           │ RAD_BEDOUR_20260721_2355_BEECON_SYS001.wav                     │  3.49 MB │
│ RAD_BEDOUR_20260722_0000_BEECON_SYS001.wav                            │ Raw Signal           │ RAD_BEDOUR_20260722_0000_BEECON_SYS001.wav                     │  3.49 MB │
│ RAD_BEDOUR_20260722_0005_BEECON_SYS001.wav                            │ Raw Signal           │ RAD_BEDOUR_20260722_0005_BEECON_SYS001.wav                     │  3.49 MB │
│ RAD_BEDOUR_20260722_0010_BEECON_SYS001.wav                            │ Raw Signal           │ RAD_BEDOUR_20260722_0010_BEECON_SYS001.wav                     │  3.49 MB │
│ RAD_BEDOUR_20260722_0015_BEECON_SYS001.wav                            │ Raw Signal           │ RAD_BEDOUR_20260722_0015_BEECON_SYS001.wav                     │  3.49 MB │
│ RAD_BEDOUR_20260722_0020_BEECON_SYS001.wav                            │ Raw Signal           │ RAD_BEDOUR_20260722_0020_BEECON_SYS001.wav                     │  3.49 MB │
│ RAD_BEDOUR_20260722_0025_BEECON_SYS001.wav                            │ Raw Signal           │ RAD_BEDOUR_20260722_0025_BEECON_SYS001.wav                     │  3.49 MB │
│ RAD_BEDOUR_20260722_0030_BEECON_SYS001.wav                            │ Raw Signal           │ RAD_BEDOUR_20260722_0030_BEECON_SYS001.wav                     │  3.49 MB │

config

PyBRAMS uses a global configuration file to manage settings. The config command allows users to view the current configuration or copy it to the current working directory for customization.

To display the global configuration used by PyBRAMS, run :

$ pybrams config show
PyBRAMS Configuration
└── pybrams
    ├── brams
    │   ├── adsb
    │   │   └── api_endpoint
    │   │       └── 'adsb.php'
    │   ├── fetch
    │   │   ├── api
    │   │   │   └── base_url
    │   │   │       └── 'https://brams.aeronomie.be/v1/'
    │   │   └── archive
    │   │       └── base_path
    │   │           └── '/bira-iasb/data/GROUNDBASED/BRAMS/wav'
    │   ├── file
    │   │   └── api_endpoint
    │   │       └── 'file.php'
    │   ├── location
    │   │   └── api_endpoint
    │   │       └── 'location.php'
    │   └── receiver
    │       └── api_endpoint
    │           └── 'receiver.php'
    ├── event
    │   └── meteor
    │       ├── identification_half_range_frequency
    │       │   └── 100
    │       ├── filtering_half_range_frequency
    │       │   └── 300
    │       ├── filtering_length_kernel
    │       │   └── 2501
    [...]

If you want to modify the settings, you can copy the global configuration file to the current working directory by running :

pybrams config copy

This creates a pybrams.json file in the default configuration directory, which you can edit to override the default settings. When present, this file takes precedence over the global configuration.

You can also get or set a single entry from the global configuration by using these subcommands :

$ pybrams config get pybrams.processing.signal calibrator_subtraction
False
$ pybrams config set pybrams.processing.signal airplane_subtraction True

If you need to restore the default global configuration, you can use this command :

pybrams config restore

spectrogram

The spectrogram command generates spectrograms from WAV files found in the current working directory or in the path specified by the user.

$ ls -1 *.wav
RAD_BEDOUR_20240729_2305_BESAFF_SYS001.wav
RAD_BEDOUR_20240729_2310_BESAFF_SYS001.wav
RAD_BEDOUR_20240729_2315_BESAFF_SYS001.wav
RAD_BEDOUR_20240729_2320_BESAFF_SYS001.wav
RAD_BEDOUR_20240729_2325_BESAFF_SYS001.wav
$ pybrams spectrogram
RAD_BEDOUR_20240729_2310_BESAFF_SYS001.png
RAD_BEDOUR_20240729_2305_BESAFF_SYS001.png
RAD_BEDOUR_20240729_2315_BESAFF_SYS001.png
RAD_BEDOUR_20240729_2320_BESAFF_SYS001.png
RAD_BEDOUR_20240729_2325_BESAFF_SYS001.png

wavinfo

The wavinfo command displays information about the WAV file provided by the user.

By default, the command displays information found in the header of the file :

$ pybrams wavinfo RAD_BEDOUR_20240729_2310_BESAFF_SYS001.wav
Header
Version : 4
Samplerate : 6048.0 Hz
LO frequency : 49969000.0 Hz
Start (us) : 1722294600326662
PPS count : 1800
Beacon latitude : 50.097526
Beacon longitude : 4.588525
Beacon altitude : 273.3 m
Beacon frequency : 49970000.0 Hz
Beacon power : 84.9
Beacon polarization : 3
Antenna ID : 1
Antenna latitude : 50.784132
Antenna longitude : 5.233545
Antenna altitude : 1
Antenna azimuth : 1
Antenna elevation : 1
Beacon code : BEDOUR
Observer code : 
Station code : BESAFF
Description : Calclock

optical

The optical command validates BRAMS trajectory reconstructions against optical meteor observations. For a given optical event, it looks for the corresponding echoes in the BRAMS data, reconstructs the trajectory from them, and compares the result with the optical solution.

Two optical networks are supported:

• CAMS (Cameras for Allsky Meteor Surveillance), whose curated trajectories are bundled with PyBRAMS.
• GMN (Global Meteor Network), whose daily trajectories are fetched online.

Each network exposes a list subcommand to browse the available trajectories and a trajectory subcommand to run the validation.

CAMS

The optical cams list command displays all bundled CAMS trajectories.

$ pybrams optical CAMS list
                          CAMS trajectories                           
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Trajectory ID ┃ Trajectory Number ┃ Observed Date ┃ Reference Time ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│    CAMS_1     │        79         │  29/07/2020   │  23:14:00.43   │
│    CAMS_2     │        105        │  29/07/2020   │  23:36:27.99   │
│    CAMS_3     │        188        │  30/07/2020   │  00:51:27.48   │
│    CAMS_4     │        477        │  30/07/2020   │  22:07:59.00   │
│    CAMS_5     │        532        │  30/07/2020   │  23:03:22.61   │
│    [ ... ]    │      [ ... ]      │    [ ... ]    │    [ ... ]     │
└───────────────┴───────────────────┴───────────────┴────────────────┘

Each trajectory is identified by its Trajectory ID (e.g. CAMS_3). Add the --json option to cache the raw JSON instead of printing the table.

Pass that ID to the trajectory subcommand to reconstruct and validate it :

pybrams optical cams trajectory CAMS_3

GMN

The optical gmn list command displays the suitable GMN trajectories observed on a given day. The date must be in DAY/MONTH/YEAR format :

$ pybrams optical gmn list 30/07/2020
             GMN trajectories on 30/07/2020             
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Trajectory Number ┃          Reference Time          ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│         0         │ 2020-07-30T00:51:27.480000+00:00 │
│         1         │ 2020-07-30T22:07:59.000000+00:00 │
│         2         │ 2020-07-30T23:03:22.610000+00:00 │
└───────────────────┴──────────────────────────────────┘

Run the validation by providing the same date and the trajectory number shown by list :

pybrams optical gmn trajectory 30/07/2020 0

Options

Both trajectory subcommands accept the following options :

• --deceleration_model to choose the kinematic model used for the retrieval. Available models are Constant (default), Linear, InvLinear, InvExp and InvExp2.
• --recompute_echoes to ignore cached echoes and recompute them from the raw signals.

Combine them with the global --verbose option to log the reconstructed BRAMS trajectory alongside the optical one :

pybrams --verbose optical cams trajectory CAMS_3 --deceleration_model Linear

availability

The availability command retrieves information about the availability of BRAMS or ADS-B data. It can be called with the brams or adsb subcommand and a corresponding datetime interval:

$ pybrams availability adsb 2025-06-01/2025-06-09
  Availability from 2025-06-01  
  00:00:00+00:00 to 2025-06-09  
         00:00:00+00:00         
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ ADSB Receiver ┃ Availability ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ BEUCCL        │ ████████     │
└───────────────┴──────────────┘
$ pybrams availability brams 2025-06-01/2025-06-03
     Availability from 2025-06-01 00:00:00+00:00 to 2025-06-03      
                           00:00:00+00:00                           
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Receiver        ┃ Availability                                     ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ BEBILZ_SYS001 │ ████████████████████████████████████████████████ │
├───────────────┼──────────────────────────────────────────────────┤
│ LUKIRC_SYS001 │ ████████████████████████████████████████████████ │
├───────────────┼──────────────────────────────────────────────────┤
│ NLMAAS_SYS001 │ ████████████████████████████████████████████████ │
└───────────────┴──────────────────────────────────────────────────┘
[ ... ]

psd

The psd command computes the calibrator or noise power spectral density for files in a datetime interval and for the specified receiver(s) :

$ pybrams psd calibrator 2025-08-01/2025-08-10 BEMAAM_SYS001
                           Calibrator PSD                             
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                    File                    ┃          PSD           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RAD_BEDOUR_20250731_2355_BEMAAM_SYS001.wav │ 2.304543733506049e-08  │
│ RAD_BEDOUR_20250801_0000_BEMAAM_SYS001.wav │ 2.3073969355195496e-08 │
│ RAD_BEDOUR_20250801_0005_BEMAAM_SYS001.wav │ 2.3108002900549175e-08 │
│ RAD_BEDOUR_20250801_0010_BEMAAM_SYS001.wav │ 2.3149156546909356e-08 │
└────────────────────────────────────────────┴────────────────────────┘

 

---

For more information about a specific command and available arguments, run :

pybrams <command> --help

Contributing

Contributions and feedback are welcome !

License

This package is licensed under the MIT License. Feel free to use and modify it as needed.