MagSurveyPy v1.0.1

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

Recommended: pip

Install the published package with:

python -m pip install magsurveypy

Upgrade with:

python -m pip install --upgrade magsurveypy

Verify the installation:

mspy --version
mspy --help
mspy tools doctor

Install from a source checkout with:

python -m pip install .

Uninstall with:

python -m pip uninstall magsurveypy

Uninstalling removes the installed Python package and the mspy command from the active environment. It does not remove MagSurveyPy projects, raw data, processed results, source folders, or downloaded archives.

Alternative: Conda environment

From the repository root:

conda env create -f environment.yml
conda activate magsurveypy
mspy --version

The supplied environment installs MagSurveyPy itself, so mspy is created automatically.

See INSTALL.md and docs/INSTALL.md for details.

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.

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

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.

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 currently published version-specific software archive is:

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

For research use, please cite the scientific description and the specific software version used. The CITATION.cff file contains the software metadata and identifies the preprint as the preferred scientific citation. The version-specific Zenodo DOI for v1.0.1 can be added after the release has been archived.

See CITATION.cff.

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.