Coverage for C: \ Users \ peaco \ OneDrive \ Documents \ GitHub \ mth5 \ mth5 \ io \ phoenix \ read.py: 100%
27 statements
« prev ^ index » next coverage.py v7.13.1, created at 2026-01-27 20:09 -0800
1# -*- coding: utf-8 -*-
2"""
3Created on Fri May 6 12:39:34 2022
5@author: jpeacock
6"""
8# =============================================================================
9# Imports
10# =============================================================================
11from __future__ import annotations
13from pathlib import Path
14from typing import Any, TYPE_CHECKING
16from .readers import (
17 DecimatedContinuousReader,
18 DecimatedSegmentedReader,
19 MTUTable,
20 MTUTSN,
21 NativeReader,
22)
25if TYPE_CHECKING:
26 from mth5.timeseries import ChannelTS, RunTS
29# =============================================================================
30# Dictionary for reader types
31# =============================================================================
32READERS: dict[str, type] = {
33 "bin": NativeReader,
34 "td_24k": DecimatedSegmentedReader,
35 "td_150": DecimatedContinuousReader,
36 "td_30": DecimatedContinuousReader,
37 "TS3": MTUTSN,
38 "TS4": MTUTSN,
39 "TS5": MTUTSN,
40 "TBL": MTUTable,
41 "TSL": MTUTSN,
42 "TSH": MTUTSN,
43}
46def get_file_extenstion(file_name: str | Path) -> str:
47 """
48 Get the file extension from a file name.
50 Parameters
51 ----------
52 file_name : str or pathlib.Path
53 The file name to extract the extension from.
55 Returns
56 -------
57 str
58 The file extension without the leading dot.
59 """
60 file_name = Path(file_name)
61 return file_name.suffix[1:]
64def open_phoenix(
65 file_name: str | Path, **kwargs: Any
66) -> (
67 DecimatedContinuousReader
68 | DecimatedSegmentedReader
69 | NativeReader
70 | MTUTSN
71 | MTUTable
72):
73 """
74 Open a Phoenix Geophysics data file in the appropriate container.
76 Parameters
77 ----------
78 file_name : str or pathlib.Path
79 Full path to the Phoenix data file to open.
80 **kwargs : Any
81 Additional keyword arguments to pass to the reader constructor.
83 Returns
84 -------
85 reader : DecimatedContinuousReader | DecimatedSegmentedReader | NativeReader
86 The appropriate Phoenix reader container based on file extension:
87 - .bin files: NativeReader
88 - .td_24k files: DecimatedSegmentedReader
89 - .td_150/.td_30 files: DecimatedContinuousReader
91 Raises
92 ------
93 KeyError
94 If the file extension is not supported by any Phoenix reader.
95 """
96 extension = get_file_extenstion(file_name)
98 # need to put the data into a TS object
100 return READERS[extension](file_name, **kwargs)
103def read_phoenix(file_name: str | Path, **kwargs: Any) -> ChannelTS | RunTS | MTUTable:
104 """
105 Read a Phoenix Geophysics data file into a ChannelTS or RunTS object
106 depending on the file type. Newer files that end in .td_XX or .bin will be
107 read into ChannelTS objects. Older MTU files that end in .TS3, .TS4, .TS5,
108 .TSL, or .TSH will be read into RunTS objects.
110 Parameters
111 ----------
112 file_name : str or pathlib.Path
113 Path to the Phoenix data file to read.
114 **kwargs : Any
115 Additional keyword arguments. May include:
117 - rxcal_fn : str or pathlib.Path, optional
118 Path to receiver calibration file.
119 - scal_fn : str or pathlib.Path, optional
120 Path to sensor calibration file.
121 - table_filepath : str or pathlib.Path, optional
122 Path to the MTU TBL file for use with MTUTSN files.
123 - Other arguments passed to the Phoenix reader constructor.
125 Returns
126 -------
127 channel_ts : ChannelTS
128 Time series data object containing the Phoenix file data
129 with calibration applied if calibration files were provided.
131 run_ts : RunTS
132 Time series data object containing the MTU data from the Phoenix MTU
133 files with calibration applied if specified.
135 mtu_table : MTUTable
136 Metadata table object containing the MTU table data.
138 Raises
139 ------
140 KeyError
141 If the file extension is not supported by any Phoenix reader.
142 ValueError
143 If the file cannot be read or converted to ChannelTS or RunTS format.
144 """
145 extension = get_file_extenstion(file_name)
146 if extension.startswith("td_") or extension == "bin":
147 phnx_obj = open_phoenix(file_name, **kwargs)
148 rxcal_fn = kwargs.pop("rxcal_fn", None)
149 scal_fn = kwargs.pop("scal_fn", None)
151 return phnx_obj.to_channel_ts(rxcal_fn=rxcal_fn, scal_fn=scal_fn)
152 elif extension in ["TS3", "TS4", "TS5", "TSL", "TSH"]:
153 tbl_file = kwargs.pop("table_filepath", None)
154 mtu_obj = open_phoenix(file_name, **kwargs)
155 run_ts = mtu_obj.to_runts(table_filepath=tbl_file, calibrate=True)
156 return run_ts
157 elif extension == "TBL":
158 mtu_table = open_phoenix(file_name, **kwargs)
159 return mtu_table
160 else:
161 raise KeyError(
162 f"File extension '{extension}' is not supported by any Phoenix reader."
163 )