Skip to content

Commit f713c29

Browse files
BrianMichellBrianMichell
committed
Update template, streamline grid override, add+enhance docs
1 parent 0d2ae00 commit f713c29

9 files changed

Lines changed: 304 additions & 80 deletions

File tree

‎docs/guides/grid_overrides.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Grid Overrides
2+
3+
```{warning}
4+
🚧👷🏻 We are actively working on updating the documentation and adding missing features to v1 release. Please check back later for more updates!
5+
```
6+
7+
Grid overrides are transformations applied during SEG-Y import that modify how trace headers are interpreted and indexed. They handle complex acquisition geometries that cannot be represented by simple header-to-dimension mappings.
8+
9+
## Overview
10+
11+
When importing SEG-Y data, MDIO maps trace header fields to dataset dimensions. However, real-world seismic data often has complexities that require additional processing. Grid overrides address these issues by transforming header values before indexing.
12+
13+
## CalculateShotIndex
14+
15+
Calculates a dense `shot_index` dimension from sparse or interleaved `shot_point` values. Required for the `ObnReceiverGathers3D` template.
16+
17+
**Supported Templates:** `ObnReceiverGathers3D`
18+
19+
**Required Headers:** `shot_line`, `gun`, `shot_point`
20+
21+
**How it works:**
22+
23+
In multi-gun OBN acquisition, shot points are often interleaved across guns:
24+
25+
```
26+
Before (interleaved shot_point):
27+
Gun 1: 1, 3, 5, 7, ...
28+
Gun 2: 2, 4, 6, 8, ...
29+
30+
After (dense shot_index):
31+
Gun 1: 0, 1, 2, 3, ...
32+
Gun 2: 0, 1, 2, 3, ...
33+
```
34+
35+
The override detects the geometry type and only applies the transformation when shot points are actually interleaved (Type B geometry). For non-interleaved data (Type A), shot points are used directly.
36+
37+
**Usage:**
38+
39+
```python
40+
segy_to_mdio(
41+
input_path="obn_data.sgy",
42+
output_path="obn_data.mdio",
43+
segy_spec=obn_spec,
44+
mdio_template=get_template("ObnReceiverGathers3D"),
45+
grid_overrides={"CalculateShotIndex": True},
46+
)
47+
```
48+
49+
```{note}
50+
See [OBN Data Import](obn_data_import.md) for a complete guide on importing OBN data.
51+
```
52+
53+
## Special Behaviors
54+
55+
Some templates have special behaviors that are applied automatically during import, independent of grid overrides.
56+
57+
### Component Synthesis (OBN)
58+
59+
When using the `ObnReceiverGathers3D` template, if the SEG-Y specification does not include a `component` field, MDIO automatically synthesizes it with value `1` for all traces. This allows single-component data (e.g., hydrophone-only) to use the same template without modification.
60+
61+
```{note}
62+
A warning is logged when component is synthesized:
63+
64+
> SEG-Y headers do not contain 'component' field required by template 'ObnReceiverGathers3D'.
65+
> Synthesizing 'component' dimension with constant value 1 for all traces.
66+
```
67+
68+
## Error Handling
69+
70+
Grid overrides validate their requirements and raise specific exceptions:
71+
72+
| Exception | Cause |
73+
| --------- | ----- |
74+
| `GridOverrideUnknownError` | Unknown override name passed |
75+
| `GridOverrideKeysError` | Required header fields missing |
76+
| `GridOverrideMissingParameterError` | Required parameters not provided |
77+
| `GridOverrideIncompatibleError` | Override incompatible with template |
78+
79+
**Example error message:**
80+
81+
```
82+
GridOverrideKeysError: Grid override 'CalculateShotIndex' requires keys: {'shot_line', 'gun', 'shot_point'}
83+
```
84+
85+
## See Also
86+
87+
- [OBN Data Import](obn_data_import.md) - Complete guide for OBN data
88+
- [Template Registry](../template_registry.md) - Available templates
89+
- [Tutorials](../tutorials/index.md) - Hands-on guides

‎docs/guides/index.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Guides
2+
3+
Welcome to the MDIO guides. This section provides in-depth documentation on advanced features and specialized workflows.
4+
5+
## Topics
6+
7+
```{toctree}
8+
:maxdepth: 1
9+
:titlesonly:
10+
11+
grid_overrides
12+
obn_data_import
13+
```
14+
15+
## Overview
16+
17+
### Grid Overrides
18+
19+
Grid overrides are transformations applied during SEG-Y import that modify how trace headers are interpreted and indexed. They handle complex acquisition geometries like multi-gun acquisition with interleaved shot points.
20+
21+
See [Grid Overrides](grid_overrides.md) for documentation.
22+
23+
### OBN Data Import
24+
25+
Ocean Bottom Node (OBN) data has unique characteristics requiring specialized handling. The OBN guide covers:
26+
27+
- The `ObnReceiverGathers3D` template
28+
- Required grid overrides for OBN
29+
- Component synthesis for single-component data
30+
31+
See [OBN Data Import](obn_data_import.md) for the complete guide.

