kashima 3.3.1

Interactive seismic event mapping and catalog management.

kashima

Interactive Seismic Event Mapping and Catalog Management

Last updated: June 20, 2026

kashima is a Python library for seismic event visualization and catalog processing that produces interactive Folium-based web maps from global earthquake catalogs and auxiliary datasets. The active package surface is kashima.mapper.

Contents

• Overview
• Who is this for? (TL;DR)
• Features
• Installation
• Quickstart
• Usage
• Examples
• API overview
• API help
• Command-line interface / man page
• Dependencies
• Documentation (how to read)
• License
• Citation
• Author

Overview

kashima focuses on the mapping workflow for engineering seismology: given one or more sites of interest, it builds reproducible web maps that combine:

• Global earthquake catalogs (USGS ComCat, Global CMT NDK, ISC Bulletin)
• Auxiliary fault databases (GEM, USGS Quaternary, EFSM20) and user GeoJSON faults
• Global ISC station layer (from a packaged CSV, filtered to the map window)
• Optional user event catalogs in the normalized mapper schema

The heavy lifting (data download, caching, clipping and styling) is encapsulated in a small public API under kashima.mapper.

Who is this for? (TL;DR)

kashima is aimed at engineering seismology, seismic hazard and mining/energy projects where you need reproducible, shareable web maps of earthquakes, faults and stations around one or more sites.

The typical workflow is:

1. Install the library: python -m pip install kashima.
2. Pre-populate the global cache once: downloadAllCatalogs(include_faults=True).
3. Build a map for your site with buildMap(...) and open the generated maps/index.html in a browser.

Features

• Multi-catalog support: USGS, Global CMT (NDK method), ISC, and custom event catalogs
• Interactive maps: Folium-based maps with beachball focal mechanisms, distance rings and rich tooltips
• Global cache: Download catalogs and fault databases once, reuse across projects with incremental updates
• Advanced visualizations: Heatmaps, clustered markers, epicentral circles, fault overlays
• Auxiliary data: GEM Active Faults, USGS Quaternary Faults, EFSM20 fault databases
• Global ISC stations: packaged CSV (~41k stations) automatically clipped to the map radius, with a dedicated layer
• Multi-fault datasets: combine GEM, USGS Quaternary and EFSM20 faults (and local GeoJSONs) in a single color-coded layer
• Reproducible projects: every map writes the catalogs actually used to ./maps and (optionally) ./data for auditability

Installation

Requires Python 3.8+.

python -m pip install --upgrade pip
python -m pip install kashima

Verify the install:

python - <<'PY'
import kashima
from kashima.mapper import buildMap, downloadAllCatalogs

print("kashima", kashima.__version__)
print(buildMap, downloadAllCatalogs)
PY

Development version:

git clone https://github.com/averriK/kashima.git
cd kashima
python -m pip install --upgrade pip
python -m pip install -e .

Build a local wheel from source:

python -m pip install --upgrade build
python -m build
python -m pip install dist/kashima-3.3.1-py3-none-any.whl

Quickstart

1. Install kashima (see above).
2. Initialize the global cache (earthquake catalogs + optional fault databases). Run this once per machine. pip install kashima installs the library and bundled seed data; it does not guarantee that the user cache contains the newest daily catalogs until you refresh it:

from kashima.mapper import downloadAllCatalogs

# First-time setup: fills ~/.cache/kashima (Linux),
# ~/Library/Caches/kashima (macOS) or %LOCALAPPDATA%\kashima\Cache\ (Windows)
downloadAllCatalogs(include_faults=True)

3. Build your first map around a site of interest:

from kashima.mapper import buildMap

result = buildMap(
    latitude=-32.86758,
    longitude=-68.88867,
    radius_km=500,
    project_name="Mendoza seismicity",
    client="Example Mining Co.",
)

print("HTML map:", result["html"])  # ./maps/index.html
print("Events CSV:", result["csv"])  # ./maps/epicenters.csv

Open the generated index.html in a browser to explore earthquakes, faults and stations interactively.

Usage

Map layers and concepts

Each map produced by buildMap is composed of several layers that you can turn on/off in the Folium LayerControl:

