MagSurveyPy v1.0.3

Archaeological Magnetometry Prospection Suite
Open-source processing, analysis, quality control, GIS integration, cartography, and local GIS inspection for archaeological magnetometry.

Developed by Alexandru Hegyi, PhD
Department of Geosciences, University of Oslo
UiO: alexandru.hegyi@geo.uio.no · Personal: alexandruhegyi@gmail.com
Website: https://alexandruhegyi.com · GitHub: https://github.com/alexandruhegyi

Overview

MagSurveyPy is a project-based Python package and command-line application for archaeological magnetometry. It supports multichannel magnetic acquisition, gridded total-field magnetometry, and fluxgate magnetometry/gradiometry in a common workflow built around the mspy command.

The software combines:

• native and generic data import;
• acquisition-aware survey processing;
• interpolation with explicit spatial support;
• observation- and raster-domain filtering;
• line, traverse, grid, and background corrections;
• robust statistics, spectral analysis, and QC;
• enhancement and optional segmentation/vectorization;
• georeferencing and reprojection;
• quantitative GeoTIFF, ASCII-grid, CSV, and GIS export;
• scientific figures and cartographic output;
• a local GIS interface for interactive inspection, profiles, drawing, georeferencing, and current-view export;
• project history and incremented result branches for reproducibility.

Supported native readers are used where acquisition metadata are encoded in instrument files. Generic ASC, CSV, TXT, XYZ, DAT, raster, and GIS formats can be used when their coordinates and measurement fields are sufficiently defined.

Software architecture

MagSurveyPy separates input decoding, positioning, project data, quantitative processing, analysis, and presentation. Raw inputs remain separate from derived products, while each processing stage can retain its own reports, diagnostics, previews, and comparisons.

The project model is intentionally explicit:

Project/
├── project.json
├── RawData/
│   ├── Multichannel/
│   ├── TotalField/
│   ├── Fluxgate/
│   ├── Generic/
│   ├── GNSS/
│   └── BaseStation/
├── Config/
├── Layouts/
├── Results/
├── Reports/
├── Exports/
├── Logs/
└── Temp/

Automatic processing figures follow the same structure across result stages:

PNG/
├── Comparison/
├── Products/
├── QC/
└── Diagnostics/

Comparison/ contains the principal source/result comparison and, where relevant, a separately retained removed component. Products/ contains clean raster previews, QC/ contains quality-control figures, and Diagnostics/ contains spectra and specialist diagnostic plots. Publication cartography remains under mspy figure and mspy export.

Processing domains

Quantitative processing is separated from display-only operations. Acquisition decoding and positioning occur before observation-domain corrections; interpolation creates quantitative rasters with explicit support; raster filters create new quantitative branches; brightness, contrast, gamma, saturation, and display ranges remain presentation controls and do not rewrite raster values.

This distinction is important when evaluating filters. Where applicable, MagSurveyPy retains source, filtered, and removed-component products separately so that the effect of a processing choice can be inspected rather than inferred only from the appearance of the final map.

Installation

MagSurveyPy is distributed through PyPI.

Recommended setup on Windows and macOS: Miniconda or Anaconda + pip

For Windows and macOS, the recommended approach is to create an isolated Conda environment and install MagSurveyPy from PyPI with pip.

Important: Conda is used to create and manage the Python environment. MagSurveyPy itself is installed from PyPI with pip. It is not currently distributed through a Conda channel.

Windows — Miniconda Prompt or Anaconda Prompt

conda create -n magsurveypy python=3.12 -y
conda activate magsurveypy
python -m pip install --upgrade pip
python -m pip install magsurveypy
mspy --version

For later sessions:

conda activate magsurveypy
mspy --version

Activating the environment automatically adds its executable directory to PATH. This normally avoids the Windows situation where MagSurveyPy installs successfully but the mspy command cannot be found.

A dedicated MagSurveyPy environment is preferable to installing into an application-managed Python environment such as the default ArcGIS Pro environment.

macOS

After installing Miniconda or Anaconda:

conda create -n magsurveypy python=3.12 -y
conda activate magsurveypy
python -m pip install --upgrade pip
python -m pip install magsurveypy
mspy --version

Using a dedicated Conda environment also avoids restrictions associated with some system-managed macOS Python installations.

For later sessions:

conda activate magsurveypy
mspy --version

Linux

The same isolated workflow can be used:

conda create -n magsurveypy python=3.12 -y
conda activate magsurveypy
python -m pip install --upgrade pip
python -m pip install magsurveypy
mspy --version

