crimepy 0.2.0__tar.gz → 0.2.2__tar.gz

{crimepy-0.2.0 → crimepy-0.2.2}/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project will be documented in this file.
 
 <!-- insertion marker -->
 
+## 0.2.2
+
+* Fixed the `pydoclint` check of CI: the Deflate64 reader of
+  `crimepy.nibrs.reader` and the fake responses of the download tests are
+  dataclasses, so their arguments are documented only by the class, and the
+  "Yields" sections of `reader.tables` and the tests name the types that
+  they yield.
+* Requires amos 0.6.2, and the lock file uses the latest bobbie (0.3.3),
+  bunches (0.3.0), camina (0.2.4), chrisjen (0.4.2), holden (0.2.6), miller
+  (0.2.3), nagata (0.2.1), and wonka (0.3.0). camina, chrisjen, and nagata
+  ship the `py.typed` marker, so they are gone from the `mypy` override for
+  untyped imports.
+* Importing `crimepy` registers the codebook of every column of codes with
+  `amos.register_value_map`, so `amos`'s `map_values` replaces the codes of
+  the columns it names with their labels, with no map in the settings
+  (`columns = victim_race, offender_race`).
+* `load_nibrs` keeps a label that is not a column of the loaded table as a
+  pending label (as amos 0.6.2 does), instead of dropping it, so a later
+  step such as `count_crimes` or `derive_columns` can make it.
+* `crimepy.combine.stack` and `merge` keep a pending label, and the kinds
+  (`Dataset.kinds`, from amos's `set_kinds`) of the columns that are still
+  there, so dummies stay dummies.
+* The tutorial scores its model with `measure`, since amos 0.6.2's metrics
+  are no longer techniques with an `apply`, and the advanced user guide shows
+  `map_values` with the codebooks.
+
+## 0.2.1
+
+* **Breaking:** `crimepy.nibrs.codes.STATES` is now the name of each numeric
+  state code (it was `STATE_NAMES`), and `codes.STATE_ABBREVIATIONS` is the
+  postal abbreviation (it was `STATES`).
+* Each codebook of `crimepy.nibrs.codes.CODEBOOKS` is also public by itself
+  (such as `codes.RACES` and `codes.WEAPONS`). The "clearances" codebook is
+  `codes.EXCEPTIONAL_CLEARANCES`, and the "divisions" codebook is
+  `codes.SUBREGIONS`. `codes.OFFENSES` has the name, category, whom or what
+  it is against, and group of each offense code.
+* `crimepy.nibrs.codes.OFFENSE_TYPES` lists the offense codes of each type:
+  whom or what they are against ("Person", "Property", "Society", and "Not
+  a Crime"), and "National Security Offenses", "Rape Offenses", "Sex
+  Offenses", and "Immigration Offenses".
+* The code follows the house style throughout: lines of at most 80
+  characters (the tables in docstrings are now lists), section markers that
+  group the members of each module and class, and a full docstring for every
+  function and method, tests and private ones included.
+
 ## 0.2.0
 
 * **Breaking:** crimepy keeps its data in amos's workspace (amos 0.6.0), not

{crimepy-0.2.0 → crimepy-0.2.2}/CITATION.cff

@@ -12,8 +12,8 @@ authors:
     family-names: Yung
     email: coreyrayburnyung@gmail.com
     orcid: "https://orcid.org/0000-0001-6524-9956"
-version: 0.2.0
-date-released: 2026-10-30
+version: 0.2.2
+date-released: 2026-11-01
 license: Apache-2.0
 repository-code: "https://github.com/WithPrecedent/crimepy"
 url: "https://WithPrecedent.github.io/crimepy"

{crimepy-0.2.0 → crimepy-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: crimepy
-Version: 0.2.0
+Version: 0.2.2
 Summary: Accessible tools for downloading, combining, munging, analyzing, and plotting crime data
 Project-URL: Documentation, https://WithPrecedent.github.io/crimepy
 Project-URL: Repository, https://github.com/WithPrecedent/crimepy
@@ -26,7 +26,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Sociology
 Requires-Python: >=3.11
-Requires-Dist: amos[plots]>=0.6.0
+Requires-Dist: amos[plots]>=0.6.2
 Requires-Dist: inflate64>=1.0
 Requires-Dist: numpy>=1.26
 Requires-Dist: pandas>=3.0
@@ -308,7 +308,7 @@ repository" button reads the same information from
 @software{yung_crimepy,
   author  = {Yung, Corey Rayburn},
   title   = {crimepy: Accessible tools for downloading, combining, munging, analyzing, and plotting crime data},
-  version = {0.2.0},
+  version = {0.2.2},
   year    = {2026},
   url     = {https://github.com/WithPrecedent/crimepy},
   license = {Apache-2.0}

{crimepy-0.2.0 → crimepy-0.2.2}/README.md

@@ -270,7 +270,7 @@ repository" button reads the same information from
 @software{yung_crimepy,
   author  = {Yung, Corey Rayburn},
   title   = {crimepy: Accessible tools for downloading, combining, munging, analyzing, and plotting crime data},
-  version = {0.2.0},
+  version = {0.2.2},
   year    = {2026},
   url     = {https://github.com/WithPrecedent/crimepy},
   license = {Apache-2.0}

{crimepy-0.2.0 → crimepy-0.2.2}/docs/advanced.md

@@ -167,11 +167,39 @@ offenses = crimepy.nibrs.decode(
     offenses, ['location'], {'location': {'20': 'Home', '13': 'Street'}})
 ```
 
+Importing `crimepy` also registers every codebook with
+`amos.register_value_map`, so `amos`'s `map_values` replaces the codes of
+the columns it names with their labels, with no map in the settings:
+
+```ini
+[wrangler]
+techniques = load_nibrs, map_values
+
+[load_nibrs_parameters]
+table = victims
+years = 2023
+decode = false
+
+[map_values_parameters]
+columns = victim_sex, victim_race, offender_race
+```
+
+Unlike `decode_nibrs`, `map_values` sorts the categories rather than putting
+them in the order of the codebook.
+
 `offenses`, `arrestees`, and `group_b_arrests` also get the category of the
 offense (`offense_category`, such as "Assault Offenses"), whom or what it is
 against (`crime_against`: "Person", "Property", "Society", or "Not a
 Crime"), and its group (`offense_group`: "A" or "B"), from the CDE's table of
 offenses (with the prefix "arrest_" for arrests).
+`crimepy.nibrs.codes.OFFENSE_TYPES` lists the offense codes that are against
+each of them, and those of a few types that cut across the categories
+("National Security Offenses", "Rape Offenses", "Sex Offenses", and
+"Immigration Offenses"), such as for picking the crimes against property:
+
+```python
+property_crimes = crimepy.nibrs.codes.OFFENSE_TYPES['Property']
+```
 
 ## Where the data are saved
 
@@ -230,13 +258,17 @@ while the parquet files are read, so the rest is never loaded.
   in the dataset's `tables` and a figure in its `figures`, under the
   technique's name, and every step is recorded in its `history`. `count`
   makes a new dataset of counts, whose label is the counts.
-* `crimepy.combine.stack` and `merge` return a dataset with the label and
-  groups of the first dataset given, if their columns are still there.
+* `crimepy.combine.stack` and `merge` return a dataset with the label,
+  groups, and kinds (from `amos`'s `set_kinds`) of the first dataset given,
+  if their columns are still there.
+* A label that is not yet a column (such as the "count" of `count_crimes`,
+  or a column that `derive_columns` makes) is pending, as `amos` keeps it:
+  `load_nibrs`, `stack`, and `merge` keep it until a later step makes it.
 
 A dataset gathers the data, what was learned from it, and how, so it is the
-record of an analysis. Any `amos` technique (a model, a validator, a metric,
-or a plot such as `shap_beeswarm`) can be applied to it directly, as in the
-[tutorial](tutorial.md#model).
+record of an analysis. Any `amos` technique (a model, a validator, or a plot
+such as `shap_beeswarm`) can be applied to it directly, and a metric's
+`measure` scores its predictions, as in the [tutorial](tutorial.md#model).
 
 ## The amos techniques
 

crimepy-0.2.2/docs/scripts/gen_ref_nav.py

@@ -0,0 +1,40 @@
+"""Generate the code reference pages and navigation.
+
+This code is adapted from pawamoy's packages. See, e.g.,
+https://github.com/pawamoy/duty/blob/main/scripts/gen_ref_nav.py.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+for path in sorted(Path('src').rglob('*.py')):
+    module_path = path.relative_to('src').with_suffix('')
+    doc_path = path.relative_to('src').with_suffix('.md')
+    full_doc_path = Path('reference', doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == '__init__':
+        parts = parts[:-1]
+        doc_path = doc_path.with_name('index.md')
+        full_doc_path = full_doc_path.with_name('index.md')
+    elif parts[-1].startswith('_'):
+        continue
+
+    nav_parts = [f'{mod_symbol} {part}' for part in parts]
+    nav[tuple(nav_parts)] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, 'w') as fd:
+        ident = '.'.join(parts)
+        fd.write(f'::: {ident}')
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, '..' / path)
+
+with mkdocs_gen_files.open('reference/SUMMARY.md', 'w') as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

{crimepy-0.2.0 → crimepy-0.2.2}/docs/tutorial.md

@@ -130,10 +130,12 @@ features = incidents.data[columns].dropna().astype(int)
 model_data = amos.Dataset.create(features, label = 'cleared', seed = 43)
 splitters.Stratified().apply(model_data)
 models.GradientBoosting().apply(model_data)
-metrics.RocAuc().apply(model_data)
-model_data.metrics['roc_auc']
+metrics.RocAuc().measure(model_data)
 ```
 
+A metric is not a step: `measure` returns its score. In a settings file,
+name it as a worker's `criterion` or in the `metrics` of a `scorecard`.
+
 (`arrestee_count` all but decides `cleared`, so the score is high: a real
 model of clearance would leave it out.)
 

{crimepy-0.2.0 → crimepy-0.2.2}/pyproject.toml

@@ -33,7 +33,7 @@ keywords = [
     "nibrs",
     "ucr"]
 dependencies = [
-    "amos[plots]>=0.6.0",
+    "amos[plots]>=0.6.2",
     "inflate64>=1.0",
     "numpy>=1.26",
     "pandas>=3.0",
@@ -126,10 +126,7 @@ show_error_codes = true
 # These packages are annotated but do not ship a py.typed marker.
 module = [
     "amos.*",
-    "camina.*",
-    "chrisjen.*",
     "inflate64.*",
-    "nagata.*",
     "pyarrow.*"]
 follow_untyped_imports = true
 ignore_missing_imports = true

crimepy-0.2.2/src/crimepy/__init__.py

@@ -0,0 +1,39 @@
+"""Accessible tools for crime data.
+
+crimepy downloads, combines, munges, analyzes, and plots crime data.
+
+Contents:
+    Project: an `amos.Project`, for a study of crime data.
+    analyze: counts crimes and computes rates, changes, and crosstabs.
+    combine: stacks and merges tables of crime data.
+    nibrs: tools for the FBI's National Incident-Based Reporting System.
+    options: default settings of crimepy.
+    plot: figures of crime data.
+    techniques: techniques that analyze crime data, on `amos` datasets.
+    utilities: small tools that the rest of crimepy shares.
+
+"""
+
+from __future__ import annotations
+
+__version__ = '0.2.2'
+
+__author__: str = 'Corey Rayburn Yung'
+
+__all__: list[str] = [
+    'Project',
+    'analyze',
+    'combine',
+    'nibrs',
+    'options',
+    'plot',
+    'techniques',
+    'utilities']
+
+# A study is an `amos.Project`, which crimepy offers under the same name.
+from amos import Project
+
+# Importing `nibrs`, `plot`, and `techniques` adds their techniques to the
+# `amos` library, so they can be named in settings as soon as crimepy is
+# imported.
+from . import analyze, combine, nibrs, options, plot, techniques, utilities

{crimepy-0.2.0 → crimepy-0.2.2}/src/crimepy/analyze.py

@@ -42,6 +42,8 @@ import pandas as pd
 
 from . import techniques, utilities
 
+""" Public Functions """
+
 
 def count(
     data: amos.Dataset | pd.DataFrame,
@@ -275,6 +277,9 @@ def coverage(
     return _describe(techniques.Coverage(), agencies, by = by, months = months)
 
 
+""" Private Functions """
+
+
 def _describe(
     technique: amos.Describer,
     data: amos.Dataset | pd.DataFrame,

{crimepy-0.2.0 → crimepy-0.2.2}/src/crimepy/cli.py

@@ -27,6 +27,8 @@ from collections.abc import Sequence
 
 from . import nibrs
 
+""" Public Functions """
+
 
 def main(arguments: Sequence[str] | None = None) -> int:
     """Runs the command line interface.
@@ -48,8 +50,17 @@ def main(arguments: Sequence[str] | None = None) -> int:
     return int(parsed.run(parsed) or 0)
 
 
+""" Private Functions """
+
+
 def _parser() -> argparse.ArgumentParser:
-    """Returns the parser of the command line arguments."""
+    """Returns the parser of the command line arguments.
+
+    Returns:
+        The parser, with a subcommand for each command, each of which sets
+            "run" to the function that runs it.
+
+    """
     parser = argparse.ArgumentParser(
         prog = 'crimepy',
         description = (
@@ -111,7 +122,12 @@ def _parser() -> argparse.ArgumentParser:
 
 
 def _add_folder(parser: argparse.ArgumentParser) -> None:
-    """Adds the "--folder" argument to `parser`."""
+    """Adds the "--folder" argument to `parser`.
+
+    Args:
+        parser: the parser of a command that uses the data folder.
+
+    """
     parser.add_argument(
         '--folder', type = pathlib.Path, default = None,
         help = 'the data folder (by default, the "crime" folder of the data '
@@ -119,14 +135,27 @@ def _add_folder(parser: argparse.ArgumentParser) -> None:
 
 
 def _add_years(parser: argparse.ArgumentParser) -> None:
-    """Adds the "years" argument to `parser`."""
+    """Adds the "years" argument to `parser`.
+
+    Args:
+        parser: the parser of a command that takes years.
+
+    """
     parser.add_argument(
         'years', nargs = '+',
         help = 'years or ranges of years, such as 2022 or 2015-2023')
 
 
 def _convert(arguments: argparse.Namespace) -> int:
-    """Converts master files to parquet files."""
+    """Converts master files to parquet files.
+
+    Args:
+        arguments: the parsed arguments of the "convert" command.
+
+    Returns:
+        The exit status, 0.
+
+    """
     converted = nibrs.convert(
         arguments.years, arguments.folder, tables = arguments.tables,
         overwrite = arguments.overwrite)
@@ -137,7 +166,15 @@ def _convert(arguments: argparse.Namespace) -> int:
 
 
 def _download(arguments: argparse.Namespace) -> int:
-    """Downloads master files."""
+    """Downloads master files.
+
+    Args:
+        arguments: the parsed arguments of the "download" command.
+
+    Returns:
+        The exit status, 0.
+
+    """
     for path in nibrs.download(
         arguments.years, arguments.folder, overwrite = arguments.overwrite):
         print(path)
@@ -145,7 +182,16 @@ def _download(arguments: argparse.Namespace) -> int:
 
 
 def _export(arguments: argparse.Namespace) -> int:
-    """Writes a table to a csv or parquet file."""
+    """Writes a table to a csv or parquet file.
+
+    Args:
+        arguments: the parsed arguments of the "export" command.
+
+    Returns:
+        The exit status: 0 if the table was written, or 2 if the output is
+            not a csv or parquet file.
+
+    """
     suffix = arguments.output.suffix.lower()
     if suffix not in ('.csv', '.parquet'):
         print('the output must be a .csv or .parquet file', file = sys.stderr)
@@ -169,7 +215,15 @@ def _export(arguments: argparse.Namespace) -> int:
 
 
 def _project(arguments: argparse.Namespace) -> int:
-    """Runs an amos project from a settings file."""
+    """Runs an amos project from a settings file.
+
+    Args:
+        arguments: the parsed arguments of the "project" command.
+
+    Returns:
+        The exit status, 0.
+
+    """
     import amos  # noqa: PLC0415
 
     project = amos.Project.create(arguments.settings)
@@ -180,7 +234,16 @@ def _project(arguments: argparse.Namespace) -> int:
 
 
 def _years(arguments: argparse.Namespace) -> int:  # noqa: ARG001
-    """Lists the years of NIBRS master files that the FBI has."""
+    """Lists the years of NIBRS master files that the FBI has.
+
+    Args:
+        arguments: the parsed arguments of the "years" command, which are
+            not used.
+
+    Returns:
+        The exit status, 0.
+
+    """
     found = nibrs.available_years()
     print(f'{found[0]}-{found[-1]}')
     return 0

{crimepy-0.2.0 → crimepy-0.2.2}/src/crimepy/combine.py

@@ -6,8 +6,9 @@ and `pandas.merge` does the same to the keys it joins on. These functions
 keep the categories, so combined tables stay small and keep their labels.
 
 They take `amos` datasets or data frames and return an `amos.Dataset`, which
-keeps the label, task, and groups of the first dataset given when its
-columns are still there.
+keeps the label, task, groups, and kinds (see `amos`'s `set_kinds`) of the
+first dataset given when its columns are still there. A label that is still
+pending (not yet a column) stays pending.
 
 Contents:
     merge: joins two tables, keeping their categories.
@@ -26,6 +27,8 @@ from pandas.api.types import union_categoricals
 
 from . import utilities
 
+""" Public Functions """
+
 
 def stack(
     tables: Iterable[amos.Dataset | pd.DataFrame],
@@ -64,7 +67,8 @@ def stack(
     if source is not None:
         names = list(labels) if labels is not None else list(range(len(frames)))
         frames = [
-            f.assign(**{source: name}) for f, name in zip(frames, names, strict = True)]
+            f.assign(**{source: name})
+            for f, name in zip(frames, names, strict = True)]
     columns = list(dict.fromkeys(c for f in frames for c in f.columns))
     categorical = [
         c for c in columns
@@ -114,7 +118,8 @@ def merge(
     keys = [on] if isinstance(on, str) else list(on)
     restore = {}
     items = [left, right]
-    left, right = utilities.to_frame(left).copy(), utilities.to_frame(right).copy()
+    left = utilities.to_frame(left).copy()
+    right = utilities.to_frame(right).copy()
     for key in keys:
         kinds = (left[key].dtype, right[key].dtype)
         if any(isinstance(k, pd.CategoricalDtype) for k in kinds):
@@ -122,13 +127,17 @@ def merge(
             left[key] = left[key].astype('object')
             right[key] = right[key].astype('object')
     joined = left.merge(
-        right, on = keys, how = how, suffixes = suffixes,  # type: ignore[arg-type]
+        right, on = keys,
+        how = how, suffixes = suffixes,  # type: ignore[arg-type]
         validate = validate)  # type: ignore[arg-type]
     for key in restore:
         joined[key] = joined[key].astype('category')
     return _dataset(joined, items)
 
 
+""" Private Functions """
+
+
 def _dataset(
     data: pd.DataFrame,
     items: Sequence[amos.Dataset | pd.DataFrame]) -> amos.Dataset:
@@ -139,16 +148,21 @@ def _dataset(
         items: the datasets and data frames that were combined.
 
     Returns:
-        A dataset with the label, task, and groups of the first dataset in
-            `items` whose label and groups are columns of `data` (and with
-            none if no dataset was given).
+        A dataset with the label, task, groups, and kinds of the first
+            dataset in `items` whose label, groups, and columns with kinds
+            are columns of `data` (and with none if no dataset was given). A
+            pending label (one that is not yet a column) stays pending.
 
     """
     first = next((i for i in items if isinstance(i, amos.Dataset)), None)
     if first is None:
         return amos.Dataset.create(data)
-    label = first.label if first.label in data.columns else None
+    kept = first.label in data.columns or not first.has_label
+    label = first.label if kept else None
     groups = [g for g in first.groups if g in data.columns]
-    return amos.Dataset.create(
+    dataset = amos.Dataset.create(
         data, label = label, task = first.task if label else None,
         seed = first.seed, groups = groups or None)
+    dataset.kinds = {
+        c: k for c, k in first.kinds.items() if c in data.columns}
+    return dataset

{crimepy-0.2.0 → crimepy-0.2.2}/src/crimepy/nibrs/__init__.py

@@ -7,17 +7,23 @@ publishes a master file of every year's reports from 1991 on, which `crimepy`
 downloads, parses, and makes into flat tables, each loaded as an
 `amos.Dataset` (whose `data` is a `pandas` data frame):
 
-| Table | One row for each |
-| --- | --- |
-| `agencies` | agency (its batch header): location, population, and months reported |
-| `administrative` | incident: date, hour, numbers of segments, and exceptional clearance |
-| `offenses` | offense of an incident: offense, location, weapons, and bias motivations |
-| `properties` | property loss of an incident: type of loss, description, value, and drugs |
-| `victims` | victim: offenses, age, sex, race, injuries, and relationships to offenders |
-| `offenders` | offender: age, sex, race, and ethnicity |
-| `arrestees` | arrestee of an incident: date and type of arrest, offense, and person |
-| `group_b_arrests` | arrestee of a Group "B" offense |
-| `window_clearances`, `window_properties`, `window_arrestees` | partial report of an incident that began before its agency reported to NIBRS |
+* `agencies`: one row for each agency (its batch header): location,
+  population, and months reported.
+* `administrative`: one row for each incident: date, hour, numbers of
+  segments, and exceptional clearance.
+* `offenses`: one row for each offense of an incident: offense, location,
+  weapons, and bias motivations.
+* `properties`: one row for each property loss of an incident: type of loss,
+  description, value, and drugs.
+* `victims`: one row for each victim: offenses, age, sex, race, injuries,
+  and relationships to offenders.
+* `offenders`: one row for each offender: age, sex, race, and ethnicity.
+* `arrestees`: one row for each arrestee of an incident: date and type of
+  arrest, offense, and person.
+* `group_b_arrests`: one row for each arrestee of a Group "B" offense.
+* `window_clearances`, `window_properties`, and `window_arrestees`: one row
+  for each partial report of an incident that began before its agency
+  reported to NIBRS.
 
 The tables of an incident share "data_year", "ori", and "incident_number",
 and `crimepy.nibrs.tables` joins them into tables for analysis (such as one

{crimepy-0.2.0 → crimepy-0.2.2}/src/crimepy/nibrs/cde.py

@@ -55,6 +55,9 @@ _BROKEN: tuple[type[Exception], ...] = (
     requests.Timeout)
 
 
+""" Public Functions """
+
+
 def available_years(*, timeout: float | None = None) -> list[int]:
     """Returns the years of NIBRS master files that the CDE has.
 
@@ -131,8 +134,7 @@ def download(
     if missing:
         message = (
             f'the CDE has NIBRS master files for {first} to {last}, so there '
-            f'are none for {missing}'
-        )
+            f'are none for {missing}')
         raise ValueError(message)
     paths = []
     for year in wanted:
@@ -174,6 +176,9 @@ def download_documentation(
     return path
 
 
+""" Private Functions """
+
+
 def _fetch(
     key: str,
     path: pathlib.Path,
@@ -327,6 +332,7 @@ def _year_range(timeout: float) -> tuple[int, int]:
 
     Raises:
         requests.HTTPError: if the CDE refuses the request.
+        ValueError: if the CDE does not list a NIBRS master file.
 
     Returns:
         The first and last years.