• Events: epicentral points coloured and sized by magnitude, coming from USGS/GCMT/ISC or an optional user CSV.
• Clustered view: an alternative representation where nearby events are grouped into clusters to reduce overplotting.
• Heatmap: a smoothed density field of events, controlled by the heatmap_* parameters.
• Beachballs: focal mechanisms (from GCMT) drawn as beachball symbols for events above a given magnitude.
• Faults: line features from global fault databases (GEM, USGS Quaternary, EFSM20) selected via fault_sets, plus any local GeoJSON passed in faults_files, all clipped to the same geographic window as the events.
• Stations: global ISC stations from the packaged CSV, your own station_csv_path, or GMDB stations when gmdb_index_path is active.
• Site marker: a star symbol at the site location (latitude, longitude).
• Epicentral circles: concentric distance rings around the site, controlled by epicentral_circles.

These layers showcase most of the power of kashima; the parameters of buildMap let you decide which ones to include and how they look.

High-level map API: buildMap

The main entry point is kashima.mapper.buildMap. It:

• Copies the latest cached USGS/ISC/GCMT catalogs into a project-local data/ directory
• Optionally merges global fault databases (GEM, USGS Quaternary, EFSM20) and user GeoJSON faults
• Adds a global ISC stations layer by default, unless station_csv_path or gmdb_index_path overrides station ownership
• Builds a Folium map and writes maps/index.html + maps/epicenters.csv

Minimal call (requires a pre-populated cache, see Quickstart):

from kashima.mapper import buildMap

result = buildMap(
    latitude=-32.86758,
    longitude=-68.88867,
)

A more realistic example using multiple layers, fault sets and local faults:

from kashima.mapper import buildMap

result = buildMap(
    latitude=-12.90795,
    longitude=+15.24845,
    radius_km=3500,
    # Layer visibility
    show_events_default=True,
    show_cluster_default=False,
    show_heatmap_default=True,
    show_beachballs_default=True,
    show_faults_default=True,
    show_epicentral_circles_default=True,
    # Fault datasets: global cache + local GeoJSONs
    fault_sets=["gem", "usgs", "efsm20"],
    faults_files=[
        "examples/mapper/faults/Angola1982.geojson",
        "examples/mapper/faults/Escosa2024.geojson",
    ],
    # Stations: default ISC CSV from cache, custom title
    station_layer_title="ISC + local stations",
    # Keep ./data snapshot for documentation
    keep_data=True,
)

print(result)

Key parameter groups (see help(buildMap) for the full list and defaults):

• Location & radius (latitude, longitude, radius_km, event_radius_multiplier): define the geographic window of the map. radius_km sets the base radius, and event_radius_multiplier scales that radius when computing the spatial window used for events, faults and stations.
• Layers (show_events_default, show_cluster_default, show_heatmap_default, show_beachballs_default, show_faults_default, show_stations_default, show_epicentral_circles_default): control which layers are visible when the map opens. Users can still toggle them later via the Folium LayerControl.
• Catalogs & data (user_events_csv, keep_data, output_dir, gmdb_index_path): override the global catalogs with your own CSV, preserve the ./data snapshot for auditability, choose where maps/ and data/ are written, and optionally hydrate matched events/stations from a GMDB snapshot.
• Fault configuration (fault_sets, faults_files, regional_faults_color, regional_faults_weight, faults_coordinate_system): select which cached fault databases (any subset of "gem", "usgs", "efsm20") are merged and which extra GeoJSON faults to add (for example the Angola files used in examples/mapper/longonjo.py), and how they are styled.
• Stations (station_csv_path, station_coordinate_system, station_layer_title, show_stations_default): keep the default global ISC stations or replace them with your own CSV, adjusting CRS and layer title for the stations layer. Use show_stations_default=False to start with the stations layer turned off.
• Styling & legend (mag_bins, dot_palette, dot_sizes, beachball_sizes, fault_style_meta, color_palette, color_reversed, scaling_factor, legend_title, legend_position): control how magnitudes map to colours and sizes and how the legend is rendered. Much of the visual power of examples like examples/mapper/longonjo.py comes from careful tuning of these parameters.
• XY coordinates (x_col, y_col, location_crs): work in projected coordinates (for example local UTM) instead of latitude/longitude, useful when your input catalogs are already in a local CRS.
• Tooltips (tooltip_fields, legend_map): choose which event fields appear in the tooltip and how they are labelled.
• Map behavior (base_zoom_level, min_zoom_level, max_zoom_level, default_tile_layer, auto_fit_bounds, lock_pan, epicentral_circles): control the initial view (zoom levels and base tile layer) and how many distance rings are drawn around the site via epicentral_circles. auto_fit_bounds and lock_pan exist for future map-behaviour controls and may have no visible effect in some versions; use help(buildMap) for the authoritative description.

