V2

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    paths:
+      # Changes to source code
+      - hobj/**
+      - test/**.py
+      # Changes to workflows
+      - .github/workflows/ci.yml
+      # Changes to project/dependency metadata
+      - 'pyproject.toml'
+      - 'uv.lock'
+jobs:
+  unit_tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --locked --dev
+      - name: Run pytests
+        run: uv run pytest -s

.gitignore

@@ -1,2 +1,7 @@
 .idea
-.DS_Store
+.DS_Store
+.venv
+__pycache__/
+*.egg-info/
+dist/
+/data/

.python-version

@@ -0,0 +1 @@
+3.12

Makefile

@@ -0,0 +1,28 @@
+lint:
+	uv run ruff check --fix && \
+	uv run ruff format
+
+check:
+	uv run ty check && \
+	uv run ruff check && \
+	uv run ruff format --check
+
+test:
+	uv run pytest tests
+
+
+publish:
+	@version="$$(uv version --short)"; \
+	case "$$version" in \
+		*.dev*) ;; \
+		*) \
+			printf "Version %s does not include .dev. Continue? [y/N] " "$$version"; \
+			read -r answer; \
+			case "$$answer" in \
+				y|Y) ;; \
+				*) echo "Aborted."; exit 1 ;; \
+			esac ;; \
+	esac; \
+	rm -rf dist && \
+	uv build && \
+	uv publish

README.md

@@ -0,0 +1,99 @@
+# `hobj`: human object learning benchmarks
+
+[![CI](https://github.com/himjl/hobj/actions/workflows/ci.yml/badge.svg)](https://github.com/himjl/hobj/actions/workflows/ci.yml)
+
+This repository contains benchmarks for comparing models of object learning against measurements of human behavior, from Lee and DiCarlo 2023 (["How well do rudimentary plasticity rules predict adult visual object learning?"](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011713)). It also lets you download the raw data and images from the experiments in the paper.
+
+<div style="text-align: center;">
+  <img src="site/readme_images/human_learning_curves.svg" alt="Alt text" >
+</div>
+
+If you just want to download the raw data and images without using the `hobj` library, you can do so at the [OSF repository](https://osf.io/pj6wm/files/osfstorage) for this project.
+
+## Quickstart
+
+### Install
+
+The `hobj` package works for Python >=3.12.
+
+Install it from [PyPI](https://pypi.org/project/hobj/):
+
+```bash
+pip install hobj
+```
+
+If you prefer to use [uv](https://docs.astral.sh/uv/getting-started/installation/),
+you can install it with:
+
+```bash
+uv pip install hobj
+```
+
+
+### Using `hobj` to comparing a linear learner against human learning data 
+
+The template script below shows you how you can run a benchmark on a linear learning model based on your image encoding model. 
+
+All you need to do is have a way to process a `PIL.Image` into a vector of image features (as an `np.ndarray`). There are ~18,000 images that you'd need to compute image features for.    
+
+```python
+import hobj
+import numpy as np 
+
+# Compute your features for the images 
+my_image_features: dict[str, np.ndarray] = {}
+for image_id in hobj.list_image_ids():
+    image = hobj.load_image(image_id=image_id) # PIL.Image
+
+    # Compute your features here:  
+    my_image_features[image_id] = ... # replace right hand side with your image-computable model
+
+# Assemble the learning model:
+model = hobj.create_linear_learner(
+    image_id_to_features=my_image_features,
+    update_rule_name='Square', # "Square", "Perceptron", "Hinge", "MAE", "Exponential", "CE", "REINFORCE",
+    alpha=1, # learning rate between [0, 1]
+)
+
+# Load the benchmark:
+benchmark = hobj.MutatorHighVarBenchmark()  # or hobj.MutatorOneshotBenchmark()
+
+# Score the model:
+result = benchmark.score_model(model)
+
+# Print its score and its CI:
+print(result.msen, result.msen_CI95)
+
+# You can also check out more granular statistics of the model's behavior, like its learning curves: 
+# print(result.model_statistics)
+```
+
+
+For more details (e.g., how to load the raw behavioral data or images in Python), check out the Jupyter notebooks in `examples/`.
+
+To use a different location, pass `cachedir=...` to a data loader or benchmark
+constructor, or prefetch manually with `hobj-download-data --cachedir /path/to/data`.
+
+## Contact 
+If you have any questions, need help, or experience a bug, please don't hesitate to email me ([mil@mit.edu](mailto:name@example.com)), or open an issue on this repo!
+
+
+
+## Changes to codebase since publication
+This codebase was overhauled in 2026 to improve its accessibility, performance, and quality. Along the way, minor changes to the statistical analysis procedure were introduced, along with changes to the names of the original filenames (see [changelist](site/changelist.md)). To see the codebase at the time of publication, check out the repo with the `v1` tag [here](https://github.com/himjl/hobj/releases/tag/v1).
+
+
+## Citation
+
+```
+@article{lee2023well,
+  title={How well do rudimentary plasticity rules predict adult visual object learning?},
+  author={Lee, Michael J and DiCarlo, James J},
+  journal={PLOS Computational Biology},
+  volume={19},
+  number={12},
+  pages={e1011713},
+  year={2023},
+  publisher={Public Library of Science San Francisco, CA USA}
+}
+```