Update documentation and project standards to use uv

Author: Ashvin-Ranjan

README.md

@@ -2,20 +2,44 @@
 
 ## Installing Efficiency & Convexity
 
-First, set up a virtual environment (e.g. via [miniconda](https://docs.conda.io/en/latest/miniconda.html), `conda create -n eff_conv python=3.11`, and `conda activate eff_conv`).
-
 1. Download or clone this repository and navigate to the root folder.
 
 2. Install the IB Optimizer (We recommend doing this inside a virtual environment)
 
    `pip install -e .`
 
+## Development, Examples, & Tests
+
+### Setting Up the Environment
+
+First, install [uv](https://docs.astral.sh/uv/getting-started/installation/). After `uv` is installed navigate to root of the project and execute:
+
+```sh
+uv sync
+```
+
+### Testing
+
+Tests are located in `src/tests` and can be run using:
+
+```sh
+uv run pytest
+```
+
+### Examples
+
+Examples can be found in the `src/examples` folder. Each example will have documentation of how to execute its scripts in their respective `README.md` files.
+Note that oftentimes scripts from each example are to be executed in the `src/examples` folder, NOT the folder of the example itself.
+
 ## References
 
+<details>
 <summary>Links:</summary>
 
 > Tishby, N., Fernando P., & Bialek, W. (2000). The information bottleneck method. The 37th annual Allerton Conference on Communication, Control, and Computing. pp. 368–377. https://doi.org/10.48550/arXiv.physics/0004057
 
 > Skinner, L. (2025). Convexity is a Fundamental Feature of Efficient Semantic Compression in Probability Spaces. https://hdl.handle.net/1773/53008
 
+> Zaslavsky, N., Kemp, C., Regier, T., & Tishby, N. (2018). Efficient compression in color naming and its evolution. Proceedings of the National Academy of Sciences, 115(31), 7937–7942. https://doi.org/10.1073/pnas.1800521115
+
 </details>

pyproject.toml

@@ -21,13 +21,6 @@ license = {file = "LICENSE.txt"}
 dependencies = [
     "scipy",
     "numpy",
-    "pytest",
-    "black",
-    "statsmodels==0.14.5",
-    "pandas==2.3.0",
-    "open3d==0.19.0",
-    "matplotlib==3.10.3",
-    "scikit-image==0.25.2",
 ]
 
 [project.urls]
@@ -36,6 +29,24 @@ dependencies = [
 
 [dependency-groups]
 dev = [
+    "black",
     "ruff>=0.14.0",
     "ty>=0.0.1a21",
+    "pytest",
 ]
+
+[project.optional-dependencies]
+colors = [
+    "statsmodels==0.14.5",
+    "pandas==2.3.0",
+    "open3d==0.19.0",
+    "matplotlib==3.10.3",
+    "scikit-image==0.25.2",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["eff_conv*"]

src/examples/colors/README.md

@@ -5,9 +5,9 @@
 The paper and appendix can be found [here](./docs/).
 
 ## Setup
-After setting up the `eff_conv` environment, install the proper prerequisites:
+After setting up the general `uv` environment, install the proper prerequisites:
 ```sh
-python -m pip install -r requirements.txt
+uv sync --extra colors
 ```
 
 ## How To Run
@@ -23,13 +23,11 @@ populate the relevant files.
 
 ### Creating the WCS and CIELab visualizations
 
-TODO: The stimulus grid needs to be updated
-
 In the `examples` directory, run the following commands to get CIELab visualization (Figure 2 in the paper):
 ```sh
-python -m colors.visualization.cloud color_reg
-python -m colors.visualization.cloud color_rot 20
-python -m colors.visualization.cloud color_diff 20 diff
+uv run -m colors.visualization.cloud color_reg
+uv run -m colors.visualization.cloud color_rot 20
+uv run -m colors.visualization.cloud color_diff 20 diff
 ```
 
 This will create the files `color_reg.png`, `color_rot.png`, and `color_diff.png` in the `output/color` folder.
@@ -42,7 +40,7 @@ The raw model files for each experiement are very large (ranging from 250 MB for
 If you wish to run this experiment with your own data, after doing the data generation for experiment 1 and 2 you will need to generate the `.csv` files using the following command:
 
 ```sh
-python -m colors.utils.minimize_models
+uv run -m colors.utils.minimize_models
 ```
 
 ### Experiment 1
@@ -51,7 +49,7 @@ python -m colors.utils.minimize_models
 
 To generate the color model run the following command in the `examples` directory:
 ```sh
-python -m colors.exp1.generate_color_model
+uv run -m colors.exp1.generate_color_model
 ```
 
 #### Data Analysis
@@ -61,11 +59,11 @@ Please ensure you have the minimized `.csv` files before doing analysis.
 You can generate the plots and correlations using the respective commands:
 ```sh
 # Plots
-python -m colors.exp1.generate_color_plot
-python -m colors.exp1.gen_whisker_plots
+uv run -m colors.exp1.generate_color_plot
+uv run -m colors.exp1.gen_whisker_plots
 # Correlations
-python -m colors.exp1.generate_color_correlation
-python -m colors.utils.ols_model color_model
+uv run -m colors.exp1.generate_color_correlation
+uv run -m colors.utils.ols_model color_model
 ```
 
 ### Experiments 2 & 3
@@ -74,7 +72,7 @@ python -m colors.utils.ols_model color_model
 
 To generate the test models for experiments 2 and 3, you can run the followign command in the `examples` directory:
 ```sh
-python -m colors.exp2_3.generate_models
+uv run -m colors.exp2_3.generate_models
 ```
 
 ### Data Analysis
@@ -83,8 +81,8 @@ Please ensure you have the minimized `.csv` files before doing analysis.
 
 After this you can generate the plots and correlations using the respective commands:
 ```sh
-python -m colors.exp2_3.generate_plots
-python -m colors.exp2_3.calculate_correlation
+uv run -m colors.exp2_3.generate_plots
+uv run -m colors.exp2_3.calculate_correlation
 ```
 
 ### OLS Models
@@ -93,7 +91,7 @@ Please ensure you have the minimized `.csv` files before running the OLS model.
 
 After the `.csv` files are generated, you can generate the the OLS model for a given environment with the following command
 ```sh
-python -m colors.utils.ols_model [environment_name]
+uv run -m colors.utils.ols_model [environment_name]
 ```
 
 ## Additional Documentation

src/examples/colors/visualization/cloud.py

@@ -184,6 +184,6 @@ def custom_draw(
         pcd,
         extras=[xy_grid, xz_grid, yz_grid],
         lookat=min_bound + np.array([-20, 0, 10]),
-        up=np.ndarray([1, 0, 0]),
+        up=np.array([1, 0, 0]),
         camera_position=center + np.array([-135, -180, -220]),
     )