API Reference

SEG-Y File

class segy.SegyFile(url, spec=None, settings=None)

A SEG-Y file class that has various accessors.

Parameters:

• url (str) – Path to SEG-Y file on disk or remote store.

• spec (SegyDescriptor | None) – The schema / spec describing the SEG-Y file. This is optional and by default it will try to infer the SEG-Y standard from the binary header.

• settings (SegyFileSettings | None) – A settings instance to configure / override the SEG-Y parsing logic. Optional.

property binary_header: HeaderArray

Read binary header from store, based on spec.

property file_size: int

Return file size in bytes.

property header: HeaderIndexer

Way to access the file to fetch trace headers only.

property num_ext_text: int

Return number of extended text headers.

property num_traces: int

Return number of traces in file based on size and spec.

property sample: AbstractIndexer

Way to access the file to fetch trace data only.

property sample_interval: int

Return samples interval in file based on spec.

property sample_labels: NDArray[np.int32]

Return sample axis labels.

property samples_per_trace: int

Return samples per trace in file based on spec.

property text_header: str

Return textual file header.

property trace: TraceIndexer

Way to access the file to fetch full traces (headers + data).

SEG-Y Factory

class segy.SegyFactory(spec, sample_interval=4000, samples_per_trace=1500)

Factory class for composing SEG-Y by components.

Parameters:

• spec (SegyDescriptor) – SEG-Y specification.

• sample_interval (int) – Sample interval to use in new file.

• samples_per_trace (int) – Number of samples per trace.

create_binary_header()

Create a binary header for the SEG-Y file.

Returns:

Bytes containing the encoded binary header, ready to write.

Return type:

bytes

create_textual_header(text=None)

Create a textual header for the SEG-Y file.

The length of the text should match the rows and columns in the spec’s TextHeaderDescriptor. The newlines must also be in the text to separate the rows.

Parameters:

text (str | None) – String containing text header rows. If left as None, a default textual header will be created.

Returns:

Bytes containing the encoded text header, ready to write.

Return type:

bytes

create_trace_header_template(size=1)

Create a trace header template array that conforms to the SEG-Y spec.

Parameters:

size (int) – Number of headers for the template.

Returns:

Array containing the trace header template.

Return type:

NDArray[Any]

create_trace_sample_template(size=1)

Create a trace data template array that conforms to the SEG-Y spec.

Parameters:

size (int) – Number of traces for the template.

Returns:

Array containing the trace data template.

Return type:

NDArray[Any]

create_traces(headers, samples)

Convert trace data and header to bytes conforming to SEG-Y spec.

The rows (length) of the headers and traces must match. The headers must be a (num_traces,) shape array and data must be a (num_traces, num_samples) shape array. They can be created via the create_trace_header_template and create_trace_sample_template methods.

Parameters:

• headers (NDArray[Any]) – Header array.

• samples (NDArray[Any]) – Data array.

Returns:

Bytes containing the encoded traces, ready to write.

Raises:

• AttributeError – if data dimensions are wrong (not 2D trace,samples).

• ValueError – if there is a shape mismatch between headers.

• ValueError – if there is a shape mismatch number of samples.

Return type:

bytes

property segy_revision: SegyStandard | None

Revision of the SEG-Y file.

property trace_sample_format: ScalarType

Trace sample format of the SEG-Y file.

Configuration

pydantic settings segy.config.SegyFileSettings

SEG-Y file parsing settings.

Show JSON schema

{
   "title": "SegyFileSettings",
   "description": "SEG-Y file parsing settings.",
   "type": "object",
   "properties": {
      "binary": {
         "$ref": "#/$defs/SegyBinaryHeaderSettings"
      },
      "endianness": {
         "allOf": [
            {
               "$ref": "#/$defs/Endianness"
            }
         ],
         "default": "big"
      },
      "revision": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Revision"
      },
      "storage_options": {
         "title": "Storage Options",
         "type": "object"
      },
      "apply_transforms": {
         "default": true,
         "title": "Apply Transforms",
         "type": "boolean"
      }
   },
   "$defs": {
      "Endianness": {
         "description": "Enumeration class with three possible endianness values.\n\nExamples:\n    >>> endian = Endianness.BIG\n    >>> print(endian.symbol)\n    >",
         "enum": [
            "big",
            "little",
            "native"
         ],
         "title": "Endianness",
         "type": "string"
      },
      "ExtendedTextHeaderSetting": {
         "description": "Configuration for extended textual headers parsing.",
         "properties": {
            "key": {
               "default": "extended_textual_headers",
               "title": "Key",
               "type": "string"
            },
            "value": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Value"
            }
         },
         "title": "ExtendedTextHeaderSetting",
         "type": "object"
      },
      "SampleIntervalSetting": {
         "description": "Configuration for samples interval parsing.",
         "properties": {
            "key": {
               "default": "sample_interval",
               "title": "Key",
               "type": "string"
            },
            "value": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Value"
            }
         },
         "title": "SampleIntervalSetting",
         "type": "object"
      },
      "SamplesPerTraceSetting": {
         "description": "Configuration for samples per trace parsing.",
         "properties": {
            "key": {
               "default": "samples_per_trace",
               "title": "Key",
               "type": "string"
            },
            "value": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Value"
            }
         },
         "title": "SamplesPerTraceSetting",
         "type": "object"
      },
      "SegyBinaryHeaderSettings": {
         "description": "SEG-Y binary header parsing settings.",
         "properties": {
            "samples_per_trace": {
               "allOf": [
                  {
                     "$ref": "#/$defs/SamplesPerTraceSetting"
                  }
               ],
               "default": {
                  "key": "samples_per_trace",
                  "value": null
               }
            },
            "sample_interval": {
               "allOf": [
                  {
                     "$ref": "#/$defs/SampleIntervalSetting"
                  }
               ],
               "default": {
                  "key": "sample_interval",
                  "value": null
               }
            },
            "extended_text_header": {
               "allOf": [
                  {
                     "$ref": "#/$defs/ExtendedTextHeaderSetting"
                  }
               ],
               "default": {
                  "key": "extended_textual_headers",
                  "value": null
               }
            }
         },
         "title": "SegyBinaryHeaderSettings",
         "type": "object"
      }
   }
}

