pynetdesign.modelling.io.read_geometry#

pynetdesign.modelling.io.read_geometry(file_path)[source]#

Read geometry data from a whitespace-delimited CSV (ASCII) file and return a DataFrame.

This function reads a CSV (ASCII) file containing geometry information, ensuring that coordinate columns (Latitude/Northing, Longitude/Easting, Elevation) and NoiseLevel column are present. The ‘Name’, ‘Surface’ and ‘Components’ columns are optional. The resulting DataFrame has columns renamed and units converted as necessary. If header has ‘GaugeLength=’, the appropriate gauge length is read and stored in the attributes.

Parameters:
file_pathstr

The path to the input CSV (ASCII) file containing the geometry data.

Returns:
pd.DataFrame

A DataFrame containing the renamed columns:

  • ‘Name’ for Name (if present in the input file)

  • ‘Y’ for Latitude or Northing (converted to meters)

  • ‘X’ for Longitude or Easting (converted to meters)

  • ‘Z’ for Depth (negative of Elevation, converted to meters)

  • ‘NoiseLevel’ for Noise Level

  • ‘Surface’ for the free surface indicator (if present in the input file)

  • ‘Components’ for the recorded station components (if present in the input file)

The DataFrame also includes metadata:

  • df.attrs['file_path']: Path of the file that was read

  • df.attrs['original_coord_units']: Original units of coordinate columns

  • df.attrs['noise_type']: Type of noise measurement

  • df.attrs['noise_unit']: Original unit of noise measurement

  • df.attrs['gauge_length']: Gauge length (if specified in the header)

  • df.attrs['_is_combined']: Combined status (False)

Raises:
ValueError

If required columns are missing, unknown columns are present, inconsistent units are found for coordinate columns, or if an unrecognized unit is encountered for the NoiseLevel column or GaugeLength.

Notes

  • The function handles whitespace and tabs as delimiters.

  • It recognizes and converts units for coordinate columns (m, km, ft).

  • For the NoiseLevel column, it recognizes units: m (displacement), m/s (velocity), m/s^2 (acceleration), and 1/s (strain).

  • The ‘Z’ column is converted to represent depth (negative of elevation).

  • The ‘Name’ column, if present, is interpreted as strings.

  • The ‘Surface’ column, if present, is a weight in [0, 1] marking receivers at the free surface, where a fractional value blends between no amplification and full free surface amplification.

  • The ‘Components’ column, if present, must be ‘3C’ or ‘Z’ and is only allowed for station geometries, not for DAS geometries.

  • Only known columns (‘Name’, ‘Latitude’, ‘Northing’, ‘Longitude’, ‘Easting’, ‘Elevation’, ‘NoiseLevel’, ‘Surface’, ‘Components’) or combinations like ‘Latitude/Northing’ or ‘Latitude(WGS84)/Northing(m)’ are read from the file.

  • For Latitude and Longitude conversion to m is not implemented, inputs are treated as meters

  • The function will raise an error if any unknown columns are present in the input file.

Examples

>>> df = read_geometry("data/geometry.csv")
>>> print(df.head())
>>> print(df.attrs)  # To view metadata
On this page