{"id":32154007,"url":"https://github.com/technocrat/statebins.jl","last_synced_at":"2026-02-19T13:34:07.997Z","repository":{"id":308080514,"uuid":"1030049287","full_name":"technocrat/StateBins.jl","owner":"technocrat","description":"Julia functions to create cartograms of the US States, District and Columbia","archived":false,"fork":false,"pushed_at":"2025-08-01T02:31:16.000Z","size":11,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-26T09:47:54.761Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/technocrat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-01T02:30:45.000Z","updated_at":"2025-08-06T16:36:54.000Z","dependencies_parsed_at":"2025-08-05T08:33:02.662Z","dependency_job_id":null,"html_url":"https://github.com/technocrat/StateBins.jl","commit_stats":null,"previous_names":["technocrat/statebins.jl"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/technocrat/StateBins.jl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technocrat%2FStateBins.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technocrat%2FStateBins.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technocrat%2FStateBins.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technocrat%2FStateBins.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/technocrat","download_url":"https://codeload.github.com/technocrat/StateBins.jl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technocrat%2FStateBins.jl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280256208,"owners_count":26299341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-21T11:49:08.675Z","updated_at":"2025-10-21T11:49:14.213Z","avatar_url":"https://github.com/technocrat.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StateBins.jl\n\nA Julia package for creating statebins (state binned choropleth maps) visualizations adapted from the R package statesbin (©2015 by Bob Rudis). StateBins provide an alternative to traditional geographic maps by representing each US state as an equally-sized square arranged in a grid that roughly approximates the geographic layout of the United States.\n\n## Features\n\n- **Two backend options**: Simple Plots.jl interface and full-featured Makie.jl interface\n- **Automatic state detection**: Works with state names or abbreviations\n- **Adaptive text coloring**: State labels automatically switch between light/dark for optimal contrast\n- **Customizable styling**: Full control over colors, sizes, fonts, and layout (Makie backend)\n- **Sensible defaults**: Works out-of-the-box with minimal configuration\n\n## Installation\n\n```julia\nusing Pkg\nPkg.add(\"StateBins\")\n```\n\n## Quick Start\n\n### Plots.jl Backend (Simple)\n\n```julia\nusing StateBins, DataFrames, Plots\n\n# Create sample data\ndata = DataFrame(\n    state = [\"California\", \"Texas\", \"Florida\", \"New York\", \"Pennsylvania\"],\n    population = [39.5, 29.7, 22.6, 19.3, 13.0]\n)\n\n# Create statebins plot\nstatebins_plots(data, \n    state_col=\"state\", \n    value_col=\"population\",\n    title=\"State Population (millions)\")\n```\n\n### Makie.jl Backend (Full-featured)\n\n```julia\nusing StateBins, DataFrames, CairoMakie  # or GLMakie, WGLMakie\n\n# Create sample data with state abbreviations\ndata = DataFrame(\n    state = [\"CA\", \"TX\", \"FL\", \"NY\", \"PA\"],\n    gdp = [3.6, 2.4, 1.1, 2.0, 0.9]\n)\n\n# Create customized statebins plot\nstatebins_makie(data,\n    state_col=\"state\",\n    value_col=\"gdp\", \n    title=\"State GDP (trillions USD)\",\n    colorscheme=:plasma,\n    font_size=14,\n    show_colorbar=true,\n    colorbar_label=\"GDP ($ trillions)\")\n```\n\n## API Reference\n\n### `statebins_plots(data::DataFrame; kwargs...)`\n\nSimple Plots.jl-based statebins with minimal customization options.\n\n**Arguments:**\n- `data::DataFrame`: Input data with state and value columns\n- `state_col::String=\"state\"`: Name of the state column (accepts state names or abbreviations)\n- `value_col::String=\"value\"`: Name of the value column  \n- `title::String=\"\"`: Plot title\n\n### `statebins_makie(data::DataFrame; kwargs...)`\n\nFlexible Makie-based statebins with extensive customization options.\n\n**Arguments:**\n- `data::DataFrame`: Input data with state and value columns\n- `state_col::String=\"state\"`: Name of the state column\n- `value_col::String=\"value\"`: Name of the value column\n- `title::String=\"\"`: Plot title\n- `colorscheme=:viridis`: Color scheme for mapping values\n- `font_size::Int=12`: Font size for state labels\n- `marker_size::Real=35`: Size of state markers\n- `margin_factor::Float64=0.3`: Margin around text as fraction of text size\n- `auto_size::Bool=true`: Whether to automatically calculate marker size\n- `show_labels::Bool=true`: Whether to show state abbreviations\n- `show_colorbar::Bool=true`: Whether to show the colorbar\n- `border_color=\"white\"`: Color of marker borders\n- `border_width::Real=2`: Width of marker borders\n- `figure_size::Tuple=(800, 600)`: Figure dimensions\n- `hide_decorations::Bool=true`: Whether to hide axis decorations\n- `colorbar_label::String=\"\"`: Label for the colorbar\n- `text_color_threshold::Float64=0.179`: Luminance threshold for text color switching\n\n### `STATE_COORDS`\n\nA DataFrame containing the coordinate grid positions for all US states, DC, Puerto Rico, Virgin Islands, and New York City. Contains columns:\n- `abbrev`: State abbreviations\n- `state`: Full state names  \n- `col`: Grid column position\n- `row`: Grid row position\n\n## Examples\n\n### Election Results\n\n```julia\nusing StateBins, DataFrames, CairoMakie\n\n# 2020 Presidential election results (example data)\nelection_data = DataFrame(\n    state = [\"AL\", \"AK\", \"AZ\", \"AR\", \"CA\", \"CO\", \"CT\", \"DE\", \"FL\", \"GA\"],\n    margin = [-25.8, -10.1, 0.3, -27.7, 29.2, 13.5, 20.1, 19.0, -3.4, 0.2]\n)\n\nstatebins_makie(election_data,\n    state_col=\"state\",\n    value_col=\"margin\", \n    title=\"2020 Presidential Election Margins\",\n    colorscheme=:RdBu,\n    colorbar_label=\"Democratic Margin (%)\")\n```\n\n### Economic Data\n\n```julia\n# State unemployment rates\nunemployment = DataFrame(\n    state = [\"California\", \"Texas\", \"Florida\", \"New York\", \"Illinois\"],\n    rate = [4.2, 3.8, 3.1, 4.1, 4.9]\n)\n\nstatebins_plots(unemployment,\n    value_col=\"rate\",\n    title=\"State Unemployment Rates (%)\")\n```\n\n## Requirements\n\n- Julia ≥ 1.9\n- DataFrames.jl ≥ 1.6\n- Colors.jl ≥ 0.13  \n- ColorSchemes.jl ≥ 3.24\n- Plots.jl (for `statebins_plots`)\n- A Makie.jl backend (CairoMakie, GLMakie, or WGLMakie for `statebins_makie`)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n## License\n\nThis package is available under the MIT License.\n\n## Acknowledgments\n\nInspired by the original statebins concept and similar implementations in R and Python.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnocrat%2Fstatebins.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnocrat%2Fstatebins.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnocrat%2Fstatebins.jl/lists"}