docs/obn_data_import.md renamed to docs/guides/obn_data_import.md

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,14 @@ This guide covers the `ObnReceiverGathers3D` template for importing Ocean Bottom
66

77
The `ObnReceiverGathers3D` template organizes data with the following dimensions:
88

9-
| Dimension | Description |
10-
| -------------- | ---------------------------------------------------------------------------------- |
11-
| `component` | Sensor component (e.g., 1=X, 2=Y, 3=Z, 4=Hydrophone) |
12-
| `receiver` | Ocean bottom node receiver ID |
13-
| `shot_line` | Shot line identifier |
14-
| `gun` | Gun identifier for multi-gun sources |
15-
| `shot_index` | Calculated dense index for shots (see [AutoShotWrap](#autoshotwrap-grid-override)) |
16-
| `time`/`depth` | Vertical sample axis |
9+
| Dimension | Description |
10+
| -------------- | ----------------------------------------------------------------------------------------- |
11+
| `component` | Sensor component (e.g., 1=X, 2=Y, 3=Z, 4=Hydrophone) |
12+
| `receiver` | Ocean bottom node receiver ID |
13+
| `shot_line` | Shot line identifier |
14+
| `gun` | Gun identifier for multi-gun sources |
15+
| `shot_index` | Calculated dense index for shots (see [Required Grid Overrides](#required-grid-overrides)) |
16+
| `time`/`depth` | Vertical sample axis |
1717

1818
### Coordinates
1919

@@ -24,11 +24,15 @@ The `ObnReceiverGathers3D` template organizes data with the following dimensions
2424
The `shot_index` dimension is calculated (0 to N-1) from `shot_point` values during ingestion. Original `shot_point` values are preserved as a coordinate indexed by `(shot_line, gun, shot_index)`.
2525
```
2626

27-
## Special Behaviors
27+
## Required Grid Overrides
28+
29+
### CalculateShotIndex (Required)
30+
31+
The `CalculateShotIndex` grid override is **required** for the `ObnReceiverGathers3D` template. It calculates the `shot_index` dimension from `shot_point` values. Without this override, the import will fail with an error:
2832

29-
### AutoShotWrap Grid Override
33+
> Required computed fields ['shot_index'] for template ObnReceiverGathers3D not found after grid overrides.
3034
31-
The `AutoShotWrap` grid override handles multi-gun acquisition where shot points are interleaved across guns. It calculates a dense `shot_index` from sparse `shot_point` values:
35+
This override handles multi-gun acquisition where shot points are interleaved across guns, calculating a dense `shot_index` from sparse `shot_point` values:
3236

3337
```
3438
Before (interleaved shot_point):
@@ -42,6 +46,8 @@ After (dense shot_index):
4246

4347
For `ObnReceiverGathers3D`, the override uses `shot_line` as the line field and requires `shot_line`, `gun`, and `shot_point` headers.
4448

49+
## Special Behaviors
50+
4551
### Component Synthesis
4652

4753
When the SEG-Y spec does not include a `component` field, MDIO automatically synthesizes it with value `1` for all traces. This allows single-component data (e.g., hydrophone-only) to use the same template without modification.
@@ -85,7 +91,7 @@ segy_to_mdio(
8591
output_path="obn_data.mdio",
8692
segy_spec=obn_spec,
8793
mdio_template=get_template("ObnReceiverGathers3D"),
88-
grid_overrides={"AutoShotWrap": True},
94+
grid_overrides={"CalculateShotIndex": True},
8995
overwrite=True,
9096
)
9197
```
@@ -148,5 +154,6 @@ receiver_gather["amplitude"].plot()
148154

149155
## See Also
150156

151-
- [Template Registry](template_registry.md)
152-
- [Quickstart Tutorial](tutorials/quickstart.ipynb)
157+
- [Grid Overrides](grid_overrides.md) - All available grid overrides
158+
- [Template Registry](../template_registry.md)
159+
- [Quickstart Tutorial](../tutorials/quickstart.ipynb)

‎docs/index.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,16 @@ configuration
2424
:caption: Learning and Support
2525
2626
tutorials/index
27-
obn_data_import
2827
api_reference
2928
```
3029

30+
```{toctree}
31+
:hidden:
32+
:caption: Guides
33+
34+
guides/index
35+
```
36+
3137
```{toctree}
3238
:hidden:
3339
:caption: Core Concepts and Structures

‎src/mdio/builder/templates/seismic_3d_obn.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ def __init__(self, data_domain: SeismicDataDomain = "time"):
4040
"source_coord_y",
4141
)
4242
self._logical_coord_names = ("shot_point", "orig_field_record_num")
43-
self._var_chunk_shape = (1, 1, 1, 3, 128, 4096)
43+
self._var_chunk_shape = (1, 1, 1, 1, 512, 4096)
4444

4545
@property
4646
def _name(self) -> str:

0 commit comments

Comments
 (0)