### Initialize Level0File and Access Data

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/index.md

Quick start example to initialize a Level0File object and access packet metadata, ephemeris, and I/Q data for a specific acquisition chunk.

```python
import sentinel1decoder

l0file = sentinel1decoder.Level0File(filename)

# Packet metadata (indexed by acquisition chunk and packet number)
l0file.packet_metadata

# Ephemeris from sub-commutated auxiliary data
l0file.ephemeris

# Decode I/Q data for an acquisition chunk
iq_data = l0file.get_acquisition_chunk_data(0)
```

--------------------------------

### Install sentinel1decoder Package

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/README.md

Install the sentinel1decoder package using pip. Requires Python 3.8+, NumPy, and Pandas.

```bash
pip install sentinel1decoder
```

--------------------------------

### Quick Start: Decode Sentinel-1 Level 0 Data

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/README.md

Instantiate a Level0File object with the filename and access packet metadata, ephemeris, or decode I/Q data for a specific acquisition chunk.

```python
import sentinel1decoder

l0file = sentinel1decoder.Level0File(filename)
l0file.packet_metadata   # packet metadata
l0file.ephemeris        # satellite ephemeris
iq_data = l0file.get_acquisition_chunk_data(0)  # decode I/Q for acquisition chunk 0
```

--------------------------------

### Initialize Level0File

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/classes.md

Instantiate the Level0File class by providing the path to the Sentinel-1 Level 0 file. This action automatically decodes packet metadata upon construction.

```python
from sentinel1decoder import Level0File

l0file = Level0File(filename)
```

--------------------------------

### Initialize Level0Decoder

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/classes.md

Instantiate the Level0Decoder with the path to a Sentinel-1 Level 0 file. This is the first step to accessing the file's data.

```python
from sentinel1decoder import Level0Decoder

decoder = Level0Decoder(filename)
```

--------------------------------

### Level0Decoder Initialization

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/classes.md

Initialize the Level0Decoder with the path to the Sentinel-1 Level 0 file.

```APIDOC
## Initialization

### Description
Initializes the Level0Decoder with the path to the Level 0 file.

### Parameters
#### Path Parameters
- **filename** (str) - Required - Path to the Level 0 file
```

--------------------------------

### Iterate Matching Acquisition Chunks

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/classes.md

Yields acquisition chunk IDs that match all specified criteria. This is useful for filtering chunks based on parameters like signal type, swath number, or BAQ mode.

```python
for chunk in l0file.iter_chunks_matching(signal_type=SignalType.ECHO): ...
```

--------------------------------

### Level0File Class Overview

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/classes.md

The Level0File class provides a high-level interface to Sentinel-1 Level 0 files. It automatically decodes packet metadata and groups packets into acquisition chunks.

```APIDOC
## Class: Level0File

### Description
High-level interface to a Sentinel-1 Level 0 file. Automatically decodes packet metadata on construction and groups packets into acquisition chunks.

### Properties

- `filename` (str): Path to the Level 0 file
- `packet_metadata` (pd.DataFrame): Metadata for all packets, indexed by acquisition chunk and packet number. Parsed representation.
- `raw_packet_metadata` (pd.DataFrame): Same metadata in raw form (spec-style names, integer codes). Computed on first access.
- `ephemeris` (pd.DataFrame): Sub-commutated satellite ephemeris; computed on first access
- `acquisition_chunks` (list[int]): List of acquisition chunk IDs (0-indexed) in the file

### Methods

- **`get_acquisition_chunk_metadata(acquisition_chunk: int)`** 
  Metadata for all packets in the given acquisition chunk.

- **`get_acquisition_chunk_constants(acquisition_chunk: int)`** 
  Returns a dict of the parameters that define an acquisition chunk (i.e. those that stay constant within a chunk): `signal_type`, `swath_num`, `num_quads`, `baq_mode`, `swst`, `swl`, `pri`, `elevation_beam_address`. Values are taken from the first packet in the chunk.

- **`iter_chunks_matching(**kwargs)`** 
  Yield acquisition chunk IDs whose constants match all given criteria. Each keyword is one of the chunk-defining parameters; the value is compared to the constant for that chunk (from the first packet). Supported keywords and expected types:
    - `signal_type` (SignalType)
    - `swath_num` (int)
    - `num_quads` (int)
    - `baq_mode` (BaqMode)
    - `swst` (float)
    - `swl` (float)
    - `pri` (float)
    - `elevation_beam_address` (int)
  Example: `for chunk in l0file.iter_chunks_matching(signal_type=SignalType.ECHO): ...`

- **`get_acquisition_chunk_data(acquisition_chunk: int, try_load_from_file: bool = True)`** 
  Complex I/Q samples for the acquisition chunk, shape `(num_packets, num_samples)`, dtype `complex64` (two float32 per sample). By default, attempts to load from a cached `.npy` file if present.

- **`save_acquisition_chunk_data(acquisition_chunk: int)`** 
  Save decoded I/Q data to a `.npy` file for faster subsequent loads. The cache file is written next to the source Level 0 file, with the same base path and the suffix `_acquisition_chunk_{id}.npy`.
```

