Metadata-Version: 2.4
Name: bsod2
Version: 0.2.1
Summary: package for reading radiosonde data
Author: So Tomita
License-Expression: GPL-3.0-only
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==2.4.3
Requires-Dist: pandas==3.0.2
Requires-Dist: metpy==1.7.1
Requires-Dist: tqdm==4.67.3
Requires-Dist: xarray==2026.4.0
Dynamic: license-file

# bsod2

<p>
<a href="https://github.com/sotomita/bsod2/actions/workflows/publish.yml"><img src="https://github.com/sotomita/bsod2/actions/workflows/publish.yml/badge.svg"></a>
<img src="https://img.shields.io/pypi/dm/bsod2.svg?label=PyPI%20downloads">
<img src="https://img.shields.io/github/license/sotomita/bsod2">
<img src="https://img.shields.io/badge/-Python-gray.svg?logo=Python">
</p>

BSoD2(BalloonScope on Deck 2) is a package in Python for reading radiosonde data.

## Requirements
- numpy == 2.4.3
- pandas == 3.0.2
- xarray == 2026.4.0
- metpy == 1.7.1
- tqdm == 4.67.3

## Installation
This package can be installed from [PyPI](https://pypi.org/project/bsod2/).
```
pip install bsod2
```

## Usage
The only functionality provided by this package is the `bsod2.Sondeset` class, which retrieves radiosonde data and performs quality control.

### Basic `Sondeset` construction and methods

Initialize the class with the file path to the raw data.
```
from pathlib import Path
from bsod2 import Sondeset

ss = Sondeset(Path("Seisuimaru2407/raw_data/F2024061806S1101771.CSV"))
print(ss)
>>> N=1, sonde_no=["1101771"]
```

If a directory path is given, all sonde data files (`F*S*.CSV`) in that directory are loaded.
```
ss = Sondeset(Path("Seisuimaru2407/raw_data"))
print(ss)
>>> N=8, sonde_no=["1101771", "1101323", "1101386", "1101322", "1101327", "1101772", "1101388", "1101326"]
```

Individual data items can be accessed by indexing.
```
print(ss[0])
>>> Sonde(sonde_no=1101771, launch_time=2024-06-18 06:01:42, product_name=iMS-100 , num_records=4174)
```

### Accessors for individual data items
The following accessors can be used to access individual data items.   
Most accessors return values with `metpy.units.units` attached.

| Accessor | units | Description | Example |
|----------|-------------|---------| ---------|
|`df`|`NOne`| quality-controlled `pandas.DataFrame`|`ss[0].df`|
|`time`|`None`|Time|`ss[0].time`|
|`lat`|`units("deg")`| Latitude|`ss[0].lat`|
|`lon`|`units("deg")`| Longitude|`ss[0].lon`|
|`x`|`units("m")`| X-displacement from the launch point|`ss[0].x`|
|`y`|`units("m")`| Y-displacement from the launch point|`ss[0].y`|
|`z`| ```units("m")```  | Altitude | `ss[0].z` |
|`p`| ```units("hPa")```  | Pressure | `ss[0].p` |
|`t`| ```units("degC")```| Temperature | `ss[0].temp` |
|`rh`|```units("percents")```| Relative humidity | `ss[0].rh` |
|`wd`|```units("deg")```| Wind direction | `ss[0].wd` |
|`ws`| ```units("m/s")```| Wind speed | `ss[0].ws` |


### Save as CSV
Save the quality-controlled DataFrame as a CSV file to the specified file path using the `save_df` method.
```
ss[0].save_df(Path("output.csv"))
```

### Altitude or pressure interpolation
Interpolate linearly onto an evenly spaced grid in pressure(`"p"`) or altitude(`"z"`) using the `interp` argument.
```
ss = Sondeset(DIR_PATH,interp="p")
```
By default, the interpolated pressure axis ranges from 50 to 1,100 hPa at 1 hPa intervals, or the height axis ranges from 0 m to 20,000 m at 10 m intervals.   
Values outside the original data range are filled with NaN. The range and resolution of the interpolation axes can be specified using the following arguments.

| Argument| Description                                                                 | Default |
|---------------|-----------------------------------------------------------------------------|---------|
| `interp`      | Name of the interpolation axis. If None, interpolation is not performed.    | None    |
| `interp_pmin` | Minimum value of the interpolated pressure axis (hPa)                       | 50     |
| `interp_pmax` | Maximum value of the interpolated pressure axis (hPa)                       | 1100    |
| `interp_dp`   | Step size of the interpolated pressure axis (hPa)                           | 1       |
| `interp_zmin` | Minimum value of the interpolated height axis (m)                           | 0       |
| `interp_zmax` | Maximum value of the interpolated height axis (m)                           | 20000   |
| `interp_dz`   | Step size of the interpolated height axis (m)                               | 10      |

### Interpolated and combined `xarray.Dataset`
`Sondeset.ds` provides access to an `xarray.Dataset` containing interpolated and combined radiosonde data.
```
ss = Sondeset(Path("Seisuimaru2407/raw_data", interp="z"))
ss.ds
>>> 
xarray.Dataset> Size: 785kB
Dimensions:      (n: 8, z: 2001)
Coordinates:
  * n            (n) <U7 224B '1101771' '1101323' ... '1101388' '1101326'
  * z            (z) float64 16kB 0.0 10.0 20.0 ... 1.998e+04 1.999e+04 2e+04
Data variables:
    p            (n, z) float64 128kB nan 1.007e+03 1.005e+03 ... nan nan nan
    tmp          (n, z) float64 128kB nan 18.76 18.93 19.0 ... nan nan nan nan
    wd           (n, z) float64 128kB nan 270.4 252.9 250.7 ... nan nan nan nan
    ws           (n, z) float64 128kB nan 2.426 2.09 2.16 ... nan nan nan nan
    rh           (n, z) float64 128kB nan 89.21 89.78 90.21 ... nan nan nan nan
    launch_time  (n) datetime64[us] 64B 2024-06-18T06:01:42 ... 2024-06-18T14...
    time         (n, z) datetime64[ns] 128kB 2024-06-18T06:01:42 ... 2024-06-...
```

## Sample scrips

See [sample/sample.md](sample/sample.md) for sample scripts.


## License
This project is distributed under the terms of the GNU General Public License, Version 3 (GPLv3).  
See the [LICENSE](LICENSE) file for details.
