crimepy 0.1.0__tar.gz

crimepy-0.1.0/.cruft.json

@@ -0,0 +1,33 @@
+{
+  "template": "https://github.com/WithPrecedent/snickerdoodle",
+  "commit": "51b83c5f5273e9f66d7860b84f574b58f08050c4",
+  "checkout": null,
+  "context": {
+    "cookiecutter": {
+      "project_name": "crimepy",
+      "package_name": "crimepy",
+      "repo_name": "crimepy",
+      "author_name": "Corey Rayburn Yung",
+      "author_email": "coreyrayburnyung@gmail.com",
+      "github_user": "WithPrecedent",
+      "description": "Accessible tools for downloading, combining, munging, analyzing, and plotting crime data",
+      "version": "0.0.1",
+      "url": "https://github.com/WithPrecedent/crimepy",
+      "development_status": "Development Status :: 3 - Alpha",
+      "license": "Apache Software License 2.0",
+      "badge_style": "for-the-badge",
+      "github_actions": true,
+      "pre_commit": true,
+      "dependabot": true,
+      "mkdocs": true,
+      "mypy": true,
+      "pypi": true,
+      "code_coverage": true,
+      "commit_to_github": false,
+      "virtual_environment": false,
+      "_template": "https://github.com/WithPrecedent/snickerdoodle",
+      "_commit": "51b83c5f5273e9f66d7860b84f574b58f08050c4"
+    }
+  },
+  "directory": null
+}

crimepy-0.1.0/.editorconfig

