likingInitiative 0.2.1__tar.gz

likinginitiative-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kianté Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

likinginitiative-0.2.1/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: likingInitiative
+Version: 0.2.1
+Summary: The Liking Rating Database in Python
+Author: Kianté Fernandez
+License: MIT
+Project-URL: Homepage, https://github.com/liking-initiative/likingInitiative-py
+Project-URL: Source, https://github.com/liking-initiative/likingInitiative-py
+Project-URL: Issues, https://github.com/liking-initiative/likingInitiative-py/issues
+Project-URL: Changelog, https://github.com/liking-initiative/likingInitiative-py/blob/main/CHANGELOG.md
+Project-URL: Data, https://doi.org/10.5281/zenodo.22216442
+Keywords: psychology,decision-making,open-data,preference,liking
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: polars>=0.20
+Requires-Dist: requests>=2.28
+Requires-Dist: platformdirs>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# likingInitiative — Python
+
+[![CI](https://github.com/liking-initiative/likingInitiative-py/actions/workflows/ci.yml/badge.svg)](https://github.com/liking-initiative/likingInitiative-py/actions/workflows/ci.yml)
+[![DOI](https://img.shields.io/badge/data%20DOI-10.5281%2Fzenodo.22216442-blue)](https://doi.org/10.5281/zenodo.22216442)
+
+The Liking Rating Database in Python: subjective liking ratings from
+published decision-making studies, as [polars](https://pola.rs) frames.
+
+## Install
+
+```bash
+pip install git+https://github.com/liking-initiative/likingInitiative-py
+```
+
+Requires Python 3.9 or newer. Data is downloaded from Zenodo on first use and
+cached locally; no account or token is needed.
+
+## Use
+
+```python
+import likingInitiative
+
+likingInitiative.list_datasets()                      # 59 datasets
+likingInitiative.list_studies()                       # 38 studies
+likingInitiative.list_items()                         # 2,217 stimuli
+
+d = likingInitiative.get_dataset("leeholyoak2021")
+d.data                                        # polars DataFrame
+d.scale                                       # (1.0, 100.0)
+d.timepoints                                  # [1, 2, 3]
+print(d.cite())
+
+likingInitiative.get_dataset(["leeholyoak2021", "leehare2023exp2"]).data   # stacked
+```
+
+### One item across every study that used it
+
+The cross-study view — the thing this database is built for:
+
+```python
+k = likingInitiative.get_item("kitkat")     # 1,626 ratings across 25 datasets
+k.by_dataset()                      # mean / sd / median per study, 0-1 scale
+```
+
+### The whole corpus
+
+```python
+db = likingInitiative.load_database()
+db["ratings"]        # 759,399 rows
+```
+
+## Two things to get right
+
+**Cross-study comparisons must use `normalized_rating`.** Studies use
+different response scales (0–4, 1–100, 1–870, willingness-to-pay in dollars),
+so raw `rating` values are not comparable. `normalized_rating` is
+`(rating − scale_min) / (scale_max − scale_min)` and always lies in 0–1.
+
+**Subject ids are unique only within a dataset.** Subject `"12"` in two
+datasets is two different people — key on `(dataset_code, subject_id)`.
+
+## Repeated rating phases
+
+Six datasets repeat the whole rating phase (`chenhol1`, `chenhol2`,
+`crosswebb`, `hamesmcc`, `leehare2023exp2`, `leeholyoak2021`), so
+`(subject_id, item_id)` alone is not unique for them:
+
+```python
+d = likingInitiative.get_dataset("leeholyoak2021")        # phases 1, 2, 3
+d.data.group_by("timepoint").agg(pl.col("normalized_rating").mean())
+
+likingInitiative.get_dataset("leeholyoak2021", timepoint=2)   # one phase
+```
+
+`get_item()` uses each dataset's first phase only, so a repeated-phase study
+does not carry extra weight in a cross-study comparison.
+
+## Versions and caching
+
+Data comes from versioned release files, not a live service, so a pinned
+version returns the same rows however long from now.
+
+```python
+likingInitiative.release_info()          # version, date, counts, migrations applied
+likingInitiative.get_dataset("leeholyoak2021", version="1.6.2")   # pin it
+likingInitiative.cache_info();  likingInitiative.clear_cache()
+```
+
+Set `LIKING_INITIATIVE_RELEASE_DIR` to a directory built by
+`scripts/build_release.py` to work against an unreleased build.
+
+## API
+
+| Function | Returns |
+|----------|---------|
+| `list_studies()` / `list_datasets()` / `list_items()` | catalogue frames |
+| `get_dataset(code, version, timepoint)` | `Dataset` — `.data`, `.metadata`, `.cite()` |
+| `get_item(name, version)` | `Item` — `.data`, `.by_dataset()`, `.cite()` |
+| `load_database(version)` | dict of frames |
+| `cite(x)` / `bibtex(x)` | citation text |
+| `release_info()` / `cache_info()` / `clear_cache()` | housekeeping |
+
+## Citation
+
+Please cite the database and the studies whose data you use. `cite()` with no
+argument returns the database citation; `cite(d)` returns a study's.
+
+> Fernandez, K., Goyal, S., & Krajbich, I. (2026). The Liking Initiative: a
+> database of subjective evaluation ratings for decision-making research
+> [Data set]. Zenodo. https://doi.org/10.5281/zenodo.22216442
+
+That is the concept DOI, which always resolves to the newest version. To name
+the exact bytes an analysis ran on, cite the version DOI that Zenodo lists for
+the version `release_info()` reports.
+
+## License
+
+MIT. The underlying data remain subject to the terms of the original
+publications.

likinginitiative-0.2.1/README.md

@@ -0,0 +1,119 @@
+# likingInitiative — Python
+
+[![CI](https://github.com/liking-initiative/likingInitiative-py/actions/workflows/ci.yml/badge.svg)](https://github.com/liking-initiative/likingInitiative-py/actions/workflows/ci.yml)
+[![DOI](https://img.shields.io/badge/data%20DOI-10.5281%2Fzenodo.22216442-blue)](https://doi.org/10.5281/zenodo.22216442)
+
+The Liking Rating Database in Python: subjective liking ratings from
+published decision-making studies, as [polars](https://pola.rs) frames.
+
+## Install
+
+```bash
+pip install git+https://github.com/liking-initiative/likingInitiative-py
+```
+
+Requires Python 3.9 or newer. Data is downloaded from Zenodo on first use and
+cached locally; no account or token is needed.
+
+## Use
+
+```python
+import likingInitiative
+
+likingInitiative.list_datasets()                      # 59 datasets
+likingInitiative.list_studies()                       # 38 studies
+likingInitiative.list_items()                         # 2,217 stimuli
+
+d = likingInitiative.get_dataset("leeholyoak2021")
+d.data                                        # polars DataFrame
+d.scale                                       # (1.0, 100.0)
+d.timepoints                                  # [1, 2, 3]
+print(d.cite())
+
+likingInitiative.get_dataset(["leeholyoak2021", "leehare2023exp2"]).data   # stacked
+```
+
+### One item across every study that used it
+
+The cross-study view — the thing this database is built for:
+
+```python
+k = likingInitiative.get_item("kitkat")     # 1,626 ratings across 25 datasets
+k.by_dataset()                      # mean / sd / median per study, 0-1 scale
+```
+
+### The whole corpus
+
+```python
+db = likingInitiative.load_database()
+db["ratings"]        # 759,399 rows
+```
+
+## Two things to get right
+
+**Cross-study comparisons must use `normalized_rating`.** Studies use
+different response scales (0–4, 1–100, 1–870, willingness-to-pay in dollars),
+so raw `rating` values are not comparable. `normalized_rating` is
+`(rating − scale_min) / (scale_max − scale_min)` and always lies in 0–1.
+
+**Subject ids are unique only within a dataset.** Subject `"12"` in two
+datasets is two different people — key on `(dataset_code, subject_id)`.
+
+## Repeated rating phases
+
+Six datasets repeat the whole rating phase (`chenhol1`, `chenhol2`,
+`crosswebb`, `hamesmcc`, `leehare2023exp2`, `leeholyoak2021`), so
+`(subject_id, item_id)` alone is not unique for them:
+
+```python
+d = likingInitiative.get_dataset("leeholyoak2021")        # phases 1, 2, 3
+d.data.group_by("timepoint").agg(pl.col("normalized_rating").mean())
+
+likingInitiative.get_dataset("leeholyoak2021", timepoint=2)   # one phase
+```
+
+`get_item()` uses each dataset's first phase only, so a repeated-phase study
+does not carry extra weight in a cross-study comparison.
+
+## Versions and caching
+
+Data comes from versioned release files, not a live service, so a pinned
+version returns the same rows however long from now.
+
+```python
+likingInitiative.release_info()          # version, date, counts, migrations applied
+likingInitiative.get_dataset("leeholyoak2021", version="1.6.2")   # pin it
+likingInitiative.cache_info();  likingInitiative.clear_cache()
+```
+
+Set `LIKING_INITIATIVE_RELEASE_DIR` to a directory built by
+`scripts/build_release.py` to work against an unreleased build.
+
+## API
+
+| Function | Returns |
+|----------|---------|
+| `list_studies()` / `list_datasets()` / `list_items()` | catalogue frames |
+| `get_dataset(code, version, timepoint)` | `Dataset` — `.data`, `.metadata`, `.cite()` |
+| `get_item(name, version)` | `Item` — `.data`, `.by_dataset()`, `.cite()` |
+| `load_database(version)` | dict of frames |
+| `cite(x)` / `bibtex(x)` | citation text |
+| `release_info()` / `cache_info()` / `clear_cache()` | housekeeping |
+
+## Citation
+
+Please cite the database and the studies whose data you use. `cite()` with no
+argument returns the database citation; `cite(d)` returns a study's.
+
+> Fernandez, K., Goyal, S., & Krajbich, I. (2026). The Liking Initiative: a
+> database of subjective evaluation ratings for decision-making research
+> [Data set]. Zenodo. https://doi.org/10.5281/zenodo.22216442
+
+That is the concept DOI, which always resolves to the newest version. To name
+the exact bytes an analysis ran on, cite the version DOI that Zenodo lists for
+the version `release_info()` reports.
+
+## License
+
+MIT. The underlying data remain subject to the terms of the original
+publications.

likinginitiative-0.2.1/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "likingInitiative"
+version = "0.2.1"
+description = "The Liking Rating Database in Python"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Kianté Fernandez" }]
+keywords = ["psychology", "decision-making", "open-data", "preference", "liking"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = [
+    "polars>=0.20",
+    "requests>=2.28",
+    "platformdirs>=3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.5", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/liking-initiative/likingInitiative-py"
+Source = "https://github.com/liking-initiative/likingInitiative-py"
+Issues = "https://github.com/liking-initiative/likingInitiative-py/issues"
+Changelog = "https://github.com/liking-initiative/likingInitiative-py/blob/main/CHANGELOG.md"
+Data = "https://doi.org/10.5281/zenodo.22216442"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+likingInitiative = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+# Pinned explicitly so a newer ruff on CI cannot widen the rule set. The
+# package is deliberately camelCase (it matches the R package), so
+# pep8-naming's module-name rule is not selected.
+select = ["E", "F", "W", "I"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["likingInitiative"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

likinginitiative-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

likinginitiative-0.2.1/src/likingInitiative/__init__.py

@@ -0,0 +1,60 @@
+"""
+likingInitiative — the Liking Rating Database in Python.
+
+Subjective liking ratings from published decision-making studies, as polars
+frames.
+
+    import likingInitiative
+
+    likingInitiative.list_datasets()                      # the catalogue
+    d = likingInitiative.get_dataset("leeholyoak2021")    # one study's ratings
+    d.data                                        # polars DataFrame
+    d.cite()
+
+    likingInitiative.get_item("kitkat")                   # one item, every study
+    likingInitiative.load_database()                      # the whole corpus
+
+Data comes from versioned release files, not a live service, so a pinned
+version returns the same rows however long from now. Assets are cached
+locally after first download — see ``cache_info()``.
+
+Two things to get right:
+
+* **Cross-study comparisons must use ``normalized_rating``.** Response scales
+  differ between studies (0-4, 1-100, 1-870, willingness-to-pay in dollars),
+  so raw ``rating`` values are not comparable. ``normalized_rating`` is
+  ``(rating - scale_min) / (scale_max - scale_min)`` and always lies in 0-1.
+* **Subject ids are unique only within a dataset.** Subject "12" in two
+  datasets is two different people; key on ``(dataset_code, subject_id)``.
+"""
+from .catalog import list_datasets, list_items, list_studies, release_info
+from .citation import bibtex, cite
+from .database import load_database
+from .dataset import Dataset, get_dataset
+from .item import Item, get_item
+from .release import (
+    LikingInitiativeError,
+    cache_info,
+    clear_cache,
+    resolve_version,
+)
+
+__all__ = [
+    "list_studies",
+    "list_datasets",
+    "list_items",
+    "get_dataset",
+    "get_item",
+    "load_database",
+    "cite",
+    "bibtex",
+    "release_info",
+    "resolve_version",
+    "cache_info",
+    "clear_cache",
+    "Dataset",
+    "Item",
+    "LikingInitiativeError",
+]
+
+__version__ = "0.2.1"

likinginitiative-0.2.1/src/likingInitiative/catalog.py

@@ -0,0 +1,61 @@
+"""The release catalogue: studies, datasets, and items."""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import polars as pl
+
+from .release import LikingInitiativeError, asset_path, load_catalog
+
+
+def release_info(version: str = "latest") -> Dict[str, Any]:
+    """Version, date, and headline counts for the release in use."""
+    return load_catalog(version)["release"]
+
+
+def list_studies(version: str = "latest") -> pl.DataFrame:
+    """Every publication in the database."""
+    return pl.DataFrame(load_catalog(version)["studies"])
+
+
+def list_datasets(version: str = "latest") -> pl.DataFrame:
+    """Every dataset, with its study, response scale, and size.
+
+    ``timepoints`` lists the rating phases a dataset holds; all but two have
+    a single phase.
+    """
+    rows = load_catalog(version)["datasets"]
+    frame = pl.DataFrame(rows, infer_schema_length=None)
+    return frame.with_columns(
+        pl.col("timepoints").list.len().alias("n_timepoints")
+    )
+
+
+def list_items(version: str = "latest") -> pl.DataFrame:
+    """Every stimulus, with the number of datasets it appears in."""
+    return pl.read_csv(
+        asset_path("items.tsv", version),
+        separator="\t",
+        schema_overrides={"item_id": pl.String, "name": pl.String},
+    )
+
+
+def dataset_entry(code: str, version: str = "latest") -> Dict[str, Any]:
+    """Look up one dataset's catalogue entry by code, id, or unique prefix."""
+    datasets = load_catalog(version)["datasets"]
+    lowered = code.lower()
+
+    for d in datasets:
+        if d["dataset_code"].lower() == lowered or d["dataset_id"] == code:
+            return d
+
+    prefix = [d for d in datasets if d["dataset_code"].lower().startswith(lowered)]
+    if len(prefix) == 1:
+        return prefix[0]
+    if len(prefix) > 1:
+        names = ", ".join(sorted(d["dataset_code"] for d in prefix))
+        raise LikingInitiativeError(f"'{code}' is ambiguous; matches: {names}")
+
+    raise LikingInitiativeError(
+        f"no dataset named '{code}'. Use likingInitiative.list_datasets() to see the catalogue."
+    )

likinginitiative-0.2.1/src/likingInitiative/citation.py

@@ -0,0 +1,66 @@
+"""Citations for the database and for the studies it draws on."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+# The concept DOI, which Zenodo resolves to the newest version. Cite this to
+# mean "the database"; cite the version DOI that release_info() reports when an
+# analysis needs to name the exact bytes it ran on.
+DATABASE_DOI = "10.5281/zenodo.22216442"
+
+DATABASE_CITATION = (
+    "Fernandez, K., Goyal, S., & Krajbich, I. (2026). The Liking Initiative: a "
+    "database of subjective evaluation ratings for decision-making research "
+    "[Data set]. Zenodo. https://doi.org/" + DATABASE_DOI
+)
+
+
+def _entry(x: Any) -> Optional[dict]:
+    """Accept a Dataset/Item object or a raw catalogue dict."""
+    if x is None:
+        return None
+    if isinstance(x, dict):
+        return x
+    return getattr(x, "metadata", None)
+
+
+def cite(x: Any = None) -> str:
+    """Citation for a dataset's source publication.
+
+    Returns only that study's citation. Appending the database's every time
+    would be noise in a loop over datasets -- call ``cite()`` with no argument
+    for the database's own citation, and please include it alongside whichever
+    studies you use.
+    """
+    entry = _entry(x)
+    if entry is None:
+        return DATABASE_CITATION
+
+    citation = entry.get("citation") or entry.get("study_name") or ""
+    doi = entry.get("paper_doi")
+    if doi:
+        citation = f"{citation} https://doi.org/{doi}"
+    return citation
+
+
+def bibtex(x: Any) -> str:
+    """A BibTeX entry for a dataset's source publication."""
+    entry = _entry(x)
+    if entry is None:
+        raise ValueError("bibtex() needs a dataset or item")
+
+    authors = " and ".join(
+        a.strip() for a in (entry.get("authors") or "").split(";") if a.strip()
+    )
+    year = entry.get("year") or ""
+    first = (entry.get("first_author") or "study").lower().replace(" ", "")
+    fields = [
+        f"  author  = {{{authors}}}",
+        f"  title   = {{{entry.get('study_name', '')}}}",
+        f"  year    = {{{year}}}",
+    ]
+    if entry.get("journal"):
+        fields.append(f"  journal = {{{entry['journal']}}}")
+    if entry.get("paper_doi"):
+        fields.append(f"  doi     = {{{entry['paper_doi']}}}")
+    return "@article{" + f"{first}{year}" + ",\n" + ",\n".join(fields) + "\n}"

likinginitiative-0.2.1/src/likingInitiative/database.py

@@ -0,0 +1,46 @@
+"""load_database() — the whole corpus in one call."""
+from __future__ import annotations
+
+from typing import Dict
+
+import polars as pl
+
+from .catalog import list_items, list_studies
+from .release import asset_path, load_catalog
+
+_cache: Dict[str, Dict[str, pl.DataFrame]] = {}
+
+_SCHEMA = {
+    "subject_id": pl.String,
+    "item_id": pl.String,
+    "item_name": pl.String,
+    "dataset_code": pl.String,
+    "study_id": pl.String,
+}
+
+
+def load_database(version: str = "latest") -> Dict[str, pl.DataFrame]:
+    """Every rating, plus the study, dataset and item tables.
+
+    Returns ``{"ratings", "studies", "datasets", "items"}``. Held in memory
+    after the first call, so repeated use is free.
+    """
+    resolved = load_catalog(version)["release"]["version"]
+    if resolved in _cache:
+        return _cache[resolved]
+
+    ratings = pl.read_csv(
+        asset_path("ratings.tsv.gz", version),
+        separator="\t",
+        schema_overrides=_SCHEMA,
+    )
+    datasets = pl.DataFrame(load_catalog(version)["datasets"], infer_schema_length=None)
+
+    out = {
+        "ratings": ratings,
+        "studies": list_studies(version),
+        "datasets": datasets,
+        "items": list_items(version),
+    }
+    _cache[resolved] = out
+    return out