mth5.io.nims.header

Created on Thu Sep 1 12:57:32 2022

@author: jpeacock

Exceptions

NIMSError

Common base class for all non-exit exceptions.

Classes

NIMSHeader

Class to hold NIMS header information.

Module Contents

exception mth5.io.nims.header.NIMSError

Bases: Exception

Common base class for all non-exit exceptions.

class mth5.io.nims.header.NIMSHeader(fn: str | pathlib.Path | None = None)

Class to hold NIMS header information.

This class parses and stores header information from NIMS DATA.BIN files. The header contains metadata about the measurement site, equipment setup, GPS coordinates, electrode configuration, and other survey parameters.

Parameters:

fn (str or Path, optional) – Path to the NIMS file to read, by default None

fn

Path to the NIMS file

Type:

Path or None

site_name

Name of the measurement site

Type:

str or None

state_province

State or province of the measurement location

Type:

str or None

country

Country of the measurement location

Type:

str or None

box_id

System box identifier

Type:

str or None

mag_id

Magnetometer head identifier

Type:

str or None

ex_length

North-South electric field wire length in meters

Type:

float or None

ex_azimuth

North-South electric field wire heading in degrees

Type:

float or None

ey_length

East-West electric field wire length in meters

Type:

float or None

ey_azimuth

East-West electric field wire heading in degrees

Type:

float or None

n_electrode_id

North electrode identifier

Type:

str or None

s_electrode_id

South electrode identifier

Type:

str or None

e_electrode_id

East electrode identifier

Type:

str or None

w_electrode_id

West electrode identifier

Type:

str or None

ground_electrode_info

Ground electrode information

Type:

str or None

header_gps_stamp

GPS timestamp from header

Type:

MTime or None

header_gps_latitude

GPS latitude from header in decimal degrees

Type:

float or None

header_gps_longitude

GPS longitude from header in decimal degrees

Type:

float or None

header_gps_elevation

GPS elevation from header in meters

Type:

float or None

operator

Operator name

Type:

str or None

comments

Survey comments

Type:

str or None

run_id

Run identifier

Type:

str or None

data_start_seek

Byte position where data begins in file

Type:

int

Examples

A typical header looks like:

'''
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
>>>user field>>>>>>>>>>>>>>>>>>>>>>>>>>>>
SITE NAME: Budwieser Spring
STATE/PROVINCE: CA
COUNTRY: USA
>>> The following code in double quotes is REQUIRED to start the NIMS <<
>>> The next 3 lines contain values required for processing <<<<<<<<<<<<
>>> The lines after that are optional <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
"300b"  <-- 2CHAR EXPERIMENT CODE + 3 CHAR SITE CODE + RUN LETTER
1105-3; 1305-3  <-- SYSTEM BOX I.D.; MAG HEAD ID (if different)
106  0 <-- N-S Ex WIRE LENGTH (m); HEADING (deg E mag N)
109  90 <-- E-W Ey WIRE LENGTH (m); HEADING (deg E mag N)
1         <-- N ELECTRODE ID
3         <-- E ELECTRODE ID
2         <-- S ELECTRODE ID
4         <-- W ELECTRODE ID
Cu        <-- GROUND ELECTRODE INFO
GPS INFO: 26/09/19 18:29:29 34.7268 N 115.7350 W 939.8
OPERATOR: KP
COMMENT: N/S CRS: .95/.96 DCV: 3.5 ACV:1
E/W CRS: .85/.86 DCV: 1.5 ACV: 1
Redeployed site for run b b/c possible animal disturbance
'''

logger

property fn: pathlib.Path | None

Full path to NIMS file.

Returns:

Path object representing the NIMS file location, or None if no file is set

Return type:

Path or None

header_dict = None

site_name = None

state_province = None

country = None

box_id = None

mag_id = None

ex_length = None

ex_azimuth = None

ey_length = None

ey_azimuth = None

n_electrode_id = None

s_electrode_id = None

e_electrode_id = None

w_electrode_id = None

ground_electrode_info = None

header_gps_stamp = None

header_gps_latitude = None

header_gps_longitude = None

header_gps_elevation = None

operator = None

comments

run_id = None

data_start_seek = 0

property station: str | None

Station ID derived from run ID.

Returns:

Station identifier (run ID without the last character), or None if run_id is not set

Return type:

str or None

Notes

The station ID is typically the run ID with the last character (run letter) removed.

property file_size: int | None

Size of the NIMS file in bytes.

Returns:

File size in bytes, or None if no file is set

Return type:

int or None

Raises:

FileNotFoundError – If the file does not exist

read_header(fn: str | pathlib.Path | None = None) → None

Read header information from a NIMS file.

This method reads and parses the header section of a NIMS DATA.BIN file, extracting metadata about the survey setup, GPS coordinates, electrode configuration, and other parameters.

Parameters:

fn (str or Path, optional) – Full path to NIMS file to read. Uses self.fn if not provided.

Raises:

NIMSError – If the file does not exist or cannot be read

Notes

The method reads up to _max_header_length bytes from the beginning of the file, parses the header information, and stores the results in the header_dict attribute and individual properties.

parse_header_dict(header_dict: dict[str, str] | None = None) → None

Parse the header dictionary into individual attributes.

This method takes the raw header dictionary and extracts specific information into class attributes for easy access.

Parameters:

header_dict (dict of str, optional) – Dictionary containing header key-value pairs. Uses self.header_dict if not provided.

Notes

Parses various header fields including: - Wire lengths and azimuths for electric field measurements - System box and magnetometer IDs - GPS coordinates and timestamp - Run identifier - Other metadata fields