@@ -0,0 +1,31 @@
+# Sets default formatting options for many editors and IDEs
+
+# https://editorconfig.org/
+
+root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+indent_size = 4
+indent_style = space
+trim_trailing_whitespace = true
+
+# Docstrings and comments use max_line_length = 80
+[*.py]
+max_line_length = 80
+
+# The JSON files contain newlines inconsistently
+[*.json]
+indent_size = 2
+insert_final_newline = ignore
+
+# Makefiles always use tabs for indentation
+[Makefile]
+indent_style = tab
+
+[*.{yml,yaml,toml,html}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

crimepy-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: unconfirmed
+assignees: ''
+
+---
+
+**Describe the bug**
+
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Run command '...'
+3. Scroll down to '...'
+4. See error
+
+**Expected behavior**
+
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+
+If applicable, add screenshots to help explain your problem.
+
+**System (please complete the following information):**
+
+- `crimepy` version: [e.g. 0.2.1]
+- Python version: [e.g. 3.12]
+- OS: [Windows/Linux/MacOS]
+
+**Additional context**
+Add any other context about the problem here.

crimepy-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: feature
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+
+Add any other context or screenshots about the feature request here.

crimepy-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+# Automatically updates dependency versions using dependabot.
+
+version: 2
+updates:
+
+# Maintains the Python dependencies in `pyproject.toml` and `uv.lock`
+- package-ecosystem: uv
+  directory: "/"
+  schedule:
+    interval: weekly
+
+# Maintains the versions of the GitHub Actions used in `.github/workflows`
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: weekly

crimepy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,150 @@
+# Automatically performs jobs upon a commit push or pull-request
+
+# This Action builds, tests, and lints the package. It uploads test
+# coverage to Codecov. Then, it builds the
+# documentation and deploys it on GitHub Pages.
+
+# If the commit message matches a semantic version (e.g. "v0.1.2"), a GitHub
+# release will be created by the `create_github_release` job.
+
+name: continuous integration
+
+# Allows this Action to be called by a push to `main` or a pull request. Only
+# pushes to `main` are included so that a pull request does not run every job
+# twice (once for the push to its branch and once for the pull request).
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: write
+  pull-requests: write
+  # Lets the Codecov upload authenticate with OIDC instead of a stored token.
+  id-token: write
+
+env:
+  DISABLE_MKDOCS_2_WARNING: "true"
+
+jobs:
+
+  build_and_test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    # Makes every `uv` command use the matrix version. Otherwise, `uv run`
+    # recreates the environment with the version in ".python-version".
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+
+    steps:
+    - name: checkout repository
+      uses: actions/checkout@v7
+
+    - name: install python
+      uses: actions/setup-python@v7
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: install uv
+      uses: astral-sh/setup-uv@v10.2.0
+
+    - name: install dependencies
+      run: uv sync
+
+    - name: run tests
+      run: uv run pytest tests --cov --cov-report=xml
+
+    # Requires the Codecov GitHub App to be installed on the repository's
+    # account. Codecov merges the uploads from every job in the matrix.
+    - name: upload coverage to codecov
+      uses: codecov/codecov-action@v7
+      with:
+        files: coverage.xml
+        use_oidc: true
+
+  lint_and_format:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: checkout repository
+      uses: actions/checkout@v7
+
+    - name: install uv
+      uses: astral-sh/setup-uv@v10.2.0
+
+    - name: install dependencies
+      run: uv sync
+
+    # The hooks only need to run once, so they are here instead of in the
+    # `build_and_test` matrix.
+    - name: run pre-commit
+      run: uv run pre-commit run -a --show-diff-on-failure
+
+    - name: run ruff
+      run: uv run ruff check --no-fix --output-format=github
+
+    - name: run mypy
+      run: uv run mypy
+
+  document_and_deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: checkout repository
+      uses: actions/checkout@v7
+
+    - name: install uv
+      uses: astral-sh/setup-uv@v10.2.0
+
+    - name: install dependencies
+      run: uv sync
+
+    # Creates the HTML report that `mkdocs-coverage` adds to the documentation.
+    - name: create coverage report
+      run: uv run pytest tests --cov --cov-report=html
+
+    - name: build documentation with mkdocs
+      run: uv run mkdocs build
+
+    - name: deploy documentation to github pages
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      run: uv run mkdocs gh-deploy --force --clean --verbose
+
+  # Only releases if a line of the commit message is a semantic version (e.g.
+  # "v0.1.2"), so the version can be followed by other lines, such as a
+  # "Co-Authored-By:" trailer. The release notes are the version's section of
+  # CHANGELOG.md. Releases are only made from the `main` branch and after the
+  # tests and linters pass.
+  create_github_release:
+    name: create github release
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [build_and_test, lint_and_format]
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: checkout repository
+      uses: actions/checkout@v7
+
+    - name: create github release
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        version=$(git log -1 --format=%B | grep -m 1 -oxE 'v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?' | cut -c 2- || true)
+        if [ -z "$version" ]; then
+          echo "The commit message has no version line, so no release was made."
+          exit 0
+        fi
+        if gh release view "v$version" > /dev/null 2>&1; then
+          echo "::notice::Release v$version already exists."
+          exit 0
+        fi
+        awk -v v="$version" '$1 == "##" && $2 == v {found = 1; next} found && /^## / {exit} found' CHANGELOG.md > notes.md
+        if ! grep -q '[^[:space:]]' notes.md; then
+          echo "::error::Could not find an entry for $version in CHANGELOG.md"
+          exit 1
+        fi
+        gh release create "v$version" --title "Release: $version" --notes-file notes.md --target "$GITHUB_SHA"

crimepy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+# Securely publishes the repository on PyPI
+
+
+# To make this action work, you need to configure PyPI properly, using this
+# guide: https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+
+name: publish
+
+# Allows this Action to be called by other Actions or through GitHub
+on: [workflow_call, workflow_dispatch]
+
+jobs:
+
+  pypi_publish:
+    name: publish to pypi
+    runs-on: ubuntu-latest
+    permissions:
+      # This permission is needed for private repositories.
+      contents: read
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    steps:
+    - name: get repository
+      uses: actions/checkout@v7
+
+    - name: install uv
+      uses: astral-sh/setup-uv@v10.2.0
+
+    - name: build package
+      run: uv build
+
+    - name: push to pypi
+      run: uv publish

crimepy-0.1.0/.github/workflows/validate_codecov.yml

@@ -0,0 +1,15 @@
+name: validate_codecov
+
+on:
+  pull_request:
+    paths: [codecov.yml]
+  push:
+    branches: [main]
+
+jobs:
+  validate-codecov-config:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Validate codecov configuration
+        run: curl -sSL --fail-with-body --data-binary @codecov.yml https://codecov.io/validate

crimepy-0.1.0/.gitignore

@@ -0,0 +1,139 @@
+# Byte-compiled
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer Logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit Testing
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask
+instance/
+.webassets-cache
+
+# Scrapy
+.scrapy
+
+# Sphinx
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pipenv
+Pipfile.lock
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder
+.spyderproject
+.spyproject
+
+# Rope
+.ropeproject
+
+# MkDocs
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre
+.pyre/
+
+# VS Code
+.vscode/
+
+# VS Code counter
+.VSCodeCounter/
+
+# PyCharm
+.idea/
+
+# PDM
+.copier-answers.yml
+.idea/
+.pdm-plugins/
+.pdm-python
+__pypackages__/
+
+# Cython
+cython_debug/
+
+# Ruff
+/.ruff_cache/

crimepy-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+repos:
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: "v6.0.0"
+  hooks:
+  - id: check-added-large-files
+    # The lock file lists every package and its hashes.
+    exclude: ^uv\.lock$
+  - id: check-ast
+  - id: check-json
+  - id: check-toml
+  - id: detect-private-key
+  - id: end-of-file-fixer
+  - id: trailing-whitespace
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.16.9
+  hooks:
+    # Run the linter. The formatter is not used because it removes the spaces
+    # around "=" in keyword arguments and moves closing brackets onto their own
+    # lines (see CONTRIBUTING.md).
+    - id: ruff
+      args: [ --fix ]
+
+- repo: https://github.com/astral-sh/uv-pre-commit
+  # uv version.
+  rev: 0.12.20
+  hooks:
+    - id: uv-lock
+
+- repo: https://github.com/jsh9/pydoclint
+  rev: 0.10.1
+  hooks:
+    - id: pydoclint
+      args:
+        - --style=google
+        - --check-return-types=False
+        - --arg-type-hints-in-docstring=False
+        - --check-class-attributes=False
+        - --skip-checking-raises=True

crimepy-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

crimepy-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+<!-- insertion marker -->
+
+## 0.1.0
+
+* **Breaking:** `crimepy` is built on `amos` datasets.
+  `crimepy.nibrs.load`, `load_tables`, `read`, and `tables.build` (and its
+  builders) return `amos.Dataset`s, whose `data` is the table, and take
+  `label`, `task`, and `groups` for modeling. `crimepy.nibrs.load_frame`
+  returns a plain data frame, as `load` did. `crimepy.combine.stack` and
+  `merge` return datasets, and `crimepy.analyze.count` returns a new dataset
+  of counts, whose label is the counts.
+* Every analysis is an `amos` technique: `population_rates`, `crime_rates`,
+  `percent_change`, `crosstab`, and `coverage` join `count_crimes`,
+  `crime_trend`, and `clearance_rates`. The functions of `crimepy.analyze`
+  apply them, take datasets or data frames, and keep their tables in a
+  dataset's `tables`. `crime_rates` loads the agencies of the data's years
+  and states when it is given none.
+* The functions of `crimepy.plot` take datasets, which keep their figures in
+  `figures`, and `crimepy.nibrs.decode` decodes a dataset in place.
+* Downloads of master files that break (as they do when the CDE's 15-minute
+  link expires during a slow download) resume where they stopped, with a new
+  link.
+* `crimepy` requires `amos` 0.4.1.
+* The README has a BibTeX entry for citing `crimepy`, and `CITATION.cff` has
+  the date of the release.
+
+## 0.0.1
+
+* Initial version, from the `snickerdoodle` template, built on `amos`.
+* `crimepy.nibrs` downloads the FBI's NIBRS master files for any year from
+  1991 (`download`), converts them to parquet files (`convert`), and loads
+  their tables into `pandas` for any years, states, and columns (`load`).
+  It reads every era of the files: the three batch header records before
+  2013, the fields added in 2013, fixed-length and variable-length records,
+  and archives compressed with Deflate64.
+* `crimepy.nibrs.layouts` has the position of every field, from the FBI's
+  record descriptions and from fields found in the files, and
+  `crimepy.nibrs.codes` has the label of every code.
+* `crimepy.nibrs.tables` joins the segments of incidents into tables of
+  incidents, victims, offenses, offenders, and arrestees, with the details
+  of their incidents and agencies.
+* `crimepy.combine` stacks and joins tables while keeping their categories.
+* `crimepy.analyze` counts events, makes trends, crime rates, clearance
+  rates, and cross-tabulations, and measures reporting coverage.
+* `crimepy.plot` draws trends, the most common values, events by hour and
+  day, and age pyramids.
+* `amos` techniques: `load_nibrs`, `decode_nibrs`, `count_crimes`,
+  `crime_trend`, `clearance_rates`, `trend_plot`, `top_values`,
+  `time_heatmap`, and `age_pyramid`.
+* A command line interface: `crimepy nibrs years`, `download`, `convert`,
+  and `export`, and `crimepy project`.

crimepy-0.1.0/CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+message: "If you use crimepy in your research, please cite it as below."
+type: software
+title: "crimepy: Accessible tools for downloading, combining, munging, analyzing, and plotting crime data"
+abstract: >-
+  A Python package that downloads the FBI's National Incident-Based
+  Reporting System (NIBRS) master files for any year, turns them into flat
+  tables for pandas, joins the segments of incidents, and analyzes and plots
+  the results, built on amos for reproducible empirical research.
+authors:
+  - given-names: Corey Rayburn
+    family-names: Yung
+    email: coreyrayburnyung@gmail.com
+    orcid: "https://orcid.org/0000-0001-6524-9956"
+version: 0.1.0
+date-released: 2026-10-26
+license: Apache-2.0
+repository-code: "https://github.com/WithPrecedent/crimepy"
+url: "https://WithPrecedent.github.io/crimepy"
+keywords:
+  - crime
+  - criminology
+  - empirical legal studies
+  - fbi
+  - nibrs
+  - open science
+  - reproducibility
+  - uniform crime reporting

crimepy-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,79 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting any of the following people:
+
+* Corey Rayburn Yung (coreyrayburnyung@gmail.com)
+
+All complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq