From c7722f7398ac137d42514e08fee52ec7b1b2cd0c Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 09:29:09 +0100 Subject: [PATCH 1/9] Improve link layout --- docs/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification.md b/docs/specification.md index 21e6e6b1..b2f231e9 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -1,6 +1,6 @@ # Pretrained Model release v1.0 -This changelog is a summary of the changes to the pretrained model weights for the Clay model. We follow the "Stanford [Foundation Model Transparency Index](https://github.com/stanford-crfm/fmti)" +This changelog is a summary of the changes to the pretrained model weights for the Clay model. We follow the "[Stanford Foundation Model Transparency Index](https://github.com/stanford-crfm/fmti)" Model weights released on 2024/05/12. From 31ea9ee623ea0db2075623c84db202a502370a6e Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 10:25:20 +0100 Subject: [PATCH 2/9] Removed stacchip dependency --- docs/clay-v1-wall-to-wall.ipynb | 1161 ++----------------------------- 1 file changed, 57 insertions(+), 1104 deletions(-) diff --git a/docs/clay-v1-wall-to-wall.ipynb b/docs/clay-v1-wall-to-wall.ipynb index 4dcac9b3..378aeb43 100644 --- a/docs/clay-v1-wall-to-wall.ipynb +++ b/docs/clay-v1-wall-to-wall.ipynb @@ -21,7 +21,7 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 1, "id": "add63cd9", "metadata": {}, "outputs": [], @@ -34,7 +34,7 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 2, "id": "6a17b8a8-a9c6-4053-833e-de97287fae49", "metadata": {}, "outputs": [], @@ -53,7 +53,6 @@ "from rasterio.enums import Resampling\n", "from shapely import Point\n", "from sklearn import decomposition, svm\n", - "from stacchip.processors.prechip import normalize_timestamp\n", "from torchvision.transforms import v2\n", "\n", "from src.model import ClayMAEModule" @@ -70,7 +69,7 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 3, "id": "08d7787d-1506-4de7-89dc-c1054910acf7", "metadata": {}, "outputs": [], @@ -95,7 +94,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 4, "id": "2e80743c-7c77-459b-9984-f6c26cdff549", "metadata": {}, "outputs": [ @@ -155,7 +154,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 5, "id": "0f3573b5-5a00-47d9-a648-5c4d7cd2c996", "metadata": {}, "outputs": [], @@ -194,7 +193,7 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 6, "id": "8b8d3824-e48c-4f9d-9c7b-181c0800f96f", "metadata": {}, "outputs": [ @@ -202,708 +201,38 @@ "name": "stdout", "output_type": "stream", "text": [ - "Working with stack of size (12, 4, 256, 256)\n" + " Size: 13MB\n", + "dask.array\n", + "Coordinates: (12/53)\n", + " * time (time) datetime64[ns] 96B 2018-0...\n", + " id (time) \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "
<xarray.DataArray 'stackstac-7cbad7c129d678be53c9b6676bee564b' (time: 12,\n",
-       "                                                                band: 4,\n",
-       "                                                                y: 256, x: 256)> Size: 13MB\n",
-       "array([[[[ 9136.,  9232.,  9544., ...,  1258.,  1120.,   930.],\n",
-       "         [ 9616.,  9768.,  9840., ...,  1230.,  1208.,  1030.],\n",
-       "         [ 9992., 10008., 10000., ...,  1418.,  1336.,  1242.],\n",
-       "         ...,\n",
-       "         [  811.,   655.,   688., ...,   385.,   362.,   461.],\n",
-       "         [  798.,   675.,   727., ...,   394.,   415.,   402.],\n",
-       "         [  888.,   673.,   642., ...,   403.,   454.,   393.]],\n",
-       "\n",
-       "        [[ 8656.,  8656.,  8864., ...,  1500.,  1428.,  1220.],\n",
-       "         [ 9016.,  9160.,  9224., ...,  1546.,  1522.,  1360.],\n",
-       "         [ 9248.,  9328.,  9384., ...,  1620.,  1542.,  1482.],\n",
-       "         ...,\n",
-       "         [ 1010.,   831.,   853., ...,   277.,   276.,   336.],\n",
-       "         [ 1016.,   930.,   927., ...,   276.,   317.,   293.],\n",
-       "         [ 1112.,   885.,   827., ...,   299.,   369.,   293.]],\n",
-       "\n",
-       "        [[ 8416.,  8416.,  8640., ...,  1598.,  1466.,  1138.],\n",
-       "         [ 8744.,  8880.,  8928., ...,  1498.,  1522.,  1284.],\n",
-       "         [ 8952.,  8944.,  8960., ...,  1542.,  1478.,  1448.],\n",
-       "         ...,\n",
-       "...\n",
-       "         [  652.,   640.,   638., ...,   590.,   821.,  1008.],\n",
-       "         [  622.,   676.,   630., ...,   606.,  1092.,   726.],\n",
-       "         [  864.,   786.,   569., ...,   766.,  1068.,   630.]],\n",
-       "\n",
-       "        [[  201.,   213.,   195., ...,  1138.,  1058.,   749.],\n",
-       "         [  196.,   198.,   169., ...,   861.,   784.,   768.],\n",
-       "         [  216.,   178.,   191., ...,   870.,   806.,   820.],\n",
-       "         ...,\n",
-       "         [  857.,   838.,   846., ...,   622.,   800.,  1332.],\n",
-       "         [  922.,   848.,   771., ...,   786.,  1046.,   912.],\n",
-       "         [ 1118.,  1010.,   735., ...,   755.,   977.,   686.]],\n",
-       "\n",
-       "        [[ 3264.,  3352.,  3304., ...,  3160.,  3296.,  3376.],\n",
-       "         [ 3356.,  3300.,  3212., ...,  3188.,  3272.,  3064.],\n",
-       "         [ 3288.,  3372.,  3344., ...,  3136.,  3200.,  2932.],\n",
-       "         ...,\n",
-       "         [ 1320.,  1468.,  1298., ...,  2492.,  2556.,  3018.],\n",
-       "         [ 1630.,  1694.,  1250., ...,  2318.,  2684.,  2894.],\n",
-       "         [ 2190.,  2072.,  1288., ...,  2544.,  2942.,  2928.]]]],\n",
-       "      dtype=float32)\n",
-       "Coordinates: (12/53)\n",
-       "  * time                                     (time) datetime64[ns] 96B 2018-0...\n",
-       "    id                                       (time) <U24 1kB 'S2B_29SNB_20180...\n",
-       "  * band                                     (band) <U5 80B 'blue' ... 'nir'\n",
-       "  * x                                        (x) float64 2kB 5.366e+05 ... 5....\n",
-       "  * y                                        (y) float64 2kB 4.131e+06 ... 4....\n",
-       "    platform                                 (time) <U11 528B 'sentinel-2b' ....\n",
-       "    ...                                       ...\n",
-       "    gsd                                      int64 8B 10\n",
-       "    title                                    (band) <U20 320B 'Blue (band 2) ...\n",
-       "    common_name                              (band) <U5 80B 'blue' ... 'nir'\n",
-       "    center_wavelength                        (band) float64 32B 0.49 ... 0.842\n",
-       "    full_width_half_max                      (band) float64 32B 0.098 ... 0.145\n",
-       "    epsg                                     int64 8B 32629\n",
-       "Attributes:\n",
-       "    spec:        RasterSpec(epsg=32629, bounds=(536640.79691545, 4128000.7407...\n",
-       "    crs:         epsg:32629\n",
-       "    transform:   | 10.00, 0.00, 536640.80|\\n| 0.00,-10.00, 4130560.74|\\n| 0.0...\n",
-       "    resolution:  10
" - ], - "text/plain": [ - " Size: 13MB\n", - "array([[[[ 9136., 9232., 9544., ..., 1258., 1120., 930.],\n", - " [ 9616., 9768., 9840., ..., 1230., 1208., 1030.],\n", - " [ 9992., 10008., 10000., ..., 1418., 1336., 1242.],\n", - " ...,\n", - " [ 811., 655., 688., ..., 385., 362., 461.],\n", - " [ 798., 675., 727., ..., 394., 415., 402.],\n", - " [ 888., 673., 642., ..., 403., 454., 393.]],\n", - "\n", - " [[ 8656., 8656., 8864., ..., 1500., 1428., 1220.],\n", - " [ 9016., 9160., 9224., ..., 1546., 1522., 1360.],\n", - " [ 9248., 9328., 9384., ..., 1620., 1542., 1482.],\n", - " ...,\n", - " [ 1010., 831., 853., ..., 277., 276., 336.],\n", - " [ 1016., 930., 927., ..., 276., 317., 293.],\n", - " [ 1112., 885., 827., ..., 299., 369., 293.]],\n", - "\n", - " [[ 8416., 8416., 8640., ..., 1598., 1466., 1138.],\n", - " [ 8744., 8880., 8928., ..., 1498., 1522., 1284.],\n", - " [ 8952., 8944., 8960., ..., 1542., 1478., 1448.],\n", - " ...,\n", - "...\n", - " [ 652., 640., 638., ..., 590., 821., 1008.],\n", - " [ 622., 676., 630., ..., 606., 1092., 726.],\n", - " [ 864., 786., 569., ..., 766., 1068., 630.]],\n", - "\n", - " [[ 201., 213., 195., ..., 1138., 1058., 749.],\n", - " [ 196., 198., 169., ..., 861., 784., 768.],\n", - " [ 216., 178., 191., ..., 870., 806., 820.],\n", - " ...,\n", - " [ 857., 838., 846., ..., 622., 800., 1332.],\n", - " [ 922., 848., 771., ..., 786., 1046., 912.],\n", - " [ 1118., 1010., 735., ..., 755., 977., 686.]],\n", - "\n", - " [[ 3264., 3352., 3304., ..., 3160., 3296., 3376.],\n", - " [ 3356., 3300., 3212., ..., 3188., 3272., 3064.],\n", - " [ 3288., 3372., 3344., ..., 3136., 3200., 2932.],\n", - " ...,\n", - " [ 1320., 1468., 1298., ..., 2492., 2556., 3018.],\n", - " [ 1630., 1694., 1250., ..., 2318., 2684., 2894.],\n", - " [ 2190., 2072., 1288., ..., 2544., 2942., 2928.]]]],\n", - " dtype=float32)\n", - "Coordinates: (12/53)\n", - " * time (time) datetime64[ns] 96B 2018-0...\n", - " id (time) " + "" ] }, - "execution_count": 21, + "execution_count": 13, "metadata": {}, "output_type": "execute_result" }, @@ -1588,7 +541,7 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": 14, "id": "1da07de0-b8f2-46c9-bd2a-58b15ca2224f", "metadata": {}, "outputs": [ @@ -1626,7 +579,7 @@ ], "metadata": { "kernelspec": { - "display_name": "claymodel", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, From 19cbd9f7c3941b0dcea61540bb7827ec8931ff93 Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 10:33:42 +0100 Subject: [PATCH 3/9] Update running the model in basic use docs Using the current README text --- docs/basic_use.md | 24 +++++------------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/docs/basic_use.md b/docs/basic_use.md index 79c1ab66..83308511 100644 --- a/docs/basic_use.md +++ b/docs/basic_use.md @@ -1,6 +1,6 @@ # Basic Use -### Running jupyter lab +## Running jupyter lab mamba activate claymodel python -m ipykernel install --user --name claymodel # to install virtual env properly @@ -8,35 +8,21 @@ jupyter lab & -### Running the model - +## Running the model The neural network model can be ran via [LightningCLI v2](https://pytorch-lightning.medium.com/introducing-lightningcli-v2supercharge-your-training-c070d43c7dd6). To check out the different options available, and look at the hyperparameter configurations, run: python trainer.py --help - python trainer.py test --print_config To quickly test the model on one batch in the validation set: - python trainer.py validate --trainer.fast_dev_run=True - -To train the model for a hundred epochs: - - python trainer.py fit --trainer.max_epochs=100 + python trainer.py fit --model ClayMAEModule --data ClayDataModule --config configs/config.yaml --trainer.fast_dev_run=True -To generate embeddings from the pretrained model's encoder on 1024 images -(stored as a GeoParquet file with spatiotemporal metadata): +To train the model: - python trainer.py predict --ckpt_path=checkpoints/last.ckpt \ - --data.batch_size=1024 \ - --data.data_dir=s3://clay-tiles-02 \ - --trainer.limit_predict_batches=1 + python trainer.py fit --model ClayMAEModule --data ClayDataModule --config configs/config.yaml More options can be found using `python trainer.py fit --help`, or at the [LightningCLI docs](https://lightning.ai/docs/pytorch/2.1.0/cli/lightning_cli.html). - -## Advanced - -See [Readme](https://github.com/Clay-foundation/model/blob/v0.0.1/README.md) on model root for more details. From 75cd59e72550dfdd0d794899bb3daa08e175c97a Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 10:34:53 +0100 Subject: [PATCH 4/9] Move tutorials into separate folder --- docs/{ => tutorials}/clay-v1-wall-to-wall.ipynb | 0 docs/{ => tutorials}/reconstruction.ipynb | 0 docs/{ => tutorials}/visualize-embeddings.ipynb | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename docs/{ => tutorials}/clay-v1-wall-to-wall.ipynb (100%) rename docs/{ => tutorials}/reconstruction.ipynb (100%) rename docs/{ => tutorials}/visualize-embeddings.ipynb (100%) diff --git a/docs/clay-v1-wall-to-wall.ipynb b/docs/tutorials/clay-v1-wall-to-wall.ipynb similarity index 100% rename from docs/clay-v1-wall-to-wall.ipynb rename to docs/tutorials/clay-v1-wall-to-wall.ipynb diff --git a/docs/reconstruction.ipynb b/docs/tutorials/reconstruction.ipynb similarity index 100% rename from docs/reconstruction.ipynb rename to docs/tutorials/reconstruction.ipynb diff --git a/docs/visualize-embeddings.ipynb b/docs/tutorials/visualize-embeddings.ipynb similarity index 100% rename from docs/visualize-embeddings.ipynb rename to docs/tutorials/visualize-embeddings.ipynb From 2fa38ba2e3f017ca3fbf2e6851f23fb64a7146ab Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 10:37:21 +0100 Subject: [PATCH 5/9] Remove unnecessary header --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index f0e31382..efbe6971 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,6 @@ An open source AI model and interface for Earth. -# Getting started - ## Quickstart Launch into a [JupyterLab](https://jupyterlab.readthedocs.io) environment on From dd7a55d4f07bce1033ebb3dd69c12ab4ab290956 Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 10:40:03 +0100 Subject: [PATCH 6/9] Move jupyter-book readme into main readme --- README.md | 23 +++++++++++++++++++++++ docs/README.md | 20 -------------------- 2 files changed, 23 insertions(+), 20 deletions(-) delete mode 100644 docs/README.md diff --git a/README.md b/README.md index efbe6971..1e2d52d1 100644 --- a/README.md +++ b/README.md @@ -72,3 +72,26 @@ To train the model: More options can be found using `python trainer.py fit --help`, or at the [LightningCLI docs](https://lightning.ai/docs/pytorch/2.1.0/cli/lightning_cli.html). + +## Contributing + +### Writing documentation + +Our Documentation uses [Jupyter Book](https://jupyterbook.org/intro.html). + +Install it with: +```bash +pip install -U jupyter-book +``` + +Then build it with: +```bash +jupyter-book build docs/ +``` + +You can preview the site locally with: +```bash +python -m http.server --directory _build/html +``` + +There is a GitHub Action on `./github/workflows/deploy-docs.yml` that builds the site and pushes it to GitHub Pages. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index f5bc0086..00000000 --- a/docs/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# Clay Model Documentation - -This Documentation uses [Jupyter Book](https://jupyterbook.org/intro.html). - -Install it with: -```bash -pip install -U jupyter-book -``` - -Then build it with: -```bash -jupyter-book build docs/ -``` - -You can preview the site locally with: -```bash -python -m http.server --directory _build/html -``` - -There is a GitHub Action on `./github/workflows/deploy-docs.yml` that builds the site and pushes it to GitHub Pages. From 51c797ee087437d68e90707b5edb2b380e4603d8 Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 10:41:54 +0100 Subject: [PATCH 7/9] Updated tutorial paths in toc --- docs/_toc.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/_toc.yml b/docs/_toc.yml index 276d32b4..60334351 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -21,11 +21,11 @@ parts: - caption: Tutorials chapters: - title: Clay v1 wall-to-wall example - file: clay-v1-wall-to-wall + file: tutorials/clay-v1-wall-to-wall - title: Explore embeddings from Clay Encoder - file: visualize-embeddings + file: tutorials/visualize-embeddings - title: Clay MAE reconstruction - file: reconstruction + file: tutorials/reconstruction - caption: About Clay chapters: - title: GitHub From bab0c149e8c35d9a5413636b8cce72f4b505faf0 Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 10:48:37 +0100 Subject: [PATCH 8/9] Moved all doc files into subfolder by part --- docs/_toc.yml | 10 +++++----- docs/{ => getting-started}/basic_use.md | 0 docs/{ => getting-started}/installation.md | 0 docs/{ => release-notes}/changelog.md | 0 docs/{ => release-notes}/data_sampling.md | 0 docs/{ => release-notes}/specification.md | 0 6 files changed, 5 insertions(+), 5 deletions(-) rename docs/{ => getting-started}/basic_use.md (100%) rename docs/{ => getting-started}/installation.md (100%) rename docs/{ => release-notes}/changelog.md (100%) rename docs/{ => release-notes}/data_sampling.md (100%) rename docs/{ => release-notes}/specification.md (100%) diff --git a/docs/_toc.yml b/docs/_toc.yml index 60334351..3b3b726b 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -7,17 +7,17 @@ parts: - caption: Release notes chapters: - title: Software release notes - file: changelog + file: release-notes/changelog - title: Model release notes - file: specification + file: release-notes/specification - title: Data sampling strategy - file: data_sampling + file: release-notes/data_sampling - caption: Getting Started chapters: - title: Installation - file: installation + file: getting-started/installation - title: Basic Use - file: basic_use + file: getting-started/basic_use - caption: Tutorials chapters: - title: Clay v1 wall-to-wall example diff --git a/docs/basic_use.md b/docs/getting-started/basic_use.md similarity index 100% rename from docs/basic_use.md rename to docs/getting-started/basic_use.md diff --git a/docs/installation.md b/docs/getting-started/installation.md similarity index 100% rename from docs/installation.md rename to docs/getting-started/installation.md diff --git a/docs/changelog.md b/docs/release-notes/changelog.md similarity index 100% rename from docs/changelog.md rename to docs/release-notes/changelog.md diff --git a/docs/data_sampling.md b/docs/release-notes/data_sampling.md similarity index 100% rename from docs/data_sampling.md rename to docs/release-notes/data_sampling.md diff --git a/docs/specification.md b/docs/release-notes/specification.md similarity index 100% rename from docs/specification.md rename to docs/release-notes/specification.md From 1d8e986b933a3be7a9cc43b3fc240f3706bfc450 Mon Sep 17 00:00:00 2001 From: Daniel Wiesmann Date: Wed, 5 Jun 2024 10:56:05 +0100 Subject: [PATCH 9/9] Small improvements in cross reference links --- docs/release-notes/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-notes/specification.md b/docs/release-notes/specification.md index b2f231e9..1b5f050d 100644 --- a/docs/release-notes/specification.md +++ b/docs/release-notes/specification.md @@ -130,7 +130,7 @@ The data used for this model is described in detail in the [](training-data) sec ## Results -As a foundation model, it is designed to be used as a building block for other models. We have examples of what the embedding space & reconstruction looks like for the base model in the docs [here](visualize-embedding.ipynb) & [here](reconstruction.ipynb). +As a foundation model, it is designed to be used as a building block for other models. We have documented examples of how the [embedding space](../tutorials/visualize-embeddings.ipynb) and the [reconstructions](../tutorials/reconstruction.ipynb) look like for the base model. ### Performance Metrics