buildMap returns a small dictionary:

{
    "html": "path/to/index.html",
    "csv": "path/to/epicenters.csv",
    "event_count": 1234,
}

Catalog API: buildCatalog

For scripted data pipelines you can call buildCatalog directly to fetch and save catalogs without generating maps.

from kashima.mapper import buildCatalog

# Radial USGS query around a site
result = buildCatalog(
    source="usgs",
    output_path="data/usgs-events.csv",
    latitude=-32.86758,
    longitude=-68.88867,
    max_radius_km=500,
    min_magnitude=5.0,
    start_time="2010-01-01",
    end_time="2024-12-31",
)
print(f"Downloaded {result['event_count']} events from {result['source']}")

# Full global catalog (no spatial filter)
result = buildCatalog(
    source="gcmt",
    output_path="data/gcmt-full.csv",
    min_magnitude=5.5,
)

Supported sources are "usgs", "gcmt" and "isc" (see docstring for details and current status).

Global cache & updates

kashima maintains a global cache so catalogs and fault databases are downloaded once and reused across all projects.

from kashima.mapper import (
    downloadAllCatalogs,
    updateAllCatalogs,
    get_cache_dir,
    clear_cache,
)

# One-time setup (or when you want to pre-populate everything)
catalogs = downloadAllCatalogs(include_faults=True)
print("Cache directory:", catalogs["cache_dir"])

# Incremental update (new events only + refreshed fault databases)
updated = updateAllCatalogs(include_faults=True)
print("New USGS events:", updated["usgs_new"])

# Inspect cache location
print("Cache lives in:", get_cache_dir())

# Optional: clear a catalog if needed
# clear_cache("usgs")
# clear_cache("gmdb")

On first use, downloadAllCatalogs copies bundled USGS/ISC/GCMT, fault and station seeds from the wheel into the cache, so initial setup is often instant. The GMDB snapshot is larger after expansion and is initialized lazily by getMasterIndexPath() only when a hydrated map asks for it.

Packaged catalog CSV files are seed/snapshot data. For current USGS/ISC/GCMT content, use downloadAllCatalogs() for first-time setup and updateAllCatalogs() or the source-specific update functions before building new maps.

Fault databases

Global fault datasets live in the cache as GeoJSON files and are consumed automatically by buildMap when show_faults_default=True. You can also work with them explicitly via:

• buildGEMActiveFaults()
• buildUSGSQuaternaryFaults()
• buildEFSM20Faults()

Use fault_sets to choose which cached datasets to merge (any subset of "gem", "usgs", "efsm20") and faults_files to add custom GeoJSON faults (for example the Angola examples in examples/mapper/faults/).

Station layer

By default buildMap adds a global ISC stations layer:

• The CSV isc_stations.csv is bundled inside the package and copied to the cache on first use.
• When you do not pass station_csv_path, buildMap reads stations from the cache, clips them to the same geographic window as the events and adds them as a toggleable layer.
• If you pass station_csv_path, your CSV is used instead and the default ISC stations are ignored.
• If you pass gmdb_index_path, GMDB owns the station layer and station_csv_path is not allowed.
• Note: passing an empty string for station_csv_path raises an error; omit it to use the default ISC stations.

Project mapper scaffold

PSHA project report slots use a one-map scaffold:

• mapper/run.py writes mapper/byEvent/index.html and mapper/byEvent/epicenters.csv.
• mapper/byCluster is retired and must not be regenerated.
• Old two-map builders should be preserved under legacy/mapper/run.py before replacement.
• Hydrated reports pass gmdb_index_path=str(getMasterIndexPath()) to expand and use the bundled/cache GMDB RawMasterIndex.csv snapshot.
• When keep_data=True, hydrated maps write data/gmdb.json with the GMDB source path, hash, size and matched row counts used by that map.

See Project mapper scaffold for the agent-facing contract.

Examples

Complete, runnable workflows live in examples/mapper/:

• Catalog setup & maintenance
  • 00_download_catalogs.py, 00_update_catalogs.py
  • 01_usgs_catalog.py, 02_gcmt_catalog.py, 03_isc_catalog.py, 03_update_catalogs.py, 04_rebuild_cache.py
• Basic and intermediate maps
  • 04_minimal_map.py, 05_map_with_beachballs.py, 06_map_with_custom_legend.py, 07_map_with_heatmap.py, 08_map_with_faults.py, 09_map_advanced_config.py, longonjo.py