Direct pip installation

If a suitable Python environment is already available, Conda is not required:

python -m pip install magsurveypy
mspy --version

Inside an activated Conda environment, the shorter form also works:

pip install magsurveypy

To install the current release explicitly:

python -m pip install magsurveypy==1.0.3

For more detailed installation guidance, see docs/INSTALL.md.

Quick start

The canonical public syntax uses the same option names across the application:

--project    working project
--input      explicit external input, where required
--from       existing result stage
--output     explicit output override
--increment  preserve an existing result and create a numbered branch

A compact multichannel workflow is:

mspy project init --project Site --category multichannel
mspy project import --project Site --input /path/to/data --type multichannel
mspy survey multichannel --project Site --format auto --workflow standard
mspy analyze survey --project Site
mspy process interpolate --project Site --method archaeology
mspy web --project Site

Historical positional project/input forms remain accepted for compatibility, but new documentation uses the explicit option-based syntax.

Survey workflows

Multichannel magnetic acquisition

mspy project init --project Site --category multichannel
mspy project import --project Site --input /path/to/multichannel_data --type multichannel
mspy survey multichannel --project Site --format auto --workflow standard
mspy analyze survey --project Site
mspy process interpolate --project Site --method archaeology

Normalized ASC can also be supplied directly where supported. Source/session/sensor/channel provenance is retained where the input format provides it.

Direct supported SENSYS PRM workflow

For implemented SENSYS PRM structures, MagSurveyPy can decode native magnetic words together with embedded GPS fixes and stored probe geometry. This allows georeferenced observations to be reconstructed directly from the acquisition data without a mandatory intermediate conversion through DLMGPS or MAGNETO.

Native compatibility is format-specific; supported PRM structures should not be interpreted as universal compatibility with every historic or future PRM variant.

Gridded total-field magnetometry

mspy project init --project Site --category total-field
mspy project import --project Site --input /path/to/total_field_data --type total-field
mspy survey grid --project Site --protocol total-field --workflow preservation
mspy analyze survey --project Site --from TOTAL_FIELD

A more archaeology-oriented processing example is:

mspy survey grid --project Site --protocol total-field \
  --traverse-zero median \
  --deslope robust \
  --destripe protected \
  --destripe-strength 1 \
  --high-pass 5 \
  --archaeology-center median \
  --cell-size 0.25 \
  --statistic mean

The absolute/reference field remains separate from derived archaeology-oriented products.

Example total-field workflow showing measured-cell support, interpolation, and derived processing products. The support information makes the distinction between measured and interpolated areas explicit.

Fluxgate magnetometry / gradiometry

mspy project init --project Site --category fluxgate
mspy project import --project Site --input /path/to/grid_data --type fluxgate
mspy layout gui --project Site --protocol fluxgate
mspy layout validate --project Site --protocol fluxgate
mspy survey grid --project Site --protocol fluxgate --workflow archaeology
mspy analyze survey --project Site --from FLUXGATE

Example multichannel fluxgate/gradiometer processing comparison. The reference raster is retained so that alternative processing branches can be evaluated against the same quantitative input.

Optional paired-sensor gradients

If a total-field file retains paired sensor channels, an additional vertical or horizontal gradient can be derived when the physical sensor geometry is known. Existing measured-gradient columns can also be used directly. Sensor separation is never silently inferred.

mspy survey grid --project Site --protocol total-field \
  --gradient vertical --sensor-separation 0.50

Gradient derivation is an optional secondary product; ordinary one-column total-field data remain normal total-field inputs.

Interpolation, filtering, QC, and segmentation

MagSurveyPy provides several interpolation and processing branches, including:

• measured-cell aggregation;
• linear TIN interpolation;
• inverse-distance weighting;
• local kriging;
• nearest-neighbour and bounded cubic alternatives;
• support masks and preserved NoData gaps;
• robust despiking;
• traverse and line levelling;
• Gaussian and median filtering;
• spatial high-pass/low-pass filtering;
• Fourier-domain filters and directional diagnostics;
• plane removal and upward continuation;
• survey, line, sensor, raster, and spectral QC;
• optional segmentation and candidate vectorization as interpretive support.

Segmentation produces auxiliary candidate objects and does not replace the quantitative magnetic raster or constitute automatic archaeological interpretation.

Inspecting filtering results

Where appropriate, MagSurveyPy retains source, filtered, and removed-component products separately. This makes it possible to evaluate what a filter removed rather than judging the processing only from the final map.

