Installation Guide

This guide will walk you through installing PyLithics on your system. PyLithics requires Python 3.8 or greater and works on macOS, Windows, and Linux.

System Requirements

• Python: Version 3.8 or higher
• Operating System:
• macOS 10.14 or later
• Windows 10 or later
• Linux (Ubuntu 18.04+, CentOS 7+, or equivalent)
• Memory: Minimum 4GB RAM (8GB recommended for large datasets)
• Storage: 500MB for installation plus space for your data

Step 1: Verify Prerequisites

Before installing PyLithics, ensure you have Python and Git installed on your system.

Check Python Installation

macOS & LinuxWindows

# Check Python version (should be 3.8+)
python3 --version

# If not installed, install Python
# macOS (using Homebrew - install from https://brew.sh/)
brew install python@3.11

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv

# CentOS/RHEL
sudo yum install python3 python3-pip

# Check Python version (should be 3.8+)
python --version

# If not installed, download from https://python.org
# Make sure to check "Add Python to PATH" during installation

Check Git Installation

macOS & LinuxWindows

# Check Git version
git --version

# If not installed
# macOS (using Homebrew - install from https://brew.sh/)
brew install git

# Ubuntu/Debian
sudo apt-get install git

# CentOS/RHEL
sudo yum install git

# Check Git version
git --version

# If not installed, download from https://git-scm.com/

Python Version

PyLithics requires Python 3.8 or higher. If you have an older version, please upgrade before proceeding.

Step 2: Set Up a Virtual Environment

We strongly recommend using a virtual environment to avoid conflicts with other Python packages.

macOS & LinuxWindows

# Create virtual environment
python3 -m venv palaeo

# Activate virtual environment
source palaeo/bin/activate

# Create virtual environment
python -m venv palaeo

# Allow script execution (may require administrator privileges)
Set-ExecutionPolicy Unrestricted -Scope Process

# Activate virtual environment
.\palaeo\Scripts\activate

Virtual Environment Active

When your virtual environment is active, you'll see (palaeo) at the beginning of your command prompt.

Step 3: Clone the Repository

Clone the PyLithics repository from GitHub:

git clone https://github.com/alan-turing-institute/Palaeoanalytics.git
cd Palaeoanalytics

Choosing a Branch

• Stable Release: Use the main branch for the most recent tagged release (currently v2.0.0). This is what we recommend for almost everyone.
• In-Progress Work: Use the develop branch if you want to preview changes that are queued for the next release. May be less stable.

# For the stable release (recommended)
git checkout main

# For in-progress work
git checkout develop

To pin to a specific released version for reproducibility, check out the tag instead:

git checkout v2.0.0

Step 4: Install PyLithics

Install PyLithics and all its dependencies:

pip install .

This command will: - Install PyLithics as a package - Install all required dependencies listed in requirements.txt - Set up the pylithics command-line tool

Step 5: Verify Installation

Test that PyLithics is correctly installed by running it with no arguments:

pylithics

You should see the welcome splash — a chunky PyLithics logo above a Get-started panel listing the five common command patterns:

1. Quick start — analyze the bundled sample dataset
2. Run sample data and visualize — analyze and open the results dashboard
3. Open an existing run in the browser — re-open a previous analysis in the dashboard
4. Help & docs — pylithics --help and pylithics --docs
5. GitHub — the project repository URL

Copy whichever command you want to run next.

Optional: run the bundled sample dataset

To prove the full pipeline works end-to-end immediately after installing, run the second splash command:

pylithics --data_dir pylithics/data --meta_file pylithics/data/meta_data.csv --explore

This processes the bundled sample images and opens the interactive dashboard in your browser. If this completes without errors and the dashboard loads, your install is healthy.

Full CLI help

# Every flag, every option
pylithics --help

Updating PyLithics

To update to the latest version:

# Navigate to PyLithics directory
cd Palaeoanalytics

# Pull latest changes
git pull origin main

# Reinstall
pip install . --upgrade

Building Documentation Locally

Documentation tools are installed automatically with PyLithics. To build and view the documentation locally:

# Serve documentation locally at http://127.0.0.1:8000
pylithics --docs

Documentation Tools Included

MkDocs and related documentation dependencies are automatically installed with PyLithics, so no additional installation is needed.

Troubleshooting Installation

Python Version Issues

If you encounter Python version errors:

# Check your Python version
python --version

# If needed, install Python 3.8+ using your system's package manager
# macOS (using Homebrew)
brew install python@3.11

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3.11

# Windows - download from python.org

macOS-Specific Issues

For macOS users with OS versions below 10.14:

• Consider upgrading your OS to 10.14 or later
• If upgrade isn't possible, you may encounter build issues with some dependencies

Windows PowerShell Execution Policy

If you get execution policy errors on Windows:

# Run PowerShell as Administrator
Set-ExecutionPolicy RemoteSigned

# Or for current session only
Set-ExecutionPolicy Unrestricted -Scope Process

Missing Dependencies

If you encounter missing dependency errors:

# Upgrade pip first
pip install --upgrade pip

# Then reinstall with verbose output
pip install . -v

OpenCV Installation Issues

If OpenCV fails to install:

# Try installing OpenCV separately first
pip install opencv-python-headless>=4.8.0

# Then install PyLithics
pip install .

Uninstalling

To remove PyLithics:

# Uninstall PyLithics
pip uninstall pylithics

# Deactivate and remove virtual environment
deactivate
rm -rf palaeo/  # On Windows: rmdir /s palaeo

Next Steps

Now that PyLithics is installed, you're ready to:

1. Prepare your images
2. Set up metadata
3. Run your first analysis

For any installation issues not covered here, please check our troubleshooting guide or open an issue on GitHub.