Oogiri Dataset Builder

Reproducible builder for the datasets used in the following two papers, sourced from Chinsuko Study Oogiri pages:

• Oogiri-Master and Oogiri-Corpus — used in Oogiri-Master: Benchmarking Humor Understanding via Oogiri (arXiv:2512.21494).
• User preference data (user_preference/) — used in Who Laughs with Whom? Disentangling Influential Factors in Humor Preferences across User Clusters and LLMs (arXiv:2601.03103).

Quick Start

Requires uv and Python 3.11 (requires-python = ">=3.11,<3.12"). Run commands from the repository root.

Install dependencies:

uv sync

Build all public CSV outputs and validate them:

uv run python -m oogiri_dataset_builder pipeline --output-dir ./out
uv run python -m oogiri_dataset_builder validate --output-dir ./out

For all subcommands and options:

uv run python -m oogiri_dataset_builder --help

Pipeline

Folder names correspond to constants in defaults.py.

• crawl: Downloads topic HTML files into 01_raw_html/.
• parse: Converts HTML into 02_parsed/oogiri_data_with_votes.jsonl.
• build-dataset: Builds all public CSV outputs under 03_public_dataset/.
• pipeline: Runs crawl, parse, then build-dataset.
• validate: Verifies that 03_public_dataset/ matches the pinned baselines in baselines.py.

Common options:

• --output-dir DIR: Root directory for generated artifacts. The default is the current directory.
• --input-jsonl FILE: Parsed JSONL input. When omitted, commands read <output-dir>/02_parsed/oogiri_data_with_votes.jsonl.

Output Layout

• 01_raw_html/: Downloaded source HTML files, one per topic ID.
• 02_parsed/: Parsed JSONL data.
• 03_public_dataset/oogiri_master/Oogiri-Master.csv: Benchmark tasks.
• 03_public_dataset/oogiri_corpus/Oogiri-Corpus.csv: Prompt-response corpus.
• 03_public_dataset/user_preference/: User preference tables.

Dataset Schemas

oogiri_master/Oogiri-Master.csv

Multiple-choice benchmark tasks generated from prompt-response-vote data. 600 rows (with the canonical source JSONL and default settings).

Column	Description
id	Row identifier (e.g., binary_diff-87-0001).
task_type	Task family. One of binary_diff, binary_same, triple, quad, binary_classification.
prompt_id	Source prompt identifier.
prompt	Cleaned prompt text.
response_A	Candidate response A.
response_B	Candidate response B.
response_C	Candidate response C. Empty for binary_diff / binary_same / binary_classification.
response_D	Candidate response D. Empty unless task_type == quad.
label	Correct option label (A/B/C/D) or binary classification label (funny/not_funny).

oogiri_corpus/Oogiri-Corpus.csv

Flat prompt-response corpus with vote counts. 82,536 rows.

Column	Description
id	Row identifier (e.g., corpus-87-0001).
prompt_id	Source prompt identifier.
prompt	Prompt text.
response	Response text.
vote_count	Number of votes received by the response.

user_preference/

Filtered preference data for active users and user clustering.

votes.csv

Per-vote records. 57,751 rows.

Column	Description
user_name	Voter name.
response_id	Voted response identifier (<prompt_id>_<index>).
prompt_id	Source prompt identifier.
vote_count	Votes cast by this user for this response.

responses.csv

One row per response by an active user. 14,389 rows.

Column	Description
response_id	Response identifier (<prompt_id>_<index>).
prompt_id	Source prompt identifier.
response	Response text.
author	Response author name.
vote_count	Total votes received.
rank	Rank within the prompt (e.g., 1位).

prompts.csv

One row per prompt. 908 rows.

Column	Description
prompt_id	Prompt identifier.
prompt	Cleaned prompt text.
participant_count	Number of participants who posted a response.
vote_count	Total votes across all responses to this prompt.
response_count	Number of responses to this prompt.

prompts.csv intentionally exposes only the cleaned prompt text and does not include source URLs.

users.csv

One row per active user. 276 rows.

Column	Description
user_name	User name.
votes_cast_count	Total votes the user cast.
response_count	Number of responses the user authored.
participated_prompt_count	Distinct prompts the user authored a response for.
voted_prompt_count	Distinct prompts the user voted on.

user_clusters.csv

One row per active user with cluster assignment. 276 rows.

Column	Description
user_name	User name.
cluster_id	Assigned cluster (0–6).
votes_cast_count	Total votes the user cast.
response_count	Number of responses the user authored.
participated_prompt_count	Distinct prompts the user authored a response for.
voted_prompt_count	Distinct prompts the user voted on.

filter_config.json

Filtering parameters and source metadata used to produce this user_preference/ directory.

Build Defaults

Default parameters defined in defaults.py. Used by the build-dataset and pipeline commands.