--------------------------------

### Sample rate conversion

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/utilities.md

Converts a range decimation code to the sample rate in Hz.

```APIDOC
## range_dec_to_sample_rate

### Description
Convert a range decimation code (integer or `RangeDecimation` enum) to the sample rate in Hz.

### Method
`sentinel1decoder.utilities.range_dec_to_sample_rate(rgdec: int | RangeDecimation)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- `float`: The sample rate in Hz.

#### Response Example
None
```

--------------------------------

### Column renaming utilities

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/utilities.md

Functions to convert between raw and parsed metadata column names in a pandas DataFrame.

```APIDOC
## rename_packet_metadata_columns_to_raw

### Description
Rename parsed column names to raw (spec-style) names. Only renames columns that are present and have a raw counterpart. No-op if already raw. Does not convert any column data types, *only* renames the columns.

### Method
`sentinel1decoder.utilities.rename_packet_metadata_columns_to_raw(df: pd.DataFrame)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- `pd.DataFrame`: DataFrame with renamed columns.

#### Response Example
None
```

```APIDOC
## rename_packet_metadata_columns_to_parsed

### Description
Rename raw column names to human-readable parsed names. Only renames columns that are present and have a parsed counterpart. No-op if already parsed. Does not convert any column data types, only renames the columns.

### Method
`sentinel1decoder.utilities.rename_packet_metadata_columns_to_parsed(df: pd.DataFrame)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- `pd.DataFrame`: DataFrame with renamed columns.

#### Response Example
None
```

--------------------------------

### decode_packets

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/classes.md

Decodes radar echoes from specified packets using a batch processing approach.

```APIDOC
## decode_packets

### Description
Decode radar echoes from the packets whose headers are in `input_header`. The DataFrame must have the structure returned by `decode_metadata()` or `Level0File.packet_metadata`. Returns a complex array of shape `(num_packets, num_samples)` with dtype `complex64`. Supports bypass and FDBAQ modes; BAQ 3/4/5-bit modes are not implemented.

`batch_size` controls how many packets are sent to the Rust decoder at once. Within each batch, packets are decoded in parallel (multithreaded). Larger batches increase parallelism and throughput but use more memory; smaller batches reduce memory at the cost of some efficiency. Default 256 is a reasonable balance.

Not thread-safe: do not call `decode_packets` on the same `Level0Decoder` instance from multiple threads concurrently. Use a separate decoder per thread if decoding in parallel.

### Parameters
#### Request Body
- **input_header** (pd.DataFrame) - Required - DataFrame containing packet headers. Must have the structure returned by `decode_metadata()` or `Level0File.packet_metadata`.
- **batch_size** (int) - Optional - Default: 256. Controls how many packets are processed in parallel.

### Response
#### Success Response (200)
- **np.ndarray** - A complex array of shape `(num_packets, num_samples)` with dtype `complex64` representing the decoded radar echoes.
```

--------------------------------

### decode_metadata

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/classes.md

Decodes the secondary header of each packet. Can return raw or parsed data.

```APIDOC
## decode_metadata

### Description
Decode the secondary header of each packet. When `return_raw=False` (default), integer codes are parsed into enums, scaled floats, etc.; when `return_raw=True`, raw spec-style column names and integer codes are returned unchanged. The packet data field consists of a 62-byte secondary header followed by the payload.

### Parameters
#### Query Parameters
- **return_raw** (bool) - Optional - Default: False. If True, returns raw spec-style column names and integer codes; otherwise, parses into enums, scaled floats, etc.

### Response
#### Success Response (200)
- **pd.DataFrame** - DataFrame containing decoded packet metadata.
```

--------------------------------

### Ephemeris data decoding

Source: https://github.com/rich-hall/sentinel1decoder/blob/main/docs/api/utilities.md

Decodes the ephemeris portion of sub-commutated ancillary data from packet headers.

```APIDOC
## read_subcommed_data

### Description
Decode the ephemeris portion of the sub-commutated ancillary data from the packet headers. Does not decode the full 64-word sub-commutated block; only position, velocity, quaternions, angular rates, and timestamps are extracted. Expects a DataFrame of packet metadata (e.g. from `decode_metadata()` or `Level0File.packet_metadata`).

### Method
`sentinel1decoder.utilities.read_subcommed_data(df: pd.DataFrame)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- `pd.DataFrame`: DataFrame containing decoded ephemeris data.

#### Response Example
None
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.