Example processing of a challenging magnetic raster. Source and derived branches are retained separately so that the effect of cleaning and filtering can be inspected directly.

Multichannel filtering example showing the source raster, retained filtered component, and removed component. The removed component provides a direct audit of the structures suppressed by the selected filter.

Local GIS interface

Launch the local GIS interface with:

mspy web --project Site

It provides project-aware raster display, basemaps, statistics, profiles, drawing tools, georeferencing, layer controls, and export of the current map view. Display adjustments such as brightness, contrast, gamma, saturation, opacity, and manual display limits do not alter the stored quantitative raster.

The local GIS is intended for rapid project-linked inspection and spatial work; it does not attempt to replace a full desktop GIS.

Command groups

Start with:

mspy --help
mspy project --help
mspy survey --help
mspy survey grid --help
mspy guide projects
mspy guide installation

The detailed documentation is under docs/, including workflow, filtering, interpolation, total-field, fluxgate, PRM, georeferencing, export, QC, and local GIS guides.

Reproducibility and data preservation

MagSurveyPy keeps field inputs separate from derived products. Processing commands maintain project histories, and --increment can preserve an existing stage while creating a numbered alternative. Analysis commands create diagnostics without modifying scientific data.

The project structure therefore preserves the distinction between:

1. source/acquisition data;
2. normalized observations;
3. quantitative processing stages;
4. QC and diagnostic products;
5. publication/cartographic outputs;
6. display-only operations.

Scientific description and citation

A detailed description of the architecture, numerical processing, native PRM workflow, GIS handling, QC, and reproducibility model is available as a Zenodo preprint:

Hegyi, A. (2026). MagSurveyPy: An Open-Source Framework for Archaeological Magnetometry Processing and Spatial Analysis (Version 1). Zenodo.
https://doi.org/10.5281/zenodo.22709406

The current version-specific software archive is:

Hegyi, A. (2026). MagSurveyPy: Archaeological Magnetometry Prospection Suite (Version 1.0.1) [Computer software]. Zenodo.
https://doi.org/10.5281/zenodo.22710282

For research use, please cite the scientific description and the specific software version used. The CITATION.cff file contains the version-specific software DOI and identifies the preprint as the preferred scientific citation.

See CITATION.cff.

v1.0.3 terminal compatibility and installation update

Version 1.0.3 is a terminal-compatibility and installation-documentation patch release. It does not change the scientific processing algorithms, numerical defaults, interpolation mathematics, filtering mathematics, georeferencing, native data decoding, or quantitative GIS behaviour established in v1.0.2.

The release changes the terminal banner from a fixed black foreground to the terminal's default foreground colour so that it remains visible on both dark and light terminal themes. It also expands Windows and macOS installation guidance, with Miniconda or Anaconda used to manage an isolated environment and MagSurveyPy installed from PyPI with pip.

See docs/RELEASE_NOTES_v1.0.3.md.

v1.0.2 documentation and metadata maintenance

Version 1.0.2 is a documentation and metadata maintenance release. It does not change the scientific processing algorithms, numerical defaults, interpolation mathematics, filtering mathematics, georeferencing, native data decoding, or quantitative GIS behaviour established in v1.0.1.

The release updates the project README and scientific workflow illustrations, uses PyPI-compatible absolute image references, refreshes package and citation metadata, and improves consistency between the GitHub, PyPI, Zenodo, and preprint presentation.

See docs/RELEASE_NOTES_v1.0.2.md.

v1.0.1 consistency update

Version 1.0.1 is a consistency-focused release. It does not intentionally change the established scientific processing algorithms. The main changes are:

• uniform --project, --input, --from, --output, and --increment conventions;
• compatibility with historical positional forms;
• consistent PNG/Comparison, PNG/Products, PNG/QC, and PNG/Diagnostics output organization;
• common automatic raster-preview and comparison styling;
• adaptive colorbar tick density to avoid overlapping labels, including large absolute total-field values;
• separation of routine processing previews from explicit publication/cartographic decoration;
• retained removed-component products where appropriate for filtering audits;
• updated documentation and citation metadata.

See docs/RELEASE_NOTES_v1.0.1.md.

License and warranty

MagSurveyPy is distributed under the BSD 3-Clause License. See LICENSE.

The software is provided “AS IS”, without warranties of any kind. Users remain responsible for validating processing choices, coordinate systems, sensor geometry, quantitative outputs, and archaeological interpretation for their own data and purpose.