Metadata-Version: 2.4
Name: crategraph
Version: 0.1.3
Summary: Researcher-friendly tools for loading, exploring, and visualising RO-Crate data as network graphs
Project-URL: Homepage, https://unimelbmdap.github.io/cdl2-rocrates/
Project-URL: Documentation, https://unimelbmdap.github.io/cdl2-rocrates/
Project-URL: Source, https://github.com/unimelbmdap/cdl2-rocrates
Project-URL: Issues, https://github.com/unimelbmdap/cdl2-rocrates/issues
Author: Melbourne Data Analytics Platform
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Sociology :: History
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.12
Requires-Dist: crategraph-forceatlas2>=0.1
Requires-Dist: grand-cypher>=1.0
Requires-Dist: markupsafe>=2.1
Requires-Dist: networkx>=3.4
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: rapidfuzz>=3.0
Provides-Extra: index
Requires-Dist: cryptography>=50.0.0; extra == 'index'
Requires-Dist: fastembed>=0.3; extra == 'index'
Requires-Dist: markitdown[audio-transcription,docx,outlook,pdf,pptx,xls,xlsx]>=0.1.7; extra == 'index'
Requires-Dist: sqlite-vec>=0.1; extra == 'index'
Requires-Dist: tokenizers>=0.15; extra == 'index'
Requires-Dist: tqdm>=4.65; extra == 'index'
Provides-Extra: inspect
Requires-Dist: cryptography>=50.0.0; extra == 'inspect'
Requires-Dist: markitdown[audio-transcription,docx,outlook,pdf,pptx,xls,xlsx]>=0.1.7; extra == 'inspect'
Provides-Extra: ohrm
Requires-Dist: pandas>=2.0; extra == 'ohrm'
Provides-Extra: okf
Requires-Dist: markdown-it-py>=3.0; extra == 'okf'
Requires-Dist: pyyaml>=6.0; extra == 'okf'
Provides-Extra: pyvis
Requires-Dist: pyvis>=0.3; extra == 'pyvis'
Provides-Extra: rdf
Requires-Dist: rdflib>=7.0; extra == 'rdf'
Description-Content-Type: text/markdown

