Add description field to recipe schema and backend utilities (#430)

* add `description` and `randomness_seed` to top level recipe settings

* add description in example recipes

* add description to download and upload script

* add description field to unit tests

Author: rugeli

cellpack/autopack/DBRecipeHandler.py

@@ -855,6 +855,8 @@ def compile_db_recipe_data(db_recipe_data, obj_dict, grad_dict, comp_dict):
             recipe_data["grid_file_path"] = db_recipe_data.get("grid_file_path")
         if db_recipe_data.get("randomness_seed"):
             recipe_data["randomness_seed"] = db_recipe_data.get("randomness_seed")
+        if db_recipe_data.get("description"):
+            recipe_data["description"] = db_recipe_data.get("description")
         if grad_dict:
             recipe_data["gradients"] = [
                 {**v} for v in DBRecipeLoader.remove_dedup_hash(grad_dict).values()

cellpack/autopack/validation/recipe_models.py

@@ -417,10 +417,12 @@ def validate_entry_content(self):
 # RECIPE-METADATA-LEVEL
 class Recipe(BaseModel):
     name: str
+    description: Optional[str] = None
     version: str = Field("1.0.0")
     format_version: str = Field("2.0")
     bounding_box: List[List[float]] = Field([[0, 0, 0], [100, 100, 100]])
     grid_file_path: Optional[str] = None
+    randomness_seed: Optional[int] = None
     objects: Dict[str, RecipeObject] = Field(default_factory=dict)
     gradients: Union[Dict[str, RecipeGradient], List[Dict[str, Any]]] = Field(
         default_factory=dict

cellpack/bin/upload.py

@@ -21,6 +21,8 @@ def get_recipe_metadata(loader):
             "bounding_box": loader.recipe_data["bounding_box"],
             "composition": {},
         }
+        if "description" in loader.recipe_data:
+            recipe_meta_data["description"] = loader.recipe_data["description"]
         if "grid_file_path" in loader.recipe_data:
             recipe_meta_data["grid_file_path"] = loader.recipe_data["grid_file_path"]
         if "randomness_seed" in loader.recipe_data:

cellpack/tests/test_db_recipe_loader.py

@@ -91,11 +91,13 @@
     "version": "linear",
     "bounding_box": [[-110, -45, -62], [110, 45, 62]],
     "name": "test_recipe",
+    "description": "test_description",
 }
 
 
 compiled_firebase_recipe_example = {
     "name": "test_recipe",
+    "description": "test_description",
     "format_version": "2.1",
     "version": "linear",
     "bounding_box": [[-110, -45, -62], [110, 45, 62]],

cellpack/tests/test_db_uploader.py

@@ -27,6 +27,7 @@ def test_upload_data_with_recipe_and_id():
     collection = "recipe"
     data = {
         "name": "test",
+        "description": "test_description",
         "bounding_box": [[0, 0, 0], [1000, 1000, 1]],
         "version": "1.0.0",
         "composition": {"test": {"inherit": "firebase:test_collection/test_id"}},
@@ -147,11 +148,13 @@ def test_upload_collections():
 def test_upload_recipe():
     recipe_meta_data = {
         "name": "one_sphere",
+        "description": "test_description",
         "version": "1.0.0",
         "composition": {},
     }
     recipe_data = {
         "name": "one_sphere",
+        "description": "test_description",
         "version": "1.0.0",
         "objects": {
             "sphere_25": {

docs/RECIPE_SCHEMA.md

@@ -9,15 +9,18 @@ The top-level fields include metadata about the recipe, such as its name, versio
 | Field Path       | Type                                             | Description                        | Default Value                      | Notes                                                                                                                        |
 | ---------------- | ------------------------------------------------ | ---------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `name`           | string                                           | Name of the recipe                 |                                    |                                                                                                                              |
+| `description`    | string                                           | Description of the recipe          |                                    |                                                           |
 | `version`        | string                                           | Recipe version string              | "default"                          | Version of the recipe is appended to the output file name.                                                                   |
 | `format_version` | string                                           | Schema format version              | "1.0"                              | Older recipe formats do not have this field. Recipes are automatically migrated to the latest format version before packing. |
 | `bounding_box`   | array `[[minX, minY, minZ], [maxX, maxY, maxZ]]` | Bounding box of the packing result | `[[ 0, 0, 0 ], [ 100, 100, 100 ]]` |                                                                                                                              |
 | `grid_file_path` | string                                           | File path to read/write grid data  |                                    | If not specified, a grid file is created and stored at the output path.                                                      |
+| `randomness_seed` | integer                                          | Seed for random number generation   |  |   |
 
 **Example:**
 ```JSON
 {
     "name": "one_sphere",
+    "description": "Single sphere packed within a bounding box",
     "version": "1.0.0",
     "format_version": "2.0",
     "bounding_box": [

examples/recipes/v2/endosome.json

@@ -2,6 +2,7 @@
     "version": "gradient_packing",
     "format_version": "2.1",
     "name": "endosome",
+    "description": "Endosomes puncta (represented as spheres) packed with various biases in mesh containers, representing the cell membrane and nucleus, derived from a segmented hiPS cell.",
     "bounding_box": [
         [
             -124.39499130249024,

examples/recipes/v2/er_peroxisome.json

@@ -2,6 +2,7 @@
     "version": "gradient_packing",
     "format_version": "2.1",
     "name": "ER_peroxisome",
+    "description": "Peroxisome puncta (represented as spheres) packed in and around mesh containers representing the cell membrane, the nucleus, and the endoplasmic reticulum (ER), derived from a segmented hiPS cell.",
     "bounding_box": [
         [
             33.77499999999999,

examples/recipes/v2/golgi_endosome.json

@@ -2,6 +2,7 @@
     "version": "gradient_packing",
     "format_version": "2.1",
     "name": "golgi_endosome",
+    "description": "Endosome puncta (represented as spheres) packed in and around mesh containers representing the cell membrane, the nucleus, and the Golgi, derived from a segmented hiPS cell.",
     "bounding_box": [
         [
             34.5,

examples/recipes/v2/peroxisome.json

@@ -2,6 +2,7 @@
     "version": "gradient_packing",
     "format_version": "2.1",
     "name": "peroxisome",
+    "description": "Peroxisomes puncta (represented as spheres) packed with various biases in mesh containers representing the cell membrane and nucleus derived from a segmented hiPS cell.",
     "bounding_box": [
         [
             35.325,