Metadata-Version: 2.4
Name: pybrams
Version: 0.1.5
Summary: BRAMS project Python package
Author-email: Antoine Calegaro <antoine.calegaro@aeronomie.be>, Joachim Balis <joachim.balis@aeronomie.be>, Hugo Joly <hugo.joly@aeronomie.be>
License-Expression: MIT
Project-URL: homepage, https://brams.aeronomie.be
Project-URL: repository, https://gitlab.aeronomie.be/ae/brams/pybrams
Project-URL: documentation, https://gitlab.aeronomie.be/ae/brams/pybrams
Keywords: brams,meteor
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: KDEpy
Requires-Dist: matplotlib
Requires-Dist: pykml
Requires-Dist: requests
Requires-Dist: scipy
Requires-Dist: scikit-image
Requires-Dist: dill
Requires-Dist: tqdm
Requires-Dist: rich
Requires-Dist: pypng
Requires-Dist: freetype-py
Requires-Dist: ipython
Requires-Dist: pyproj
Requires-Dist: jax
Requires-Dist: ipympl
Dynamic: license-file

# PyBRAMS

![PyBRAMS logo](https://brams.aeronomie.be/files/pybrams.png)
**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](#features)
- [Installation](#installation)
- [Usage](#usage)
  - [Command-line tool](#command-line-tool)
    - [Available commands](#available-commands)
      - [get](#get)
      - [cache](#cache)
      - [config](#config)
      - [spectrogram](#spectrogram)
      - [wavinfo](#wavinfo)
      - [optical](#optical)
      - [availability](#availability)
      - [psd](#psd)
- [Contributing](#contributing)
- [License](#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](https://docs.astral.sh/uv/),
which makes the installation in an isolated virtual environment to prevent conflicts with other packages:

```bash
uv venv
uv pip install pybrams
```

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

On Unix-like receivers :

```bash
source .venv/bin/activate
```

On Windows (Powershell)

```Powershell
.venv\Scripts\Activate.ps1
```

On Windows (CMD)

```bat
.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 :

```bash
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 list` command displays a table of all available BRAMS locations.

```bash
$ pybrams location list
            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 list` command displays a table of all available BRAMS receivers.

```bash
$ pybrams receiver list
            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.

```bash
pybrams get INTERVAL [receiverS...]
```

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

- a single datetime  in ISO 8601 format :

```bash
pybrams get 2025-01-01T03:05
```

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

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

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

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

##### cache

PyBRAMS uses a caching receiver to store metadata, WAV files and result files in a local directory.
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

```bash
$ pybrams cache status
Cache is enabled
```

- enabling or disabling the cache

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

- clearing the cache

```bash
$ pybrams cache clear
Cache was cleared
```

- get information about the cache

```bash
$ pybrams cache info
Number of files : 385
Total size : 1811688538 B
Total size : 1769227.09 KB
Total size : 1727.76 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 :

```bash
$ 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 :

```bash
pybrams config copy
```

This creates a pybrams.json file in the current working 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 :

```bash
$ 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 :

```bash
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.

```bash
$ 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 :

```bash
$ 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.

```bash
$ 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 :

```bash
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 :

```bash
$ 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` :

```bash
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 :

```bash
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:

```bash
$ 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) :

 ```bash
$ 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 │
└────────────────────────────────────────────┴────────────────────────┘
```

&nbsp;
***

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

```bash
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.