Filtering

Parameter	Value	Constant
Min participants per prompt	30	DEFAULT_MIN_PARTICIPANTS
Min votes per prompt	100	DEFAULT_MIN_VOTES_PER_ODAI
Min votes per response	3	DEFAULT_MIN_VOTES_PER_ANSWER
Min votes cast per active user	100	DEFAULT_MIN_USER_VOTES
Duplicate user removal	enabled	DEFAULT_REMOVE_DUPLICATES
Duplicate similarity threshold	0.9999	DEFAULT_DUPLICATE_SIMILARITY_THRESHOLD

Clustering

Parameter	Value	Constant
User cluster count	7	USER_CLUSTER_K
SVD components	100	SVD_N_COMPONENTS
KMeans random state	42	KMEANS_RANDOM_STATE
KMeans n_init	10	KMEANS_N_INIT

Benchmark

Parameter	Value	Constant
Random seed	42	BENCHMARK_SEED
Sample count: binary_diff	100	BENCHMARK_SAMPLE_COUNTS
Sample count: binary_same	100	BENCHMARK_SAMPLE_COUNTS
Sample count: triple	100	BENCHMARK_SAMPLE_COUNTS
Sample count: quad	100	BENCHMARK_SAMPLE_COUNTS
Sample count: binary_classification	200	BENCHMARK_SAMPLE_COUNTS

Validation

Run the validate command to verify that 03_public_dataset/ matches the expected values pinned in baselines.py:

uv run python -m oogiri_dataset_builder validate --output-dir ./out

The command exits non-zero if any check fails. It checks:

• All expected files exist under 03_public_dataset/.
• Each CSV header matches the documented schema.
• Each CSV's sha256 matches the pinned value in baselines.py.
• user_preference/filter_config.json parameters (min_participants, min_votes_per_odai, min_votes_per_answer, min_user_votes, remove_duplicates) match the pinned values. The generated_at, input, and output_dir keys are ignored.
• user_preference/prompts.csv does not include any source URL columns.
• user_preference/ contains no files other than the documented CSVs plus filter_config.json.

Updating baselines

When the dataset intentionally changes, regenerate the outputs with pipeline, then update EXPECTED_SHA256 (and any other affected constants) in baselines.py using shasum -a 256 on each file under 03_public_dataset/.

Crawling and Legal Notice

The crawl and pipeline commands access an external website to download source HTML files. Read this section before running them.

Scope of this repository

This repository contains only the build code. The generated outputs (Oogiri-Master.csv, Oogiri-Corpus.csv, user_preference/*) are produced locally by running the pipeline; this repository does not redistribute them.

Your responsibility before crawling

• Check the target site's robots.txt and terms of service yourself before running crawl or pipeline. Do not assume that permissive defaults from past runs still hold.
• Do not increase the load beyond the defaults defined in crawl_parse.py:
  • Per-request interval: about 1.0–1.5 seconds (_INTERVAL_BASE + jitter)
  • Parallelism: 3 workers (max_workers=3)

Redistribution of derived data

If you publish data derived from the crawled pages, you are responsible for complying with the source site's copyright notice and any applicable terms. The MIT license on this code does not transfer to the data.

Disclaimer

This software is provided "as is", without warranty of any kind. The maintainers are not responsible for how end users operate the crawler or how they publish derived data.

Citation

This code accompanies the following papers:

• Soichiro Murakami, Hidetaka Kamigaito, Hiroya Takamura, and Manabu Okumura. Who Laughs with Whom? Disentangling Influential Factors in Humor Preferences across User Clusters and LLMs. arXiv:2601.03103, 2026. [arXiv]
• Soichiro Murakami, Hidetaka Kamigaito, Hiroya Takamura, and Manabu Okumura. Oogiri-Master: Benchmarking Humor Understanding via Oogiri. arXiv:2512.21494, 2025. [arXiv]

If you use this software, please cite both papers:

@misc{murakami2026laughswhomdisentanglinginfluential,
      title={Who Laughs with Whom? Disentangling Influential Factors in Humor Preferences across User Clusters and LLMs},
      author={Soichiro Murakami and Hidetaka Kamigaito and Hiroya Takamura and Manabu Okumura},
      year={2026},
      eprint={2601.03103},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2601.03103},
}

@misc{murakami2025oogirimasterbenchmarkinghumorunderstanding,
      title={Oogiri-Master: Benchmarking Humor Understanding via Oogiri},
      author={Soichiro Murakami and Hidetaka Kamigaito and Hiroya Takamura and Manabu Okumura},
      year={2025},
      eprint={2512.21494},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2512.21494},
}

Contact

For questions, feedback, or bug reports, please open an issue on this repository.

License

Copyright (c) 2026 CyberAgent AI Lab. Released under the MIT License.