field binary: SegyBinaryHeaderSettings [Optional]

field endianness: Endianness = Endianness.BIG

field revision: int | float | None = None

field storage_options: dict[str, Any] [Optional]

field apply_transforms: bool = True

pydantic settings segy.config.SegyBinaryHeaderSettings

SEG-Y binary header parsing settings.

Show JSON schema

{
   "title": "SegyBinaryHeaderSettings",
   "description": "SEG-Y binary header parsing settings.",
   "type": "object",
   "properties": {
      "samples_per_trace": {
         "allOf": [
            {
               "$ref": "#/$defs/SamplesPerTraceSetting"
            }
         ],
         "default": {
            "key": "samples_per_trace",
            "value": null
         }
      },
      "sample_interval": {
         "allOf": [
            {
               "$ref": "#/$defs/SampleIntervalSetting"
            }
         ],
         "default": {
            "key": "sample_interval",
            "value": null
         }
      },
      "extended_text_header": {
         "allOf": [
            {
               "$ref": "#/$defs/ExtendedTextHeaderSetting"
            }
         ],
         "default": {
            "key": "extended_textual_headers",
            "value": null
         }
      }
   },
   "$defs": {
      "ExtendedTextHeaderSetting": {
         "description": "Configuration for extended textual headers parsing.",
         "properties": {
            "key": {
               "default": "extended_textual_headers",
               "title": "Key",
               "type": "string"
            },
            "value": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Value"
            }
         },
         "title": "ExtendedTextHeaderSetting",
         "type": "object"
      },
      "SampleIntervalSetting": {
         "description": "Configuration for samples interval parsing.",
         "properties": {
            "key": {
               "default": "sample_interval",
               "title": "Key",
               "type": "string"
            },
            "value": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Value"
            }
         },
         "title": "SampleIntervalSetting",
         "type": "object"
      },
      "SamplesPerTraceSetting": {
         "description": "Configuration for samples per trace parsing.",
         "properties": {
            "key": {
               "default": "samples_per_trace",
               "title": "Key",
               "type": "string"
            },
            "value": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Value"
            }
         },
         "title": "SamplesPerTraceSetting",
         "type": "object"
      }
   }
}

field samples_per_trace: SamplesPerTraceSetting = SamplesPerTraceSetting(key='samples_per_trace', value=None)

field sample_interval: SampleIntervalSetting = SampleIntervalSetting(key='sample_interval', value=None)

field extended_text_header: ExtendedTextHeaderSetting = ExtendedTextHeaderSetting(key='extended_textual_headers', value=None)

pydantic settings segy.config.ExtendedTextHeaderSetting

Configuration for extended textual headers parsing.

Show JSON schema

{
   "title": "ExtendedTextHeaderSetting",
   "description": "Configuration for extended textual headers parsing.",
   "type": "object",
   "properties": {
      "key": {
         "default": "extended_textual_headers",
         "title": "Key",
         "type": "string"
      },
      "value": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Value"
      }
   }
}

field key: str = 'extended_textual_headers'

field value: int | None = None

pydantic settings segy.config.SampleIntervalSetting

Configuration for samples interval parsing.

Show JSON schema

{
   "title": "SampleIntervalSetting",
   "description": "Configuration for samples interval parsing.",
   "type": "object",
   "properties": {
      "key": {
         "default": "sample_interval",
         "title": "Key",
         "type": "string"
      },
      "value": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Value"
      }
   }
}

field key: str = 'sample_interval'

field value: int | None = None

pydantic settings segy.config.SamplesPerTraceSetting

Configuration for samples per trace parsing.

Show JSON schema

{
   "title": "SamplesPerTraceSetting",
   "description": "Configuration for samples per trace parsing.",
   "type": "object",
   "properties": {
      "key": {
         "default": "samples_per_trace",
         "title": "Key",
         "type": "string"
      },
      "value": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Value"
      }
   }
}

field key: str = 'samples_per_trace'

field value: int | None = None