Skip to content

Commit 640e711

Browse files
rdhyeeclaude
rdhyee
and
claude
authored
Enhance tutorials landing page and vocabularies page (#93)
Tutorials landing (tutorials/index.qmd): - Add "What's in the Data?" table with source breakdown - Add data files table with links to data.isamples.org - Expand "Why Browser-Based?" with more detail - Add "For Developers" section with GitHub/Zenodo/query docs links Vocabularies page (models/index.qmd): - Add ARDC link as vocabulary source of truth - Add back-links to Architecture, Requirements, and Metadata Model - Wrap core vocabularies in collapsible callout - Clean up taxonomy descriptions Addresses #87 (tutorials landing), plus metadata back-links and ARDC link from wireframe delta items. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent f811fc2 commit 640e711

2 files changed

Lines changed: 58 additions & 29 deletions

File tree

‎models/index.qmd‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -21,26 +21,33 @@ listing:
2121
number-sections: false
2222
---
2323

24-
see [description of model](https://isamplesorg.github.io/metadata/) at https://isamplesorg.github.io/metadata/
24+
See the [iSamples Metadata Model](https://isamplesorg.github.io/metadata/) for the full schema documentation.
2525

26-
## Taxonomies
26+
::: {.callout-tip}
27+
### Vocabulary Source of Truth
28+
The authoritative versions of iSamples vocabularies are maintained as RDF/SKOS files in the [iSamples GitHub repositories](https://github.com/isamplesorg/). Vocabulary terms are also registered with the [Australian Research Data Commons (ARDC) Research Vocabularies](https://vocabs.ardc.edu.au/).
29+
:::
2730

28-
One of the foundations for interoperability of iSamples material sample descriptions is the definition of vocabularies for the categorization of sample type. There are three core vocabularies for different aspects of sample type: material sample type, material type, and sampled feature type. Each vocabulary is maintained as an RDF file using the SKOS vocabulary, with hierarchical relationships using [`SKOS:broader`](https://www.w3.org/2009/08/skos-reference/skos.html#broader). In order to be domain agnostic, these core taxonomies cover a small set of top level terms. The taxonomies may be extended as necessary to support more specialized domains by relating additional terms using `SKOS:broader` and `SKOS:narrower`.
31+
## Taxonomies {.unnumbered}
2932

30-
The iSamples core taxonomies are controlled vocabularies with terms related by [`SKOS:broader`](https://www.w3.org/2009/08/skos-reference/skos.html#broader) and [`SKOS:narrower`](https://www.w3.org/2009/08/skos-reference/skos.html#narrower). In order to be domain agnostic, the core taxonomies cover a small set of top level terms. The taxonomies may be extended as necessary to support more specialized domains by relating additional terms using `SKOS:broader` and `SKOS:narrower`.
33+
One of the foundations for interoperability of iSamples material sample descriptions is the definition of vocabularies for the categorization of sample type. There are three core vocabularies for different aspects of sample type: material sample type, material type, and sampled feature type. Each vocabulary is maintained as an RDF file using the SKOS vocabulary, with hierarchical relationships using [`SKOS:broader`](https://www.w3.org/2009/08/skos-reference/skos.html#broader). In order to be domain agnostic, these core taxonomies cover a small set of top level terms. The taxonomies may be extended as necessary to support more specialized domains by relating additional terms using `SKOS:broader` and `SKOS:narrower`.
3134

3235
The iSamples taxonomies are used to characterize three fundamental concepts pertaining to physical samples:
3336

34-
1. The "iSamples Materials vocabulary" is a taxonomy of terms used to categorize the composition of a physical sample, that is "What material is the sample composed of?"
35-
2. The "Sampled Feature Type Vocabulary" is a taxonomy of terms used to indicate what the sample is representative of.
36-
3. The "iSamples Specimen Type Vocabulary" is a taxonomy of broad categories that classify what type of spcimen the physical sample record represents.
37+
1. The **Materials Vocabulary** categorizes the composition of a physical sample ("What material is the sample composed of?")
38+
2. The **Sampled Feature Type Vocabulary** indicates what the sample is representative of
39+
3. The **Specimen Type Vocabulary** classifies what type of specimen the physical sample record represents
3740

38-
Three taxonomies are currently defined :
41+
::: {.callout-note collapse="true"}
42+
## Core Vocabularies
3943

40-
[Material Sample (specimen) Type Vocabulary](generated/vocabularies/material_sample_object_type.html)
41-
42-
[Materials Vocabulary](generated/vocabularies/material_type.html)
43-
44-
[Sampled Feature (context) Type vocabulary](generated/vocabularies/sampled_feature_type.html)
44+
- [Material Sample (specimen) Type Vocabulary](generated/vocabularies/material_sample_object_type.html)
45+
- [Materials Vocabulary](generated/vocabularies/material_type.html)
46+
- [Sampled Feature (context) Type vocabulary](generated/vocabularies/sampled_feature_type.html)
47+
:::
4548

49+
## Related Pages {.unnumbered}
4650

51+
- [Architecture Overview](../design/index.qmd) — system principles and architecture
52+
- [Requirements](../design/requirements.html) — 18 use cases and requirements
53+
- [Metadata Model](https://isamplesorg.github.io/metadata/) — schema and data model documentation

‎tutorials/index.qmd‎

Lines changed: 38 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,52 @@
11
---
22
title: "Tutorials"
3+
subtitle: "Learn to explore 6.7 million physical samples from scientific collections worldwide using modern browser-based tools."
4+
number-sections: false
35
---
46

5-
Learn to explore **6.7 million physical samples** from scientific collections worldwide using modern browser-based tools.
6-
7-
## Start Here
7+
## Start Here {.unnumbered}
88

99
| Tutorial | What You'll Learn |
1010
|----------|-------------------|
11-
| [**Interactive Explorer**](isamples_explorer.qmd) | Search and filter samples with faceted search, view on 3D globe |
12-
| [**Deep-Dive Analysis**](zenodo_isamples_analysis.qmd) | Comprehensive DuckDB-WASM analysis with Observable JS |
13-
| [**3D Globe Visualization**](parquet_cesium_isamples_wide.qmd) | Cesium-based visualization of all iSamples data |
14-
| [**Technical: Narrow vs Wide**](narrow_vs_wide_performance.qmd) | Schema comparison and performance benchmarks |
11+
| [**Interactive Explorer**](isamples_explorer.qmd) | Search and filter samples with faceted search, view results on a 3D globe |
12+
| [**Deep-Dive Analysis**](zenodo_isamples_analysis.qmd) | Comprehensive DuckDB-WASM analysis with Observable JS — charts, maps, statistics |
13+
| [**3D Globe Visualization**](parquet_cesium_isamples_wide.qmd) | Cesium-based progressive visualization with H3 spatial clustering |
14+
| [**Technical: Narrow vs Wide**](narrow_vs_wide_performance.qmd) | Schema comparison and performance benchmarks for the PQG data formats |
15+
16+
## What's in the Data? {.unnumbered}
17+
18+
| Source | Samples | Focus |
19+
|--------|---------|-------|
20+
| **SESAR** | 4.6M | Earth science — rocks, minerals, sediments, soils |
21+
| **OpenContext** | 1M | Archaeology — artifacts, excavation materials |
22+
| **GEOME** | 605K | Biology — genomic and tissue specimens |
23+
| **Smithsonian** | 322K | Natural history — museum collections |
1524

16-
## Data Sources
25+
## Data Files {.unnumbered}
1726

18-
All tutorials use **geoparquet files** - no server required:
27+
All data is hosted on [`data.isamples.org`](https://data.isamples.org) with HTTP range request support — DuckDB-WASM only downloads the bytes it needs.
1928

20-
- **iSamples Full Dataset**: ~280 MB wide format, 6.7M samples from SESAR, OpenContext, GEOME, Smithsonian
21-
- **Available via**: Cloudflare R2 with HTTP range requests
29+
| File | Size | Description |
30+
|------|------|-------------|
31+
| [Wide format](https://data.isamples.org/isamples_202601_wide.parquet) | 278 MB | One row per entity, all sources — primary file for tutorials |
32+
| [Wide + H3](https://data.isamples.org/isamples_202601_wide_h3.parquet) | 292 MB | Wide format with H3 spatial indices for globe visualizations |
33+
| [Facet summaries](https://data.isamples.org/isamples_202601_facet_summaries.parquet) | 2 KB | Pre-computed filter counts — loads instantly |
34+
| [H3 clusters (res4)](https://data.isamples.org/isamples_202601_h3_summary_res4.parquet) | 0.6 MB | Zoomed-out globe view |
2235

23-
## Why Browser-Based?
36+
## Why Browser-Based? {.unnumbered}
2437

2538
Our approach using **geoparquet + DuckDB-WASM** provides:
2639

27-
- ✅ **Universal access** - No installation, works in any browser
28-
- ✅ **Fast analysis** - 5-10x faster than downloading full datasets
29-
- ✅ **Memory efficient** - Analyze 300MB using <100MB browser memory
30-
- ✅ **Minimal transfer** - Only download the columns/rows you need
40+
- **Universal access** — No installation, works in Chrome, Firefox, Edge, Safari, and Brave
41+
- **Fast analysis** — 5-10x faster than downloading full datasets
42+
- **Memory efficient** — Analyze 300MB datasets using <100MB browser memory
43+
- **Minimal transfer** — HTTP range requests download only the columns and rows you need (typically <1 MB to start)
44+
- **Reproducible** — All code is visible and foldable on tutorial pages
45+
46+
## For Developers {.unnumbered}
47+
48+
All tutorial source code is on [GitHub](https://github.com/isamplesorg/isamplesorg.github.io/tree/main/tutorials). Want to build your own analysis? Fork the repo, modify a `.qmd` file, and run `quarto preview`.
49+
50+
- [GitHub repositories](https://github.com/isamplesorg/) — all source code and data pipelines
51+
- [Zenodo community](https://zenodo.org/communities/isamples) — archived datasets for reproducible research
52+
- [Query architecture](https://github.com/isamplesorg/isamplesorg.github.io/issues/82) — how the Explorer queries work under the hood

0 commit comments

Comments
 (0)