• Fault databases & stations
  • 05_custom_faults.py, 06_update_active_faults.py, 07_compile_all_fault_databases.py, 08_update_all_catalogs_and_faults.py
• Custom catalogs
  • pass a normalized event CSV through user_events_csv in buildMap()

Use these scripts as living documentation of typical workflows and advanced configuration.

Advanced example: examples/mapper/longonjo.py

This script demonstrates a project-style map centred on Angola with:

• custom magnitude bins, colour scales and point sizes tuned for satellite imagery;
• a mix of global fault databases and multiple regional fault GeoJSON files passed via faults_files;
• a large search radius (radius_km=3500), satellite base tiles, locked panning and keep_data=True so the generated data/ directory can be inspected or versioned.

Use it as a template for real engineering projects: copy the script, adjust coordinates, radius, faults_files and project metadata, and you will obtain a map suitable for inclusion in technical reports.

API overview

The public API of kashima.mapper is defined by what is exported from kashima/mapper/__init__.py. The most important entry points are:

• Map & catalogs
  • buildMap(): high-level map builder
  • buildCatalog(): generic catalog builder (source="usgs" | "gcmt" | "isc")
  • buildUSGSCatalog(), buildGCMTCatalog(), buildISCCatalog()
• Faults & auxiliary data
  • buildGEMActiveFaults(), buildUSGSQuaternaryFaults(), buildEFSM20Faults()
• Cache management
  • downloadAllCatalogs(), updateAllCatalogs()
  • updateUSGSCatalog(), updateGCMTCatalog(), updateISCCatalog()
  • updateGEMActiveFaults(), updateUSGSQuaternaryFaults(), updateEFSM20Faults()
  • get_cache_dir(), getMasterIndexPath(), clear_cache()
• Core classes & configuration
  • MapConfig, EventConfig, FaultConfig, StationConfig
  • USGSCatalog, GCMTCatalog, EventMap
  • Constants: EARTH_RADIUS_KM, TILE_LAYERS, calculate_zoom_level()

GMDB hydration is available through buildMap(..., gmdb_index_path=...). getMasterIndexPath() resolves the bundled/cache RawMasterIndex.csv snapshot lazily so users do not need a local gmdb.v2 checkout. gmsp/gmdb.v2 remains the source of truth for rebuilding that package seed. The GMDB snapshot is release-versioned package data, not a daily online catalog like USGS/ISC/GCMT.

For the definitive parameter list and defaults, always refer to the Python docstrings:

from kashima.mapper import buildMap, buildCatalog
help(buildMap)
help(buildCatalog)

API help

• Python's built-in tools, for example python -m pydoc kashima.mapper.buildMap or help(buildMap) / help(buildCatalog) from an interactive session.
• The scripts under examples/mapper/ illustrate end-to-end workflows and advanced configuration.

Command-line interface / man page

At the moment kashima is a Python library only: it does not install a standalone kashima command and does not ship a Unix man page.

For built-in help, use Python's introspection:

# From the shell
python -m pydoc kashima.mapper.buildMap
python -m pydoc kashima.mapper.buildCatalog

or from a Python session:

from kashima.mapper import buildMap
help(buildMap)

Dependencies

Core runtime dependencies (installed automatically by pip install kashima):

• Python (>= 3.8)
• pandas, numpy, folium, geopandas, pyproj
• requests, branca, geopy, matplotlib
• obspy (beachball rendering), pyarrow (parquet cache)

Some fault builders download large GeoJSONs or talk to WFS services and therefore require a working internet connection the first time you run them.

Documentation (how to read)

Start at the documentation index:

• docs/index.md

User-facing topic pages:

• User guide (developer workflows)

Reference (maintainers):

• Naming conventions for kashima.mapper — what is public API vs. internal.
• Mapper layers plan — design notes for the ISC stations layer, faults and cache.

License

MIT License - see LICENSE.

Citation

@software{kashima2022,
  author = {Verri Kozlowski, Alejandro},
  title = {kashima: Interactive Seismic Event Mapping and Catalog Management},
  year = {2026},
  version = {3.3.1},
  url = {https://averrik.github.io/kashima/}
}

---

Author

Alejandro Verri Kozlowski
Email: [e-mail]
ORCID: 0000-0002-8535-1170
Affiliation: Universidad de Buenos Aires, Facultad de Ingeniería