{"id":51747835,"url":"https://github.com/hyperphantasia/blue-pacific-dataviz","last_synced_at":"2026-07-28T03:31:05.871Z","repository":{"id":307207917,"uuid":"1028716936","full_name":"hyperphantasia/blue-pacific-dataviz","owner":"hyperphantasia","description":"dataWave submission for the Pacific Dataviz Challenge 2025.","archived":false,"fork":false,"pushed_at":"2026-02-27T13:34:15.000Z","size":3567,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-16T14:54:02.548Z","etag":null,"topics":["2050","competitive-programming","dashboard","data-integration","data-preparation-and-analysis","data-preprocessing-and-cleaning","data-visualization","data-visualization-dashboard","dataviz","exploratory-data-analysis","hackathon","indicators","javascript","jupyter-notebook","open-data","pacific-dataviz","regional-reports","reshaping-datasets","thematic-areas","waveplot"],"latest_commit_sha":null,"homepage":"https://brooks-code.github.io/blue-pacific-dataviz/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperphantasia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-30T00:48:20.000Z","updated_at":"2026-04-12T19:22:18.000Z","dependencies_parsed_at":"2025-07-30T02:56:28.825Z","dependency_job_id":"b809df5f-6a20-4e2c-ab4a-3da8ee4ef66d","html_url":"https://github.com/hyperphantasia/blue-pacific-dataviz","commit_stats":null,"previous_names":["brooks-code/blue-pacific-dataviz","hyperphantasia/blue-pacific-dataviz"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hyperphantasia/blue-pacific-dataviz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperphantasia%2Fblue-pacific-dataviz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperphantasia%2Fblue-pacific-dataviz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperphantasia%2Fblue-pacific-dataviz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperphantasia%2Fblue-pacific-dataviz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperphantasia","download_url":"https://codeload.github.com/hyperphantasia/blue-pacific-dataviz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperphantasia%2Fblue-pacific-dataviz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35632492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"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":["2050","competitive-programming","dashboard","data-integration","data-preparation-and-analysis","data-preprocessing-and-cleaning","data-visualization","data-visualization-dashboard","dataviz","exploratory-data-analysis","hackathon","indicators","javascript","jupyter-notebook","open-data","pacific-dataviz","regional-reports","reshaping-datasets","thematic-areas","waveplot"],"created_at":"2026-07-18T21:42:56.126Z","updated_at":"2026-07-18T21:42:56.784Z","avatar_url":"https://github.com/hyperphantasia.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dataWave: a dynamic analytical synthesis visualizer\n\n**Wave-inspired visual exploration of the Pacific regional dataset.**  \n\n![Banner Image](\u003c/img/laird_hamilton_bigone.jpg\u003e \"Surfing Teahupo'o.\")\n\u003cbr\u003eSurf your data the Laird Hamilton way... Teahupo'o. *(Source: surfer films/surfing magazine)*\n\n\u003e This repository contains the source code of the dataWave submission for the [Pacific Dataviz Challenge](https://pacificdatavizchallenge.org/).\n\u003e The source dataset was a messy Excel export. The challenge I set for myself wasn’t to craft a single data-narrative, but to *build a tool* that lets users “surf” a clean, pleasant visualization that delivers concentrated understanding of the data at a glance.\n\n## Table of Contents\n\n\u003cdetails\u003e\n\u003csummary\u003eContents - click to expand\u003c/summary\u003e\n\n- [dataWave: a dynamic analytical synthesis visualizer](#datawave-a-dynamic-analytical-synthesis-visualizer)\n  - [Table of Contents](#table-of-contents)\n  - [Demo](#demo)\n  - [Features](#features)\n  - [Tech Stack](#tech-stack)\n  - [Data processing](#data-processing)\n    - [Data structure](#data-structure)\n  - [Project structure](#project-structure)\n  - [Installation \\\u0026 Usage](#installation--usage)\n    - [Install](#install)\n    - [Serve the app](#serve-the-app)\n  - [Functional overview](#functional-overview)\n    - [Normalization process of the wave](#normalization-process-of-the-wave)\n  - [Customization](#customization)\n  - [Deployment guide](#deployment-guide)\n    - [Summary](#summary)\n  - [Contributing](#contributing)\n  - [Acknowledgements](#acknowledgements)\n  - [License](#license)\n\n\u003c/details\u003e\n\n## Demo\n\nA GitHub hosted version of the [dataWave](https://brooks-code.github.io/blue-pacific-dataviz/) is available live on gh-pages.\n\n![Banner Image](\u003c/img/data_pearls.gif\u003e \"Surfing Teahupo'o.\")\n\u003cbr\u003eConcept showcase.\n\n## Features\n\n- **Wave‑based representation** – each Pacific State appears as a set of “colored pearl” whose count reflects its share of the selected metric. States do share the same color palette as their subregional pars.\n- **Dynamic year \u0026 class switching** – instantly updates the chart without reload.\n- **Smooth CSS animations** – SCSS animated with possibility to pause/resume.\n- **Responsive tooltip** – animated tooltip, stays within viewport edges.\n- **Info panel** – animated character‑by‑character text, scroll‑locked while animations pause.\n- **Accessibility** – most interactive elements are keyboard‑navigable; tooltips use `aria‑label`‑compatible text.\n\n\u003e [!NOTE]\n\u003e **And what's the data about?** It's derived from a dataset that contains political, development, security, resource, climate, ocean, and technology metrics across Pacific states.\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| **Language** | JavaScript |\n| **Styling** | SCSS compiled to CSS |\n| **Animations** | CSS keyframes, `requestAnimationFrame` |\n| **Data** | `data.json` (pre‑processed) |\n| **Build** | esbuild |\n| **Deployment** | Static hosting on GitHub pages |\n\n## Data processing\n\nCurious about how to transition from an Excel spreadsheet to fully consumable data? The data processing notebook is available in the [processing](/processing/README.md) folder.\n\n### Data structure\n\nJSON data sample:\n\n```json\n[\n    {\n        \"group_id\": 1,\n        \"year\": 2022,\n        \"class_name\": \"Political Leadership and Regionalism\",\n        \"class_num\": 1,\n        \"indicator_summary\": \"Total development aid\",\n        \"subregion_code\": \"MEL\",\n        \"subregion_name\": \"Melanesia\",\n        \"state_code\": \"FJ\",\n        \"state_name\": \"Fiji\",\n        \"raw_values\": 561024940.0,\n        \"scaled_values\": 0.8506735359,\n        \"value_contribution_to_class\": 0.0305291251,\n        \"state_rank_per_class\": 6,\n        \"pct_missing_values\": 0.0\n    }\n]\n```\n\n| Field                         | Type    | Example                               | Description                                                         |\n|-------------------------------|---------|---------------------------------------|---------------------------------------------------------------------|\n| **group_id**                      | Integer | 1                                     | ID for the indicator grouping                                       |\n| **year**                          | Integer | 2022                                  | Year of the observation                                             |\n| **class_name**                    | String  | Political Leadership and Regionalism  | Human-readable class label                                          |\n| **class_num**                     | Integer | 1                                     | Numeric class identifier                                            |\n| **indicator_summary**             | String  | Total development aid                 | Short indicator description                                         |\n| **subregion_code**                | String  | MEL                                   | Subregion ISO-like code                                              |\n| **subregion_name**                | String  | Melanesia                             | Subregion name                                                      |\n| **state_code**                    | String  | FJ                                    | ISO-like state code                                                 |\n| **state_name**                    | String  | Fiji                                  | State name                                                          |\n| **raw_values**                    | Number  | 561024940.0                           | Raw numeric value for the indicator                                 |\n| **scaled_values**                 | Number  | 0.8506735359                          | Value after scaling/normalization                                   |\n| **value_contribution_to_class**   | Number  | 0.0305291251                          | Fractional contribution of this state to the class total            |\n| **state_rank_per_class**          | Integer | 6                                     | Rank of the state within this class (1 = highest)                   |\n| **pct_missing_values**            | Number  | 0.0                                   | Proportion of missing values for this indicator                   |\n\n## Project structure\n\n```markdown\n├── .github/\n│   └── workflows/\n│       └── deploy.yml\n├── package.json\n├── build.js\n└── src/\n   ├── app.js\n   ├── favicon.ico\n   ├── img/\n   │   └── dataWave-preview.jpg\n   ├── index.html\n   ├── styles.scss\n   └── data.json\n```\n\n## Installation \u0026 Usage\n\nClone or download the repository:\n\n```bash\ngit clone https://github.com/brooks-code/blue-pacific-dataviz.git\ncd blue-pacific-dataviz\n```\n\n### Install\n\nMake sure you have **Node.js** (v. 23+) already installed on your system.\n\n```bash\nnpm -v\n```\n\nIf not, [install](https://www.geeksforgeeks.org/node-js/installation-of-node-js-on-linux/) it and then:\n\n```bash\nnpm install\n```\n\n### Serve the app\n\n```bash\nnpm run serve   # open http://localhost:displayed_portnumber\n```\n\nIf you only need to build the app, prefer this:\n\n```bash\nnpm run build   # outputs to ./dist\n```\n\n## Functional overview\n\n1) DATA PREPARATION\n\nLoad constants/lookups and convert raw data into normalized shares per year/class/state.\n\n*Key functions:*\n\n- `aggregateAndNormalize(raw)` groups, sums, normalizes to shares; returns `byYearClass`, years, classes.\n- `distributeWaves(entries, totalWaves)`: fair-rounding to allocate discrete wave counts.\n\n2) WAVE‑CHART RENDERER \u0026 CONTROLS\n\nBuild interactive wave visualization, controls and tooltip interactions.\n\n*Key functions:*\n\n- `populateControls()`: initialize UI handlers.\n- `renderChart()`: create waves from data, sort entries and fill remainder\n- `createWaveElement(bg, dataAttrs)`: DOM for one wave, `setAnimationState(paused)` and event handlers: `onWaveHover`, `onWaveOut`, `onWaveMove`.\n\n3) TITLE MORPHING\n\nAnimated morphing headline that cycles through phrases with pause on hover and loop control.\n\n*Key functions:*\n\n- `initMorph()`: initialize and start loop.\n- `tickMorph(nowMs)`: animation frame loop.\n- `setMorph(frac)` and `doCooldown()`: apply visual blending/blur.\n\n4) INFO‑PANEL\n\nAnimate an info panel with per-character text animation and interaction that pauses main animations.\n\n*Key functions:*\n\n- `getTextNodes(root)`: collect text nodes.\n- `wrapAllCharacters(container, step)`: wrap characters in spans with staggered delays.\n- `initInfoPanel()`: panel open/close handlers, interaction to pause/resume animations.\n\n### Normalization process of the wave\n\nThe concept is to aggregate values per year, class, and state and:\n\n- Compute shares – each state’s contribution is divided by the class total for that year.\n\n- Fair‑rounding – distribute a fixed number of waves (`WAVE_COUNT = 100`) proportionally, **guaranteeing** at least one pearl for any non‑zero share.\n\nThe resulting `byYearClass` map is used by the renderer to assign wave counts and tooltip data.\n\n## Customization\n\n- **Color palette:** edit `STATE_COLORS` in src/index.js (hex values per state code).\n- **Background wave color:** adjust `DFLT_BG` (RGBA string).\n- **Morphing texts:** update `morphTexts` array in the “Title Morphing” section.\n- **Animation speed:** tweak CSS animation-duration in *styles.scss* (e.g., `.wave_fade`).\n\n## Deployment guide\n\n1) Quick manual deploy with **gh-pages**:\n\nMake sure homepage in `package.json` is set properly:\n\n```json\n\"homepage\": \"https://brooks-code.github.io/blue-pacific-dataviz\" # Replace with yours!\n```\n\nInstall gh-pages:\n\n```bash\nnpm install gh-pages --save-dev\n```\n\nCommit package.json changes:\n\n```bash\ngit add package.json\ngit commit -m \"Configure gh-pages deployment\"\ngit push origin main\n```\n\nDeploy:\n\n```bash\nnpm run deploy\n```\n\nThis runs the build and pushes the contents of dist/ to the gh-pages branch. Wait a minute or two, then your site will be live at:\n\n- https://brooks-code.github.io/blue-pacific-dataviz in this case.\n\n---\n\n2) Automated deploy with GitHub Actions\n\nVerify there is a workflow file at `.github/workflows/deploy.yml` (example below). It builds the project on pushes to main and deploys the `dist/` folder to GitHub Pages.\n\n\u003cdetails\u003e\n\u003csummary\u003e`deploy.yml` example:\u003c/summary\u003e\n\nYou might need to set some Workflow permissions in the repo's settings before proceeding.\n\n```yaml\nname: Deploy static content to Pages\n\non:\n  push:\n    branches: [ 'main' ]\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: 'pages'\n  cancel-in-progress: true\n\njobs:\n  deploy:\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Set up Node\n        uses: actions/setup-node@v4\n        with:\n          node-version: lts/*\n          cache: 'npm'\n          persist-credentials: false\n          fetch-depth: 0\n      - name: Install dependencies\n        run: npm ci\n      - name: Build\n        run: npm run build\n      - name: Setup Pages\n        uses: actions/configure-pages@v5\n      - name: Upload artifact\n        uses: actions/upload-pages-artifact@v3\n        with:\n          path: './dist'\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4\n```\n\n\u003c/details\u003e\n\n### Summary\n\n- **Local usage:** `npm install` → `npm run serve` for preview.\n- **Manual deploy:** `npm install gh-pages --save-dev` → `npm run deploy`.\n- **CI deploy:** add `.github/workflows/deploy.yml` to automate builds and publish `dist/` to GitHub Pages.\n\n## Contributing\n\n1) Fork the repository.\n2) Create a feature branch (git checkout -b feature/your‑feature).\n3) Commit your changes (git commit -m \"Add …\").\n4) Push and open a Pull Request.\n\nPlease ensure:\n\n- SCSS changes are compiled before committing.\n- All new features are documented in this README.\n\n## Acknowledgements\n\nThe pacific dataviz team! Thanks, it's been a lot of fun working on that challenge. 🖤\n\n## License\n\nThis project is released into the public domain under the [Unlicense](https://unlicense.org/). See the [LICENSE](/LICENSE) file for details. The original dataset remains the property of the original owner.\n\n🃋\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperphantasia%2Fblue-pacific-dataviz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperphantasia%2Fblue-pacific-dataviz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperphantasia%2Fblue-pacific-dataviz/lists"}