# SEED-vault
#### SEED Vault is a cross platform GUI utility which can search, view and download seismic data from FDSN servers
- Download & view EQ arrival data via a station-to-event OR an event-to-station search
- Quickly download and archive bulk continuous data, saving your progress along the way
- View and plot event arrivals
- A CLI scripting tool to automate common jobs
- Search, export, or import earthquake event catalogs and station metadata
- Download restricted/embargoed data by storing auth passwords in local config
- Add and use custom FDSN servers
- Saves all downloaded data as miniseed in a local SDS database to speed up future retrievals
- Local sqlite3 database editor
- Load and save search parameters and configuration
Runs on:
- Linux
- Windows
- MacOS
Can run:
- As web service
- From the command line (CLI)
#### User Guide
https://auscope.github.io/seed-vault
---
### Requirements
- 8 GB RAM
- Python >= 3.10
- ObsPy (>=1.4.1), Streamlit (>=1.39), Plotly (>-5.24), Pandas (>=2.2.2), Matplotlib (>=3.8.5)
# Install via pip (easy way)
```
python3 -m pip install seed-vault
```
NB:
1. If you get an *"error: externally-managed-environment"* error, you will need to install and activate a new Python environment
e.g.
```
python3 -m venv ./venv
. ./venv/bin/activate
```
4. Assumes python & 'pip', 'venv' packages are installed
e.g. for Ubuntu, as root:
```
apt update
apt install -y python3 python3-dev python3-pip python3-venv
```
# Install from source (if you insist!)
### Step 1: Clone repository
```bash
git clone https://github.com/AuScope/seed-vault.git
```
### Step 2: Setup and run
Then can build via pip:
```
python3 -m pip install ./seed-vault
```
Or,
```
#### Linux/MacOS
cd seed-vault
source setup.sh
source run.sh
```
#### Windows
Open a powershell and run following commands:
```
cd seed-vault
.\setup-win.ps1
.\run-win.ps1
```
**NOTES:**
1. Requires get, sudo & python3 software packages
e.g. for Ubuntu you may need install (as root):
```
apt update
apt install -y git sudo
apt install -y python3 python3-dev python3-pip python3-venv
```
## Project Folder structure
```
seed-vault/
│
├── seed_vault/ # Python package containing application code
│ ├── docs/ # Documentation
│ ├── models/ # Python modules for data models
│ ├── scripts/ # Example CLI scripts
│ ├── service/ # Services for logic and backend processing
│ ├── tests/ # Test data and utilities
│ ├── ui/ # UI components (Streamlit files)
│ ├── utils/ # Utility functions and helpers
│
└── pyproject.toml # Project configuration file
```
---
# Development
## Setting up with Poetry
If you look to further develop this app, it is highly recommended to set up the project with `poetry`. Follow the steps below to set up using `poetry`.
### Install poetry
Refer to this link: https://python-poetry.org/docs/
Alternatively,
**Linux**
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
then, add following to .bashrc:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
**Windows**
powershell:
```powershell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
```
then, add poetry to your system path. It should be located here:
```
%USERPROFILE%\.poetry\bin
```
**Optional**
To configure poetry to create `.venv` inside project folder, run following:
```
poetry config virtualenvs.in-project true
```
## Install pyenv (Optional)
This project uses python 3.10.\*. If your base python is a different version (check via `python --version`), you may get errors when trying to install via poetry. Use pyenv to manage this.
**Linux**
Install the required packages for building Python with the following command
```
sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev
xz-utils tk-dev libffi-dev liblzma-dev git
```
Then, install pyenv
```
curl https://pyenv.run | bash
```
After installation, add following to `.bashrc`:
```
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
```
Run .bashrc to get things updated: `source ~/.bashrc`
### Start the project
Install python 3.12.\* if you have a different version locally:
```
pyenv install 3.12.0
pyenv global 3.12.0
```
Confirm your python version: `python --version`
Install the packages using following.
```
poetry install
```
Start the project:
```
poetry shell
```
To run the app:
```
streamlit run seed_vault/ui/main.py
```
Alternatively, command line is configured for this project. You can also run the app, simply by:
```
seed-vault start
```
## Build Project
### Build Python Library
```
poetry build
```
### Build Installers
_Need to be added_
## Docker Development
To develop and run the application using Docker, follow these steps:
### Prerequisites
- Install Docker Application on your system
### Build and Run the Docker Container
1. Navigate to the project root directory:
```bash
cd seed-vault
```
2. Build and run the Docker container:
```bash
docker compose up --build
```
The application should now be running and accessible at `http://localhost:8501`.
## Export poetry packages to requirements.txt
```
poetry export -f requirements.txt --output requirements.txt --without-hashes
```
## Publishing the lib to test: pypi
Define a package name in pyproject.toml (e.g. `seed-vault`).
Then, run following commands
```bash
poetry build
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry config pypi-token.test-pypi <YOUR PYPI TOKEN>
poetry publish -r testpypi
```
To install from pypi-test:
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple seed-vault
```
Note: include both `test` and `official` indexes.
## Publishing the lib to official: pypi:
```
poetry build
poetry config pypi-token.pypi <YOUR_PYPI_TOKEN>
poetry publish
```
## Unit test
The repository includes a number of unit tests. These tests only covers
the main functions in `seed_vault.service.seismoloader` as these are the
core logics adopted in the app.
### Run tests
To run the test units:
1. Running only mockup tests
```
poetry run pytest
```
2. Running tests with actual FDSN API calls
```
poetry run pytest --run-real-fdsn
```
3. Generate coverage report:
**to include the whole module:**
```
poetry run pytest --run-real-fdsn --cov=seed_vault --cov-report=html
```
**to only include `service/*` tests:**
```
poetry run pytest --run-real-fdsn --cov=seed_vault --cov-config=.coveragerc --cov-report=html
```
4. Generate coverage badge
```
poetry run coverage-badge -o coverage.svg
```
Raw data
{
"_id": null,
"home_page": null,
"name": "seed-vault",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "seismology, earthquakes, seismometers, FDSN, ObsPy, miniseed",
"author": "Robert Pickle",
"author_email": "robert.pickle@anu.edu.au",
"download_url": "https://files.pythonhosted.org/packages/8d/48/d92c92704621b4bc12eda55b0eeaf7783ca8e5ac70e7a5fd7520a322f020/seed_vault-1.0.10.tar.gz",
"platform": null,
"description": "# SEED-vault\n\n\n\n#### SEED Vault is a cross platform GUI utility which can search, view and download seismic data from FDSN servers\n\n- Download & view EQ arrival data via a station-to-event OR an event-to-station search\n- Quickly download and archive bulk continuous data, saving your progress along the way\n- View and plot event arrivals\n- A CLI scripting tool to automate common jobs\n- Search, export, or import earthquake event catalogs and station metadata\n- Download restricted/embargoed data by storing auth passwords in local config\n- Add and use custom FDSN servers\n- Saves all downloaded data as miniseed in a local SDS database to speed up future retrievals\n- Local sqlite3 database editor\n- Load and save search parameters and configuration\n\nRuns on:\n\n- Linux\n- Windows\n- MacOS\n\nCan run:\n\n- As web service\n- From the command line (CLI)\n\n#### User Guide \n\nhttps://auscope.github.io/seed-vault\n\n---\n\n### Requirements\n\n- 8 GB RAM\n- Python >= 3.10\n- ObsPy (>=1.4.1), Streamlit (>=1.39), Plotly (>-5.24), Pandas (>=2.2.2), Matplotlib (>=3.8.5)\n\n# Install via pip (easy way)\n\n```\npython3 -m pip install seed-vault\n```\n\nNB:\n\n1. If you get an *\"error: externally-managed-environment\"* error, you will need to install and activate a new Python environment\n \n e.g.\n ```\n python3 -m venv ./venv\n . ./venv/bin/activate\n ```\n\n4. Assumes python & 'pip', 'venv' packages are installed\n\n e.g. for Ubuntu, as root:\n ```\n apt update\n apt install -y python3 python3-dev python3-pip python3-venv\n ```\n\n# Install from source (if you insist!)\n\n### Step 1: Clone repository\n\n```bash\ngit clone https://github.com/AuScope/seed-vault.git\n```\n\n### Step 2: Setup and run\n\nThen can build via pip:\n\n```\npython3 -m pip install ./seed-vault\n```\n\nOr,\n\n```\n#### Linux/MacOS\ncd seed-vault\nsource setup.sh\nsource run.sh\n```\n\n#### Windows\n\nOpen a powershell and run following commands:\n\n```\ncd seed-vault\n.\\setup-win.ps1\n.\\run-win.ps1\n```\n\n**NOTES:**\n\n1. Requires get, sudo & python3 software packages\n\n e.g. for Ubuntu you may need install (as root):\n ```\n apt update\n apt install -y git sudo\n apt install -y python3 python3-dev python3-pip python3-venv\n ```\n\n## Project Folder structure\n\n```\nseed-vault/\n\u2502\n\u251c\u2500\u2500 seed_vault/ # Python package containing application code\n\u2502 \u251c\u2500\u2500 docs/ # Documentation\n\u2502 \u251c\u2500\u2500 models/ # Python modules for data models\n\u2502 \u251c\u2500\u2500 scripts/ # Example CLI scripts\n\u2502 \u251c\u2500\u2500 service/ # Services for logic and backend processing\n\u2502 \u251c\u2500\u2500 tests/ # Test data and utilities\n\u2502 \u251c\u2500\u2500 ui/ # UI components (Streamlit files)\n\u2502 \u251c\u2500\u2500 utils/ # Utility functions and helpers\n\u2502\n\u2514\u2500\u2500 pyproject.toml # Project configuration file\n```\n\n---\n\n# Development\n\n## Setting up with Poetry\n\nIf you look to further develop this app, it is highly recommended to set up the project with `poetry`. Follow the steps below to set up using `poetry`.\n\n### Install poetry\n\nRefer to this link: https://python-poetry.org/docs/\n\nAlternatively,\n\n**Linux**\n\n```bash\ncurl -sSL https://install.python-poetry.org | python3 -\n```\n\nthen, add following to .bashrc:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n**Windows**\npowershell:\n\n```powershell\n(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -\n```\n\nthen, add poetry to your system path. It should be located here:\n\n```\n%USERPROFILE%\\.poetry\\bin\n```\n\n**Optional**\nTo configure poetry to create `.venv` inside project folder, run following:\n\n```\npoetry config virtualenvs.in-project true\n```\n\n## Install pyenv (Optional)\n\nThis project uses python 3.10.\\*. If your base python is a different version (check via `python --version`), you may get errors when trying to install via poetry. Use pyenv to manage this.\n\n**Linux**\n\nInstall the required packages for building Python with the following command\n\n```\nsudo apt update\n\nsudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev\nlibreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev\nxz-utils tk-dev libffi-dev liblzma-dev git\n```\n\nThen, install pyenv\n\n```\ncurl https://pyenv.run | bash\n```\n\nAfter installation, add following to `.bashrc`:\n\n```\nexport PATH=\"$HOME/.pyenv/bin:$PATH\"\n\neval \"$(pyenv init --path)\"\n\neval \"$(pyenv init -)\"\n```\n\nRun .bashrc to get things updated: `source ~/.bashrc`\n\n### Start the project\n\nInstall python 3.12.\\* if you have a different version locally:\n\n```\npyenv install 3.12.0\n\npyenv global 3.12.0\n```\n\nConfirm your python version: `python --version`\n\nInstall the packages using following.\n\n```\npoetry install\n```\n\nStart the project:\n\n```\npoetry shell\n```\n\nTo run the app:\n\n```\nstreamlit run seed_vault/ui/main.py\n```\n\nAlternatively, command line is configured for this project. You can also run the app, simply by:\n\n```\nseed-vault start\n```\n\n## Build Project\n\n### Build Python Library\n\n```\npoetry build\n```\n\n### Build Installers\n\n_Need to be added_\n\n## Docker Development\n\nTo develop and run the application using Docker, follow these steps:\n\n### Prerequisites\n\n- Install Docker Application on your system\n\n### Build and Run the Docker Container\n\n1. Navigate to the project root directory:\n\n```bash\ncd seed-vault\n```\n\n2. Build and run the Docker container:\n\n```bash\ndocker compose up --build\n```\n\nThe application should now be running and accessible at `http://localhost:8501`.\n\n## Export poetry packages to requirements.txt\n\n```\npoetry export -f requirements.txt --output requirements.txt --without-hashes\n```\n\n## Publishing the lib to test: pypi\n\nDefine a package name in pyproject.toml (e.g. `seed-vault`).\nThen, run following commands\n\n```bash\npoetry build\npoetry config repositories.testpypi https://test.pypi.org/legacy/\npoetry config pypi-token.test-pypi <YOUR PYPI TOKEN>\npoetry publish -r testpypi\n```\n\nTo install from pypi-test:\n\n```bash\npip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple seed-vault\n```\n\nNote: include both `test` and `official` indexes.\n\n## Publishing the lib to official: pypi:\n\n```\npoetry build\npoetry config pypi-token.pypi <YOUR_PYPI_TOKEN>\npoetry publish\n```\n\n## Unit test\n\nThe repository includes a number of unit tests. These tests only covers\nthe main functions in `seed_vault.service.seismoloader` as these are the\ncore logics adopted in the app.\n\n### Run tests\n\nTo run the test units:\n\n1. Running only mockup tests\n\n```\npoetry run pytest\n```\n\n2. Running tests with actual FDSN API calls\n\n```\npoetry run pytest --run-real-fdsn\n```\n\n3. Generate coverage report:\n\n**to include the whole module:**\n\n```\npoetry run pytest --run-real-fdsn --cov=seed_vault --cov-report=html\n```\n\n**to only include `service/*` tests:**\n\n```\npoetry run pytest --run-real-fdsn --cov=seed_vault --cov-config=.coveragerc --cov-report=html\n```\n\n4. Generate coverage badge\n\n```\npoetry run coverage-badge -o coverage.svg\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "GUI and CLI utility to interface with FDSN seismic data centers to search, download, and archive event and continuous waveform data.",
"version": "1.0.10",
"project_urls": null,
"split_keywords": [
"seismology",
" earthquakes",
" seismometers",
" fdsn",
" obspy",
" miniseed"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8b28965260da53b1967e448a4157b3f50157c01f42ac949722a9a73090444487",
"md5": "9f11014ab871bf84722ef0e1a682e46c",
"sha256": "09018c5725a3f15a12794f00fe6d1e02ed24ae1f1d1c02027359b7f029769774"
},
"downloads": -1,
"filename": "seed_vault-1.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f11014ab871bf84722ef0e1a682e46c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 142286,
"upload_time": "2025-09-01T00:57:09",
"upload_time_iso_8601": "2025-09-01T00:57:09.862469Z",
"url": "https://files.pythonhosted.org/packages/8b/28/965260da53b1967e448a4157b3f50157c01f42ac949722a9a73090444487/seed_vault-1.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8d48d92c92704621b4bc12eda55b0eeaf7783ca8e5ac70e7a5fd7520a322f020",
"md5": "07fb79cdb104eab946b4efe1152daa7c",
"sha256": "dd66f2cb4a0b95e2b336fecabb590c859c4308569eab2a5afd3f7471db0fecd2"
},
"downloads": -1,
"filename": "seed_vault-1.0.10.tar.gz",
"has_sig": false,
"md5_digest": "07fb79cdb104eab946b4efe1152daa7c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 124499,
"upload_time": "2025-09-01T00:57:11",
"upload_time_iso_8601": "2025-09-01T00:57:11.650084Z",
"url": "https://files.pythonhosted.org/packages/8d/48/d92c92704621b4bc12eda55b0eeaf7783ca8e5ac70e7a5fd7520a322f020/seed_vault-1.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 00:57:11",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "seed-vault"
}
JSON