Merge pull request #4042 from voxel51/release/v0.23.4

Release v0.23.4

app/packages/plugins/src/index.ts

@@ -1,7 +1,7 @@
 import { useOperators } from "@fiftyone/operators";
 import * as fos from "@fiftyone/state";
 import * as fou from "@fiftyone/utilities";
-import { getFetchFunction, getFetchOrigin } from "@fiftyone/utilities";
+import { getFetchFunction, getFetchParameters } from "@fiftyone/utilities";
 import * as _ from "lodash";
 import React, { FunctionComponent, useEffect, useMemo, useState } from "react";
 import * as recoil from "recoil";
@@ -96,6 +96,7 @@ class PluginDefinition {
 
 export async function loadPlugins() {
   const plugins = await fetchPluginsMetadata();
+  const { pathPrefix } = getFetchParameters();
   for (const plugin of plugins) {
     usingRegistry().registerPluginDefinition(plugin);
     if (plugin.hasJS) {
@@ -106,7 +107,7 @@ export async function loadPlugins() {
         continue;
       }
       try {
-        await loadScript(name, `${getFetchOrigin()}${scriptPath}`);
+        await loadScript(name, pathPrefix + scriptPath);
       } catch (e) {
         console.error(`Plugin "${name}": failed to load!`);
         console.error(e);

docs/source/_includes/substitutions.rst

@@ -121,6 +121,7 @@
 .. |SimilarityConfig| replace:: :class:`SimilarityConfig <fiftyone.brain.similarity.SimilarityConfig>`
 .. |SimilarityIndex| replace:: :class:`SimilarityIndex <fiftyone.brain.similarity.SimilarityIndex>`
 
+.. |Visualization| replace:: :class:`Visualization <fiftyone.brain.visualization.Visualization>`
 .. |VisualizationConfig| replace:: :class:`VisualizationConfig <fiftyone.brain.visualization.VisualizationConfig>`
 .. |VisualizationResults| replace:: :class:`VisualizationResults <fiftyone.brain.visualization.VisualizationResults>`
 

docs/source/release-notes.rst

@@ -3,6 +3,33 @@ FiftyOne Release Notes
 
 .. default-role:: code
 
+FiftyOne Teams 1.5.5
+--------------------
+*Released January 25, 2024*
+
+Includes all updates from :ref:`FiftyOne 0.23.4 <release-notes-v0.23.4>`, plus:
+
+Bugs
+
+- Fixed a proxy URL bug that prevented custom JS panels from launching
+
+.. _release-notes-v0.23.4:
+
+FiftyOne 0.23.4
+---------------
+*Released January 25, 2024*
+
+Core
+
+- Added support for passing kwargs directly when creating custom runs
+  `#4039 <https://github.com/voxel51/fiftyone/pull/4039>`_
+
+Brain
+
+- Added support for registering
+  :ref:`custom visualization methods <brain-visualization-api>`
+  `#4038 <https://github.com/voxel51/fiftyone/pull/4038>`_
+
 FiftyOne Teams 1.5.4
 --------------------
 *Released January 19, 2024*

docs/source/user_guide/brain.rst

@@ -119,17 +119,35 @@ methods are:
 
 -   **umap** (*default*): Uniform Manifold Approximation and Projection
     (`UMAP <https://github.com/lmcinnes/umap>`_)
--   **t-sne**: t-distributed Stochastic Neighbor Embedding
+-   **tsne**: t-distributed Stochastic Neighbor Embedding
     (`t-SNE <https://lvdmaaten.github.io/tsne>`_)
 -   **pca**: Principal Component Analysis
     (`PCA <https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.PCA.html>`_)
+-   **manual**: provide a manually computed low-dimensional representation
+
+.. code-block:: python
+    :linenos:
+
+    import fiftyone.brain as fob
+
+    results = fob.compute_visualization(
+        dataset,
+        method="umap",  # "umap", "tsne", "pca", etc
+        brain_key="...",
+        ...
+    )
 
 .. note::
 
     When you use the default `UMAP <https://github.com/lmcinnes/umap>`_ method
     for the first time, you will be prompted to install the
     `umap-learn <https://github.com/lmcinnes/umap>`_ package.
 
+.. note::
+
+    Refer to :ref:`this section <brain-visualization-api>` for more information
+    about creating visualization runs.
+
 Applications
 ------------
 
@@ -273,6 +291,79 @@ As you can see, the coloring of the scatterpoints allows you to discover
 natural clusters of objects, such as visually similar carrots or kites in the
 air.
 
+.. _brain-visualization-api:
+
+Visualization API
+-----------------
+
+This section describes how to setup, create, and manage visualizations in
+detail.
+
+Changing your visualization method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use a specific dimensionality reduction method for a particular
+visualization run by passing the `method` parameter to
+:meth:`compute_visualization() <fiftyone.brain.compute_visualization>`:
+
+.. code:: python
+    :linenos:
+
+    index = fob.compute_visualization(..., method="<method>", ...)
+
+Alternatively, you can change your default dimensionality reduction method for
+an entire session by setting the `FIFTYONE_BRAIN_DEFAULT_VISUALIZATION_METHOD`
+environment variable:
+
+.. code-block:: shell
+
+    export FIFTYONE_BRAIN_DEFAULT_VISUALIZATION_METHOD=<method>
+
+Finally, you can permanently change your default dimensionality reduction
+method by updating the `default_visualization_method` key of your
+:ref:`brain config <brain-config>` at `~/.fiftyone/brain_config.json`:
+
+.. code-block:: text
+
+    {
+        "default_visualization_method": "<method>",
+        "visualization_methods": {
+            "<method>": {...},
+            ...
+        }
+    }
+
+Configuring your visualization method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Dimensionality reduction methods may be configured in a variety of
+method-specific ways, which you can see by inspecting the parameters of a
+method's associated |VisualizationConfig| class.
+
+The relevant classes for the builtin dimensionality reduction methods are:
+
+-   **umap**: :class:`fiftyone.brain.visualization.UMAPVisualizationConfig`
+-   **tsne**: :class:`fiftyone.brain.visualization.TSNEVisualizationConfig`
+-   **pca**: :class:`fiftyone.brain.visualization.PCAVisualizationConfig`
+-   **manual**: :class:`fiftyone.brain.visualization.ManualVisualizationConfig`
+
+You can configure a dimensionality reduction method's parameters for a specific
+run by simply passing supported config parameters as keyword arguments each
+time you call
+:meth:`compute_visualization() <fiftyone.brain.compute_visualization>`:
+
+.. code:: python
+    :linenos:
+
+    index = fob.compute_visualization(
+        ...
+        method="umap",
+        min_dist=0.2,
+    )
+
+Alternatively, you can more permanently configure your dimensionality reduction
+method(s) via your :ref:`brain config <brain-config>`.
+
 .. _brain-similarity:
 
 Similarity
@@ -333,6 +424,18 @@ another supported backend:
 -   **milvus**: a :ref:`Milvus backend <milvus-integration>`
 -   **lancedb**: a :ref:`LanceDB backend <lancedb-integration>`
 
+.. code-block:: python
+    :linenos:
+
+    import fiftyone.brain as fob
+
+    results = fob.compute_similarity(
+        dataset,
+        backend="sklearn",  # "sklearn", "qdrant", "redis", etc
+        brain_key="...",
+        ...
+    )
+
 .. note::
 
     Refer to :ref:`this section <brain-similarity-api>` for more information
@@ -1737,6 +1840,21 @@ and the CLI:
                 "lancedb": {
                     "config_cls": "fiftyone.brain.internal.core.lancedb.LanceDBSimilarityConfig"
                 }
+            },
+            "default_visualization_method": "umap",
+            "visualization_methods": {
+                "umap": {
+                    "config_cls": "fiftyone.brain.visualization.UMAPVisualizationConfig"
+                },
+                "tsne": {
+                    "config_cls": "fiftyone.brain.visualization.TSNEVisualizationConfig"
+                },
+                "pca": {
+                    "config_cls": "fiftyone.brain.visualization.PCAVisualizationConfig"
+                },
+                "manual": {
+                    "config_cls": "fiftyone.brain.visualization.ManualVisualizationConfig"
+                }
             }
         }
 
@@ -1773,6 +1891,21 @@ and the CLI:
                 "lancedb": {
                     "config_cls": "fiftyone.brain.internal.core.lancedb.LanceDBSimilarityConfig"
                 }
+            },
+            "default_visualization_method": "umap",
+            "visualization_methods": {
+                "umap": {
+                    "config_cls": "fiftyone.brain.visualization.UMAPVisualizationConfig"
+                },
+                "tsne": {
+                    "config_cls": "fiftyone.brain.visualization.TSNEVisualizationConfig"
+                },
+                "pca": {
+                    "config_cls": "fiftyone.brain.visualization.PCAVisualizationConfig"
+                },
+                "manual": {
+                    "config_cls": "fiftyone.brain.visualization.ManualVisualizationConfig"
+                }
             }
         }
 
@@ -1842,6 +1975,8 @@ to configure your default similarity backend:
 
     export FIFTYONE_BRAIN_DEFAULT_SIMILARITY_BACKEND=qdrant
 
+**Similarity backends**
+
 You can declare parameters for specific similarity backends by setting
 environment variables of the form
 `FIFTYONE_BRAIN_SIMILARITY_<BACKEND>_<PARAMETER>`. Any settings that you
@@ -1872,6 +2007,38 @@ you can add a `custom` similarity backend as follows:
     export FIFTYONE_BRAIN_SIMILARITY_BACKENDS=*,custom
     export FIFTYONE_BRAIN_SIMILARITY_CUSTOM_CONFIG_CLS=your.custom.SimilarityConfig
 
+**Visualization methods**
+
+You can declare parameters for specific visualization methods by setting
+environment variables of the form
+`FIFTYONE_BRAIN_VISUALIZATION_<METHOD>_<PARAMETER>`. Any settings that you
+declare in this way will be passed as keyword arguments to methods like
+:meth:`compute_visualization() <fiftyone.brain.compute_visualization>` whenever
+the corresponding method is in use. For example, you can suppress logging
+messages for the UMAP method as follows:
+
+.. code-block:: shell
+
+    export FIFTYONE_BRAIN_VISUALIZATION_UMAP_VERBOSE=false
+
+The `FIFTYONE_BRAIN_VISUALIZATION_METHODS` environment variable can be set to a
+`list,of,methods` that you want to expose in your session, which may exclude
+native methods and/or declare additional custom methods whose parameters are
+defined via additional config modifications of any kind:
+
+.. code-block:: shell
+
+    export FIFTYONE_BRAIN_VISUALIZATION_METHODS=custom,umap,tsne
+
+When declaring new methods, you can include `*` to append new method(s)
+without omitting or explicitly enumerating the builtin methods. For example,
+you can add a `custom` visualization method as follows:
+
+.. code-block:: shell
+
+    export FIFTYONE_BRAIN_VISUALIZATION_METHODS=*,custom
+    export FIFTYONE_BRAIN_VISUALIZATION_CUSTOM_CONFIG_CLS=your.custom.VisualzationConfig
+
 Modifying your config in code
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1887,4 +2054,5 @@ your current session.
 
     import fiftyone.brain as fob
 
-    fob.brain_config.default_similarity_backend = "<backend>"
+    fob.brain_config.default_similarity_backend = "qdrant"
+    fob.brain_config.default_visualization_method = "tsne"

fiftyone/core/collections.py

@@ -3663,13 +3663,16 @@ def list_runs(self, **kwargs):
         """
         return fors.Run.list_runs(self, **kwargs)
 
-    def init_run(self):
+    def init_run(self, **kwargs):
         """Initializes a config instance for a new run.
 
+        Args:
+            **kwargs: JSON serializable config parameters
+
         Returns:
             a :class:`fiftyone.core.runs.RunConfig`
         """
-        return fors.RunConfig()
+        return fors.RunConfig(**kwargs)
 
     def register_run(
         self,
@@ -3751,17 +3754,18 @@ def update_run_config(self, run_key, config):
 
         fors.Run.update_run_config(self, run_key, config)
 
-    def init_run_results(self, run_key):
+    def init_run_results(self, run_key, **kwargs):
         """Initializes a results instance for the run with the given key.
 
         Args:
             run_key: a run key
+            **kwargs: JSON serializable data
 
         Returns:
             a :class:`fiftyone.core.runs.RunResults`
         """
         info = fors.Run.get_run_info(self, run_key)
-        return fors.RunResults(self, info.config, run_key)
+        return fors.RunResults(self, info.config, run_key, **kwargs)
 
     def save_run_results(self, run_key, results, overwrite=True, cache=True):
         """Saves run results for the run with the given key.