docs pass

README.md

@@ -24,7 +24,7 @@ Zoobot is trained using millions of answers by Galaxy Zoo volunteers. This code
 ## 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/17bb_KbA2J6yrIm4p4Ue_lEBHMNC1I9Jd?usp=sharing). To install locally, keep reading.
+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.
 
 Download the code using git:
 
@@ -49,7 +49,7 @@ I share my install steps [here](#install_cuda). GPUs are optional - Zoobot will
 ## Quickstart
 <a name="quickstart"></a>
 
-The [Colab notebook](https://colab.research.google.com/drive/17bb_KbA2J6yrIm4p4Ue_lEBHMNC1I9Jd?usp=sharing) is the quickest way to get started. Alternatively, the minimal example below illustrates how Zoobot works.
+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:
 
@@ -97,7 +97,7 @@ Zoobot includes many guides and working examples - see the [Getting Started](#ge
 ## Getting Started
 <a name="getting_started"></a>
 
-I suggest starting with the [Colab notebook](https://colab.research.google.com/drive/17bb_KbA2J6yrIm4p4Ue_lEBHMNC1I9Jd?usp=sharing) or the worked examples below, which you can copy and adapt.
+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/).
 

docs/autodoc/pytorch/training/finetune.rst

@@ -7,19 +7,35 @@ See the `README <https://github.com/mwalmsley/zoobot>`_ for a minimal example.
 See zoobot/pytorch/examples for more worked examples.
 
 .. autoclass:: zoobot.pytorch.training.finetune.FinetuneableZoobotAbstract
+    :members: configure_optimizers
 
 |
 
 .. autoclass:: zoobot.pytorch.training.finetune.FinetuneableZoobotClassifier
 
 |
 
+.. autoclass:: zoobot.pytorch.training.finetune.FinetuneableZoobotRegressor
+
+|
+
 .. autoclass:: zoobot.pytorch.training.finetune.FinetuneableZoobotTree
 
 |
 
+.. autoclass:: zoobot.pytorch.training.finetune.LinearHead
+    :members: forward
+
+|
+
+.. autofunction:: zoobot.pytorch.training.finetune.load_pretrained_zoobot
+
+|
+
 .. autofunction:: zoobot.pytorch.training.finetune.get_trainer
 
 |
 
-.. autofunction:: zoobot.pytorch.training.finetune.load_pretrained_encoder
+.. autofunction:: zoobot.pytorch.training.finetune.download_from_name
+
+|

docs/autodoc/shared/schemas.rst

@@ -26,6 +26,5 @@ See :ref:`training_on_vote_counts` for full explanation.
 |
 
 .. autoclass:: zoobot.shared.schemas.Schema
-    :members:
 
 |

docs/guides/advanced_finetuning.rst

@@ -4,48 +4,48 @@ Advanced Finetuning
 =====================
 
 
-Zoobot includes the :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotClassifier` and :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotTree`
-classes to help you finetune Zoobot on classification or decision tree problems, respectively. 
-But what about other problems, like regression or object detection?
+Zoobot includes the :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotClassifier`, :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotRegressor`, and :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotTree`
+classes to help you finetune Zoobot on classification, regression, or decision tree problems, respectively. 
+But what about other problems, like object detection?
 
 Here's how to integrate pretrained Zoobot models into your own code.
 
 Using Zoobot's Encoder Directly
 ------------------------------------
 
-To get Zoobot's encoder, load the model and access the .encoder attribute:
+To get Zoobot's encoder, load any Finetuneable class and grab the encoder attribute:
 
 .. code-block:: python
 
-    model = ZoobotTree.load_from_checkpoint(pretrained_checkpoint_loc)
+    model = FinetuneableZoobotClassifier(name='hf_hub:mwalmsley/zoobot-encoder-convnext_nano')
     encoder = model.encoder
 
-    model = FinetuneableZoobotClassifier.load_from_checkpoint(finetuned_checkpoint_loc)
-    encoder = model.encoder
+or, because Zoobot encoders are `timm` models, you can just directly use `timm`:
+
+.. code-block:: python
+
+    import timm
+
+    encoder = timm.create_model('hf_hub:mwalmsley/zoobot-encoder-convnext_nano', pretrained=True, num_classes=0)
 
-    # for ZoobotTree, there's also a utility function to do this in one line
-    encoder = finetune.load_pretrained_encoder(pretrained_checkpoint_loc)
 
-:class:`zoobot.pytorch.estimators.define_model.ZoobotTree`, :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotClassifier` and :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotTree`
-all have ``.encoder`` and ``.head`` attributes. These are the plain PyTorch (Sequential) models used for encoding or task predictions.
-The Zoobot classes simply wrap these with instructions for training, logging, checkpointing, and so on.
+You can use it like any other `timm` model. For example, we did this to `add contrastive learning <https://arxiv.org/abs/2206.11927>`_. Good luck!
 
-You can use the encoder separately like any PyTorch Sequential for any machine learning task. We did this to `add contrastive learning <https://arxiv.org/abs/2206.11927>`_. Go nuts.
 
 
 Subclassing FinetuneableZoobotAbstract
 ---------------------------------------
 
-If you'd like to finetune Zoobot on a new task that isn't classification or vote counts,
+If you'd like to finetune Zoobot on a new task that isn't classification, regression, or vote counts,
 you could instead subclass :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotAbstract`.
-This is less general but avoids having to write out your own finetuning training code in e.g. PyTorch Lightning.
+This lets you use our finetuning code with your own head and loss functions.
 
-For example, to make a regression version:
+Imagine there wasn't a regression version and you wanted to finetune Zoobot on a regression task. You could do:
 
 .. code-block:: python
 
     
-    class FinetuneableZoobotRegression(FinetuneableZoobotAbstract):
+    class FinetuneableZoobotCustomRegression(FinetuneableZoobotAbstract):
 
         def __init__(
             self,
@@ -56,12 +56,12 @@ For example, to make a regression version:
             super().__init__(**super_kwargs)
 
             self.foo = foo
-            self.loss = torch.nn.MSELoss()
-            self.head = torch.nn.Sequential(...)
+            self.loss = torch.nn.SomeCrazyLoss()
+            self.head = torch.nn.Sequential(my_crazy_head)
 
     # see zoobot/pytorch/training/finetune.py for more examples and all methods required
 
-You can then finetune this new class just as with e.g. FinetuneableZoobotClassifier.
+You can then finetune this new class just as with e.g. :class:`zoobot.pytorch.training.finetune.FinetuneableZoobotRegressor`.
 
 
 Extracting Frozen Representations
@@ -71,27 +71,21 @@ Once you've finetuned to your survey, or if you're using a pretrained survey, (S
 the representations can be stored as frozen vectors and used as features.
 We use this at Galaxy Zoo to power our upcoming similary search and anomaly-finding tools.
 
-As above, we can get Zoobot's encoder from the .encoder attribute:
-
-.. code-block:: python
-
-    # can load from either ZoobotTree (if trained from scratch)
-    # or FinetuneableZoobotTree (if finetuned)
-    encoder = finetune.FinetuneableZoobotTree.load_from_checkpoint(checkpoint_loc).encoder
-
-``encoder`` is a PyTorch Sequential object, so we could use ``encoder.predict()`` to calculate our representations.
+As above, we can get Zoobot's encoder from the .encoder attribute. We could use ``encoder()`` to calculate our representations.
 But then we'd have to deal with batching, looping, etc. 
 To avoid this boilerplate, Zoobot includes a PyTorch Lightning class that lets you pass ``encoder`` to the same :func:`zoobot.pytorch.predictions.predict_on_catalog.predict`
 utility function used for making predictions with a full Zoobot model.
 
 .. code-block:: python
 
+    from zoobot.pytorch.training import representations
+
     # convert to simple pytorch lightning model
-    model = representations.ZoobotEncoder(encoder=encoder, pyramid=False)
+    lightning_encoder = ZoobotEncoder.load_from_name('hf_hub:mwalmsley/zoobot-encoder-convnext_nano')
 
     predict_on_catalog.predict(
         catalog,
-        model,
+        lightning_encoder,
         n_samples=1,
         label_cols=label_cols,
         save_loc=save_loc,
@@ -101,9 +95,9 @@ utility function used for making predictions with a full Zoobot model.
 
 See `zoobot/pytorch/examples/representations <https://github.com/mwalmsley/zoobot/tree/main/zoobot/pytorch/examples/representations>`_ for a full working example.
 
-We plan on adding precalculated representations for all our DESI galaxies - but we haven't done it yet. Sorry.
-Please raise an issue if you really need these.
+We are sharing precalculated representations for all our DESI galaxies, and soon for HSC as well.
+Check the data notes at :doc:/data_notes
 
-The representations are typically quite high-dimensional (1280 for EfficientNetB0) and therefore highly redundant.
+The representations are typically quite high-dimensional (e.g. 1280 for EfficientNetB0) and therefore highly redundant.
 We suggest using PCA to compress them down to a more reasonable dimension (e.g. 40) while preserving most of the information.
 This was our approach in the `Practical Morphology Tools paper <https://arxiv.org/abs/2110.12735>`_.

docs/guides/finetuning.rst

@@ -30,7 +30,7 @@ Examples
 
 Zoobot includes many working examples of finetuning: 
 
-- `Google Colab notebook <https://colab.research.google.com/drive/17bb_KbA2J6yrIm4p4Ue_lEBHMNC1I9Jd?usp=sharing>`__ (for binary classification in the cloud)
+- `Google Colab notebook <https://colab.research.google.com/drive/1A_-M3Sz5maQmyfW2A7rEu-g_Zi0RMGz5?usp=sharing>`__ (for binary classification in the cloud)
 - `finetune_binary_classification.py <https://github.com/mwalmsley/zoobot/blob/main/zoobot/pytorch/examples/finetuning/finetune_binary_classification.py>`__ (script version of the Colab notebook)
 - `finetune_counts_full_tree.py <https://github.com/mwalmsley/zoobot/blob/main/zoobot/pytorch/examples/finetuning/finetune_counts_full_tree.py>`__ (for finetuning on a complicated GZ-style decision tree)
 

docs/guides/guides.rst

@@ -9,10 +9,8 @@ Below are some practical guides for tasks that we hope Zoobot will be helpful fo
 
    /guides/finetuning
    /guides/advanced_finetuning
-   /guides/training_on_vote_counts
    /guides/how_the_code_fits_together
-   /guides/pytorch_or_tensorflow
-
-If you'd prefer worked examples, you can find those under `zoobot/pytorch/examples <https://github.com/mwalmsley/zoobot/blob/main/zoobot/pytorch/examples>`_ and `zoobot/tensorflow/examples <https://github.com/mwalmsley/zoobot/blob/main/zoobot/tensorflow/examples>`_. 
+   /guides/loading_data
+   /guides/training_on_vote_counts
 
-There's also this `Colab notebook <https://colab.research.google.com/drive/17bb_KbA2J6yrIm4p4Ue_lEBHMNC1I9Jd?usp=sharing>`_ demonstrating finetuning which you can run in the cloud (with free access to a powerful GPU, courtesy of Google Research)
+If you'd prefer worked examples, you can find those under `zoobot/pytorch/examples <https://github.com/mwalmsley/zoobot/blob/main/zoobot/pytorch/examples>`_.