# RO-Crate Analysis and Visualisation Tools

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21696059.svg)](https://doi.org/10.5281/zenodo.21696059)
[![Tests](https://github.com/unimelbmdap/cdl2-rocrates/actions/workflows/test.yml/badge.svg)](https://github.com/unimelbmdap/cdl2-rocrates/actions/workflows/test.yml)
![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://unimelbmdap.github.io/cdl2-rocrates/)
[![Milestones](https://img.shields.io/badge/milestones-view%20all-orange)](https://github.com/unimelbmdap/cdl2-rocrates/milestones)
![Status: beta](https://img.shields.io/badge/status-beta-yellow)

<p align="center">
  <img src="https://unimelbmdap.github.io/cdl2-rocrates/assets/umpc-hero.webp" alt="The University of Melbourne Perpetual Calendar RO-Crate rendered as a network graph with crategraph" width="720">
</p>

<p align="center"><em>The University of Melbourne Perpetual Calendar RO-Crate rendered as a network graph with crategraph.</em></p>

> [!NOTE]
> **Early development.** crategraph is pre-1.0 and still evolving. The core API is settling and
> no major redesigns are planned, but occasional breaking changes are still possible between
> versions as details are refined.
>
> If you rely on crategraph in your own work, pin a specific tag or commit so that upgrading is
> always a deliberate step.

## ARDC Community Data Lab Phase 2: Work Package 2

Tools for analysing and visualising research data collections stored in RO-Crates.

## About

RO-Crates offer a powerful format for preserving HASS and GLAM collections with curated metadata and linkage information. While existing tools focus on creating RO-Crates as archival objects, this project unlocks them for active research use.

This project develops accessible tools for researchers to:

- Analyse network relationships and metadata within and across RO-Crates
- Visualise collections interactively, both online and offline
- Understand and work with RO-Crate workflows through documentation and training

A set of RO-Crates converted from OHRM databases are available on FigShare: https://figshare.unimelb.edu.au/projects/OHRM_Upload_Project/230466

## Project Goals

The project focuses on use-case driven development, prioritising specific research contexts for HASS and GLAM collections. Initial work will target:

- Visualisation of linkages between RO-Crates
- Visualisation of contents within RO-Crates

## Background

This work builds on existing University of Melbourne projects and external collaborations that have developed specialised RO-Crate tools and workflows, including work derived from former Online Heritage Resource Manager projects.

## Survey

We are excited to collaborate with researchers from various backgrounds. By taking this short survey, you're helping us co-design something that reflects and supports the way researchers work. We encourage you to share this survey with colleagues and research networks beyond your institution.

[Feedback on WP2: working with RO Crate](https://q.surveys.unimelb.edu.au/jfe/form/SV_3rc5LLpCErEMpn0)

## Quick Start

Install crategraph from PyPI:

```bash
python -m pip install crategraph
```

**Interactive Python shell:**

```bash
python
```

```python
>>> from crategraph import Crate
>>> crate = Crate("path/to/my-collection/")
>>> crate.entities
>>> crate.relationships
```

**Jupyter notebook:**

```bash
python -m pip install jupyter
jupyter notebook
```

## Documentation

Full documentation, guides, and API reference are published at **[unimelbmdap.github.io/cdl2-rocrates](https://unimelbmdap.github.io/cdl2-rocrates/)**.

- **[Getting Started](https://unimelbmdap.github.io/cdl2-rocrates/getting-started/)** — install, load a crate, and take a first look.
- **[Tutorials](https://unimelbmdap.github.io/cdl2-rocrates/tutorials/)** — task-focused guides, including [Visualising a Collection](https://unimelbmdap.github.io/cdl2-rocrates/tutorials/visualising-a-collection/), [From Graph to DataFrame](https://unimelbmdap.github.io/cdl2-rocrates/tutorials/from-graph-to-dataframe/), and [Searching a Collection](https://unimelbmdap.github.io/cdl2-rocrates/tutorials/searching-a-collection/). A one-page [cheat sheet](https://unimelbmdap.github.io/cdl2-rocrates/tutorials/crategraph-cheatsheet/) covers the common commands.
- **[Case Studies](https://unimelbmdap.github.io/cdl2-rocrates/case-studies/)** — real collections explored end to end, such as [Navigating the Encyclopedia of Australian Science](https://unimelbmdap.github.io/cdl2-rocrates/case-studies/questions-for-a-collection-eoas/) and the [Australian Radio Talkback corpus](https://unimelbmdap.github.io/cdl2-rocrates/case-studies/australian-radio-talkback/).
- **[API Reference](https://unimelbmdap.github.io/cdl2-rocrates/api/)** and **[Architecture](https://unimelbmdap.github.io/cdl2-rocrates/architecture/)** — for extending crategraph or understanding its internals.

## Development Setup

### Prerequisites

- Python 3.12 or later
- [uv](https://docs.astral.sh/uv/) package manager

### Installation

```bash
# Clone the repository
git clone https://github.com/unimelbmdap/cdl2-rocrates.git
cd cdl2-rocrates

# Install dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install
```

### Running Tests

```bash
uv run pytest
```

### Code Quality

This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting, enforced via pre-commit hooks.

```bash
# Run pre-commit checks manually
uv run pre-commit run --all-files

# Run linter
uv run ruff check .

# Run formatter
uv run ruff format .
```

## Licence

Licensed under the Apache License, Version 2.0. See the [LICENSE](https://github.com/unimelbmdap/cdl2-rocrates/blob/main/LICENSE) file for the full terms.

## AI Attribution

[![AI Attribution: Human-AI blend — content edits, new content, human-initiated, reviewed; models Opus, Codex](https://unimelbmdap.github.io/cdl2-rocrates/assets/ai-attribution.svg)](https://aiattribution.github.io/statements/AIA-HAb-CeNc-Hin-R-?model=Opus%2C%20Codex)
