API Reference¶

SEG-Y File¶

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

A SEG-Y file class that has various accessors.

Parameters:

url (str) – Path to SEG-Y file on disk or remote store.
spec (SegySpec | 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 or header_overrides.
settings (SegyFileSettings | None) – A settings instance to configure / override the SEG-Y parsing logic. Optional.
header_overrides (SegyHeaderOverrides | None) – A header overrides instance to modify the SEG-Y header(s) on the fly. Optional.

fs¶

The filesystem instance used to access the file.

Type:: AbstractFileSystem

url¶

The URL of the SEG-Y file on the filesystem.

Type:: str

property binary_header: HeaderArray¶: Read binary header from store, based on spec.

property ext_text_header: list[str]¶: Return textual file header.

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 (SegySpec) – 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(update=None)¶

Create a binary header for the SEG-Y file.

This function will create bytes representing the binary header with the configuration options provided to SEG-Y factory.

The update parameter is a dictionary that contains binary header fields which need to be modified. The function will update these fields with the values specified in the update dictionary before returning the encoded bytes.

Parameters:: update (dict[str, Any] | None) – Dictionary containing binary header fields to modify.
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 TextHeaderSpec. 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 or num samples.

Return type:

bytes

property sample_format: ScalarType¶: Trace sample format of the SEG-Y file.

property sample_interval: int¶: Return sample interval from spec.

property samples_per_trace: int¶: Return number of samples from spec.

property segy_revision: SegyStandard¶: Revision 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": {
      "endianness": {
         "anyOf": [
            {
               "$ref": "#/$defs/Endianness"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Override the inferred endianness of the file."
      },
      "storage_options": {
         "additionalProperties": true,
         "description": "Storage options to pass to the storage backend.",
         "title": "Storage Options",
         "type": "object"
      }
   },
   "$defs": {
      "Endianness": {
         "description": "Enumeration class with three possible endianness values.\n\nAttributes:\n    BIG: Big endian.\n    LITTLE: Little endian.\n\nExamples:\n    >>> endian = Endianness.BIG\n    >>> print(endian.symbol)\n    >",
         "enum": [
            "big",
            "little"
         ],
         "title": "Endianness",
         "type": "string"
      }
   }
}

field endianness: Endianness | None = None¶: Override the inferred endianness of the file.

field storage_options: dict[str, Any] [Optional]¶: Storage options to pass to the storage backend.

pydantic settings segy.config.SegyHeaderOverrides¶

SEG-Y header parsing overrides.

Any value that is set to an integer will override what is parsed from the binary header in the actual file. If you override with a float please ensure that the field is defined as a float. If not, the float will get down-cast to an integer.

Show JSON schema

{
   "title": "SegyHeaderOverrides",
   "description": "SEG-Y header parsing overrides.\n\nAny value that is set to an integer will override what is parsed from\nthe binary header in the actual file. If you override with a float\nplease ensure that the field is defined as a float. If not, the float\nwill get down-cast to an integer.",
   "type": "object",
   "properties": {
      "binary_header": {
         "additionalProperties": {
            "anyOf": [
               {
                  "type": "integer"
               },
               {
                  "type": "number"
               }
            ]
         },
         "description": "Header fields to override in binary header during read.",
         "title": "Binary Header",
         "type": "object"
      },
      "trace_header": {
         "additionalProperties": {
            "anyOf": [
               {
                  "type": "integer"
               },
               {
                  "type": "number"
               }
            ]
         },
         "description": "Header fields to override in trace headers during read.",
         "title": "Trace Header",
         "type": "object"
      }
   }
}

field binary_header: Mapping[str, int | float] [Optional]¶: Header fields to override in binary header during read.

field trace_header: Mapping[str, int | float] [Optional]¶: Header fields to override in trace headers during read.