Merge branch 'main' into inigo_dev

.readthedocs.yaml

@@ -1,14 +1,17 @@
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
 python:
-  version: 3.8
   install:
     - method: pip
       path: .
       extra_requirements:
         - docs
         - pytorch_m1
-        - tensorflow
 
 sphinx:
   fail_on_warning: true

README.md

@@ -9,6 +9,10 @@
 [![status](https://joss.theoj.org/papers/447561ee2de4709eddb704e18bee846f/status.svg)](https://joss.theoj.org/papers/447561ee2de4709eddb704e18bee846f)
 <a href="https://ascl.net/2203.027"><img src="https://img.shields.io/badge/ascl-2203.027-blue.svg?colorB=262255" alt="ascl:2203.027" /></a>
 
+---
+### :tada: Zoobot 2.0 is now available. Bigger and better models with streamlined finetuning. [Blog](https://walmsley.dev/posts/zoobot-scaling-laws), [paper](https://arxiv.org/abs/2404.02973) :tada:
+---
+
 Zoobot classifies galaxy morphology with deep learning.
 <!-- At Galaxy Zoo, we use Zoobot to help our volunteers classify the galaxies in all our recent catalogues: GZ DECaLS, GZ DESI, GZ Rings and GZ Cosmic Dawn. -->
 
@@ -17,11 +21,13 @@ Zoobot is trained using millions of answers by Galaxy Zoo volunteers. This code
 - [Install](#installation)
 - [Quickstart](#quickstart)
 - [Worked Examples](#worked-examples)
-- [Pretrained Weights](https://zoobot.readthedocs.io/en/latest/data_notes.html)
+- [Pretrained Weights](https://zoobot.readthedocs.io/en/latest/pretrained_models.html)
 - [Datasets](https://www.github.com/mwalmsley/galaxy-datasets)
 - [Documentation](https://zoobot.readthedocs.io/) (for understanding/reference)
+- [Mailing List](https://groups.google.com/g/zoobot) (for updates)
 
 ## Installation
+
 <a name="installation"></a>
 
 You can retrain Zoobot in the cloud with a free GPU using this [Google Colab notebook](https://colab.research.google.com/drive/1A_-M3Sz5maQmyfW2A7rEu-g_Zi0RMGz5?usp=sharing). To install locally, keep reading.
@@ -47,85 +53,82 @@ To use a GPU, you must *already* have CUDA installed and matching the versions a
 I share my install steps [here](#install_cuda). GPUs are optional - Zoobot will run retrain fine on CPU, just slower.
 
 ## Quickstart
+
 <a name="quickstart"></a>
 
 The [Colab notebook](https://colab.research.google.com/drive/1A_-M3Sz5maQmyfW2A7rEu-g_Zi0RMGz5?usp=sharing) is the quickest way to get started. Alternatively, the minimal example below illustrates how Zoobot works.
 
 Let's say you want to find ringed galaxies and you have a small labelled dataset of 500 ringed or not-ringed galaxies. You can retrain Zoobot to find rings like so:
 
 ```python
+import pandas as pd
+from galaxy_datasets.pytorch.galaxy_datamodule import GalaxyDataModule
+from zoobot.pytorch.training import finetune
+
+# csv with 'ring' column (0 or 1) and 'file_loc' column (path to image)
+labelled_df = pd.read_csv('/your/path/some_labelled_galaxies.csv')
+
+datamodule = GalaxyDataModule(
+    label_cols=['ring'],
+    catalog=labelled_df,
+    batch_size=32
+)
+
+# load trained Zoobot model
+model = finetune.FinetuneableZoobotClassifier(checkpoint_loc, num_classes=2)  
 
-    import pandas as pd
-    from galaxy_datasets.pytorch.galaxy_datamodule import GalaxyDataModule
-    from zoobot.pytorch.training import finetune
-
-    # csv with 'ring' column (0 or 1) and 'file_loc' column (path to image)
-    labelled_df = pd.read_csv('/your/path/some_labelled_galaxies.csv')
-
-    datamodule = GalaxyDataModule(
-      label_cols=['ring'],
-      catalog=labelled_df,
-      batch_size=32
-    )
-
-    # load trained Zoobot model
-    model = finetune.FinetuneableZoobotClassifier(checkpoint_loc, num_classes=2)  
-
-    # retrain to find rings
-    trainer = finetune.get_trainer(save_dir)
-    trainer.fit(model, datamodule)
+# retrain to find rings
+trainer = finetune.get_trainer(save_dir)
+trainer.fit(model, datamodule)
 ```
 
 Then you can make predict if new galaxies have rings:
 
 ```python
-    from zoobot.pytorch.predictions import predict_on_catalog
+from zoobot.pytorch.predictions import predict_on_catalog
 
-    # csv with 'file_loc' column (path to image). Zoobot will predict the labels.
-    unlabelled_df = pd.read_csv('/your/path/some_unlabelled_galaxies.csv')
+# csv with 'file_loc' column (path to image). Zoobot will predict the labels.
+unlabelled_df = pd.read_csv('/your/path/some_unlabelled_galaxies.csv')
 
-    predict_on_catalog.predict(
-      unlabelled_df,
-      model,
-      label_cols=['ring'],  # only used for 
-      save_loc='/your/path/finetuned_predictions.csv'
-    )
+predict_on_catalog.predict(
+    unlabelled_df,
+    model,
+    label_cols=['ring'],  # only used for 
+    save_loc='/your/path/finetuned_predictions.csv'
+)
 ```
 
 Zoobot includes many guides and working examples - see the [Getting Started](#getting-started) section below.
 
 ## Getting Started
+
 <a name="getting_started"></a>
 
 I suggest starting with the [Colab notebook](https://colab.research.google.com/drive/1A_-M3Sz5maQmyfW2A7rEu-g_Zi0RMGz5?usp=sharing) or the worked examples below, which you can copy and adapt.
 
 For context and explanation, see the [documentation](https://zoobot.readthedocs.io/).
 
-For pretrained model weights, precalculated representations, catalogues, and so forth, see the [data notes](https://zoobot.readthedocs.io/en/latest/data_notes.html) in particular.
+Pretrained models are listed [here](https://zoobot.readthedocs.io/en/latest/pretrained_models.html) and available on [HuggingFace](https://huggingface.co/collections/mwalmsley/zoobot-encoders-65fa14ae92911b173712b874)
 
 ### Worked Examples
+
 <a name="worked_examples"></a>
 
-PyTorch (recommended):
 - [pytorch/examples/finetuning/finetune_binary_classification.py](https://github.com/mwalmsley/zoobot/blob/main/zoobot/pytorch/examples/finetuning/finetune_binary_classification.py)
 - [pytorch/examples/finetuning/finetune_counts_full_tree.py](https://github.com/mwalmsley/zoobot/blob/main/zoobot/pytorch/examples/finetuning/finetune_counts_full_tree.py)
 - [pytorch/examples/representations/get_representations.py](https://github.com/mwalmsley/zoobot/blob/main/zoobot/pytorch/examples/representations/get_representations.py)
 - [pytorch/examples/train_model_on_catalog.py](https://github.com/mwalmsley/zoobot/blob/main/zoobot/pytorch/examples/train_model_on_catalog.py) (only necessary to train from scratch)
 
 There is more explanation and an API reference on the [docs](https://zoobot.readthedocs.io/).
 
-I also [include](https://github.com/mwalmsley/zoobot/blob/main/benchmarks) the scripts used to create and benchmark our pretrained models. Many pretrained models are available [already](https://zoobot.readthedocs.io/en/latest/data_notes.html), but if you need one trained on e.g. different input image sizes or with a specific architecture, I can probably make it for you.
-
-When trained with a decision tree head (ZoobotTree, FinetuneableZoobotTree), Zoobot can learn from volunteer labels of varying confidence and predict posteriors for what the typical volunteer might say. Specifically, this Zoobot mode predicts the parameters for distributions, not simple class labels! For a demonstration of how to interpret these predictions, see the [gz_decals_data_release_analysis_demo.ipynb](https://github.com/mwalmsley/zoobot/blob/main/gz_decals_data_release_analysis_demo.ipynb).
-
-
 
 ### (Optional) Install PyTorch with CUDA
+
 <a name="install_cuda"></a>
 
 *If you're not using a GPU, skip this step. Use the pytorch-cpu option in the section below.*
 
-Install PyTorch 2.1.0 or Tensorflow 2.10.0 and compatible CUDA drivers. I highly recommend using [conda](https://docs.conda.io/en/latest/miniconda.html) to do this. Conda will handle both creating a new virtual environment (`conda create`) and installing CUDA (`cudatoolkit`, `cudnn`)
+Install PyTorch 2.1.0 and compatible CUDA drivers. I highly recommend using [conda](https://docs.conda.io/en/latest/miniconda.html) to do this. Conda will handle both creating a new virtual environment (`conda create`) and installing CUDA (`cudatoolkit`, `cudnn`)
 
 CUDA 12.1 for PyTorch 2.1.0:
 
@@ -135,6 +138,7 @@ CUDA 12.1 for PyTorch 2.1.0:
 
 ### Recent release features (v2.0.0)
 
+- **New in 2.0.1** Add greyscale encoders. Use `hf_hub:mwalmsley/zoobot-encoder-greyscale-convnext_nano` or [similar](https://huggingface.co/collections/mwalmsley/zoobot-encoders-greyscale-66427c51133285ca01b490c6).
 - New pretrained architectures: ConvNeXT, EfficientNetV2, MaxViT, and more. Each in several sizes.
 - Reworked finetuning procedure. All these architectures are finetuneable through a common method.
 - Reworked finetuning options. Batch norm finetuning removed. Cosine schedule option added.
@@ -152,11 +156,11 @@ Contributions are very welcome and will be credited in any future work. Please g
 
 ### Benchmarks and Replication - Training from Scratch
 
-The [benchmarks](https://github.com/mwalmsley/zoobot/blob/main/benchmarks) folder contains slurm and Python scripts to train Zoobot from scratch. We use these scripts to make sure new code versions work well, and that TensorFlow and PyTorch achieve similar performance.
+The [benchmarks](https://github.com/mwalmsley/zoobot/blob/main/benchmarks) folder contains slurm and Python scripts to train Zoobot 1.0 from scratch. 
 
 Training Zoobot using the GZ DECaLS dataset option will create models very similar to those used for the GZ DECaLS catalogue and shared with the early versions of this repo. The GZ DESI Zoobot model is trained on additional data (GZD-1, GZD-2), as the GZ Evo Zoobot model (GZD-1/2/5, Hubble, Candels, GZ2).
 
-**Pretraining is becoming increasingly complex and is now partially refactored out to a separate repository. We are gradually migrating this `zoobot` repository to focus on finetuning.**
+*Pretraining is becoming increasingly complex and is now partially refactored out to a separate repository. We are gradually migrating this `zoobot` repository to focus on finetuning.*
 
 ### Citing
 
@@ -174,6 +178,7 @@ You might be interested in reading papers using Zoobot:
 - [Galaxy Zoo DESI: Detailed morphology measurements for 8.7M galaxies in the DESI Legacy Imaging Surveys](https://academic.oup.com/mnras/advance-article/doi/10.1093/mnras/stad2919/7283169?login=false) (2023)
 - [Galaxy mergers in Subaru HSC-SSP: A deep representation learning approach for identification, and the role of environment on merger incidence](https://doi.org/10.1051/0004-6361/202346743) (2023)
 - [Astronomaly at Scale: Searching for Anomalies Amongst 4 Million Galaxies](https://arxiv.org/abs/2309.08660) (2023, submitted)
-- [Transfer learning for galaxy feature detection: Finding Giant Star-forming Clumps in low redshift galaxies using Faster R-CNN](https://arxiv.org/abs/2312.03503) (2023, submitted)
+- [Transfer learning for galaxy feature detection: Finding Giant Star-forming Clumps in low redshift galaxies using Faster R-CNN](https://arxiv.org/abs/2312.03503) (2023)
+- [Euclid preparation. Measuring detailed galaxy morphologies for Euclid with Machine Learning](https://arxiv.org/abs/2402.10187) (2024, submitted)
 
 Many other works use Zoobot indirectly via the [Galaxy Zoo DECaLS](https://arxiv.org/abs/2102.08414) catalog (and now via the new [Galaxy Zoo DESI](https://academic.oup.com/mnras/advance-article/doi/10.1093/mnras/stad2919/7283169?login=false) catalog).

docs/conf.py

@@ -19,11 +19,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Zoobot'
-copyright = '2023, Mike Walmsley'
+copyright = '2024, Mike Walmsley'
 author = 'Mike Walmsley'
 
 # The full version, including alpha/beta/rc tags
-release = '0.0.4'
+release = '2.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -33,7 +33,8 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',  # import docs from code
-    'sphinx.ext.napoleon'  # google docstrings
+    'sphinx.ext.napoleon',  # google docstrings
+    'sphinxemoji.sphinxemoji',  # emoji support https://sphinxemojicodes.readthedocs.io/en/stable/
 ]
 
 # Add any paths that contain templates here, relative to this directory.