{"id":31838591,"url":"https://github.com/poisonalien/oncoprint-js","last_synced_at":"2026-01-20T16:42:58.386Z","repository":{"id":308726840,"uuid":"1033274526","full_name":"PoisonAlien/oncoprint-js","owner":"PoisonAlien","description":"Interative oncoprints","archived":false,"fork":false,"pushed_at":"2025-08-07T14:05:08.000Z","size":548,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-26T16:07:57.039Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/PoisonAlien.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-06T15:01:38.000Z","updated_at":"2025-08-07T14:05:11.000Z","dependencies_parsed_at":"2025-08-14T15:32:44.221Z","dependency_job_id":null,"html_url":"https://github.com/PoisonAlien/oncoprint-js","commit_stats":null,"previous_names":["poisonalien/oncoprint-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PoisonAlien/oncoprint-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PoisonAlien%2Foncoprint-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PoisonAlien%2Foncoprint-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PoisonAlien%2Foncoprint-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PoisonAlien%2Foncoprint-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PoisonAlien","download_url":"https://codeload.github.com/PoisonAlien/oncoprint-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PoisonAlien%2Foncoprint-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010150,"owners_count":26084692,"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-12T02:00:06.719Z","response_time":53,"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-12T03:27:58.875Z","updated_at":"2025-10-12T03:28:00.056Z","avatar_url":"https://github.com/PoisonAlien.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Oncoprint.js\n\n\u003cdiv align=\"left\"\u003e\n\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/poisonalien/oncoprint-js/ci.yml?branch=main)](https://github.com/poisonalien/oncoprint-js/actions)\n\n**A comprehensive JavaScript/TypeScript library for creating interactive oncoprint visualizations from MAF files and metadata.**\n\n\u003e **Beta Release** - This library is in beta. Core functionality is stable and well-tested, but the API may evolve based on user feedback.\n\n\u003c/div\u003e\n\n## Features\n\n- **Interactive Oncoprint Visualizations** - Create publication-ready oncoprints\n- **Dynamic Variant Classification** - Automatic color assignment for unknown mutation types\n- **Multiple Input Formats** - Support for MAF files, TSV, CSV, and JSON\n- **Customizable Styling** - Configurable colors, dimensions, and layouts\n- **Metadata Integration** - Support for clinical and sample metadata tracks\n- **React Components** - Ready-to-use React components and hooks\n- **Export Capabilities** - Export to SVG, PNG, and data formats\n- **Interactive Features** - Hover tooltips, click events, sorting, and filtering\n- **Responsive Design** - Auto-resize and mobile-friendly\n- **TypeScript Support** - Full type definitions included\n\n## Installation\n\n```bash\nnpm install @poisonalien/oncoprint-js\n```\n\nFor beta releases:\n\n```bash\nnpm install @poisonalien/oncoprint-js@beta\n```\n\nFor React usage, ensure you have React as a peer dependency:\n\n```bash\nnpm install react react-dom\n```\n\n## Quick Start\n\n### Vanilla JavaScript\n\n```javascript\nimport { OncoprintVisualizer } from '@poisonalien/oncoprint-js';\n\n// Create container element\nconst container = document.getElementById('oncoprint-container');\n\n// Initialize visualizer\nconst visualizer = new OncoprintVisualizer(container, {\n  cellWidth: 10,\n  cellHeight: 20,\n  geneLabels: true,\n  legend: true\n});\n\n// Load MAF data\nawait visualizer.loadMafFile(mafFile);\nvisualizer.render();\n```\n\n### React Component\n\n```jsx\nimport React from 'react';\nimport { Oncoprint } from '@poisonalien/oncoprint-js';\n\nfunction MyOncoprint() {\n  const handleCellClick = (gene, sample, mutation) =\u003e {\n    console.log(`Clicked: ${gene} in ${sample}`);\n  };\n\n  return (\n    \u003cOncoprint\n      mafFile={mafFile}\n      metadataFile={metadataFile}\n      config={{\n        cellWidth: 12,\n        cellHeight: 18,\n        geneLabels: true,\n        legend: true,\n        showPercentages: true\n      }}\n      width={800}\n      height={600}\n      onCellClick={handleCellClick}\n    /\u003e\n  );\n}\n```\n\n### React Hook\n\n```jsx\nimport React, { useRef } from 'react';\nimport { useOncoprint } from '@poisonalien/oncoprint-js';\n\nfunction MyAdvancedOncoprint() {\n  const containerRef = useRef(null);\n  \n  const {\n    loadMafData,\n    exportSVG,\n    sortGenesByFrequency,\n    mutationStats\n  } = useOncoprint({ \n    container: containerRef.current,\n    config: { cellWidth: 10, cellHeight: 20 }\n  });\n\n  return (\n    \u003cdiv\u003e\n      \u003cbutton onClick={() =\u003e loadMafData(myMafData)}\u003eLoad Data\u003c/button\u003e\n      \u003cbutton onClick={() =\u003e sortGenesByFrequency(true)}\u003eSort by Frequency\u003c/button\u003e\n      \u003cbutton onClick={() =\u003e exportSVG()}\u003eExport SVG\u003c/button\u003e\n      \u003cdiv ref={containerRef} style={{ width: '100%', height: '600px' }} /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## API Reference\n\n### OncoprintVisualizer\n\nThe main class for creating oncoprint visualizations.\n\n#### Constructor\n\n```typescript\nnew OncoprintVisualizer(container: HTMLElement, config?: OncoprintConfig)\n```\n\n#### Data Loading Methods\n\n```typescript\n// Load from files\nawait visualizer.loadMafFile(file: File): Promise\u003cValidationResult\u003e\nawait visualizer.loadMetadataFile(file: File): Promise\u003cValidationResult\u003e\n\n// Load from data arrays\nawait visualizer.loadMafData(data: MafData[]): Promise\u003cvoid\u003e\nawait visualizer.loadMetadataData(data: MetadataRow[]): Promise\u003cvoid\u003e\n```\n\n#### Rendering Methods\n\n```typescript\nvisualizer.render(): void\nvisualizer.update(config?: Partial\u003cOncoprintConfig\u003e): void\nvisualizer.resize(width?: number, height?: number): void\n```\n\n#### Export Methods\n\n```typescript\nvisualizer.exportSVG(): string\nawait visualizer.exportPNG(): Promise\u003cBlob\u003e\nvisualizer.exportData(): ProcessedData\n```\n\n#### Analysis Methods\n\n```typescript\nvisualizer.sortGenesByFrequency(descending?: boolean): void\nvisualizer.sortSamplesByMutationLoad(descending?: boolean): void\nvisualizer.sortSamplesByMetadata(field: string, ascending?: boolean): void\nvisualizer.filterByMutationFrequency(minFreq: number, maxFreq?: number): void\n```\n\n### Configuration Options\n\n```typescript\ninterface OncoprintConfig {\n  // Visual settings\n  cellWidth?: number;              // Default: 10\n  cellHeight?: number;             // Default: 20\n  geneLabels?: boolean;            // Default: true\n  sampleLabels?: boolean;          // Default: false\n  \n  // Color scheme\n  variantColors?: Record\u003cstring, string\u003e;\n  \n  // Metadata tracks\n  metadataFields?: string[];\n  metadataTrackHeight?: number;    // Default: 15\n  \n  // Sorting \u0026 ordering\n  sortGenes?: 'frequency' | 'alphabetical' | 'custom';\n  sortSamples?: 'mutation_load' | 'alphabetical' | 'custom';\n  customGeneOrder?: string[];\n  customSampleOrder?: string[];\n  \n  // Layout\n  showPercentages?: boolean;       // Default: false\n  legend?: boolean;                // Default: true\n  tooltips?: boolean;              // Default: true\n}\n```\n\n### Data Formats\n\n#### MAF Data Format\n\n```typescript\ninterface MafData {\n  Hugo_Symbol: string;             // Gene symbol (required)\n  Tumor_Sample_Barcode: string;    // Sample ID (required)\n  Variant_Classification: string;  // Mutation type (required)\n  Protein_Change?: string;         // Protein change (optional)\n  Chromosome?: string;             // Chromosome (optional)\n  Start_Position?: number;         // Genomic position (optional)\n  End_Position?: number;           // Genomic position (optional)\n}\n```\n\n#### Metadata Format\n\n```typescript\ninterface MetadataRow {\n  Tumor_Sample_Barcode: string;    // Must match MAF sample IDs\n  [key: string]: string | number;  // Any additional fields\n}\n```\n\n## Examples\n\n### Basic HTML Example\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003ctitle\u003eOncoprint Example\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cdiv id=\"oncoprint-container\" style=\"width: 100%; height: 600px;\"\u003e\u003c/div\u003e\n    \n    \u003cscript type=\"module\"\u003e\n        import { OncoprintVisualizer } from '@poisonalien/oncoprint-js';\n        \n        const container = document.getElementById('oncoprint-container');\n        const visualizer = new OncoprintVisualizer(container);\n        \n        // Sample data\n        const mafData = [\n            {\n                Hugo_Symbol: 'TP53',\n                Tumor_Sample_Barcode: 'Sample_1',\n                Variant_Classification: 'Missense_Mutation'\n            },\n            // ... more mutations\n        ];\n        \n        visualizer.loadMafData(mafData);\n        visualizer.render();\n    \u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Advanced React Example\n\n```jsx\nimport React, { useState, useRef } from 'react';\nimport { Oncoprint } from '@poisonalien/oncoprint-js';\n\nfunction AdvancedOncoprintExample() {\n  const [selectedGenes, setSelectedGenes] = useState([]);\n  const oncoprintRef = useRef(null);\n\n  const handleGeneSelection = (genes) =\u003e {\n    setSelectedGenes(genes);\n    oncoprintRef.current?.setGeneSelection(genes);\n  };\n\n  const handleExportData = () =\u003e {\n    const data = oncoprintRef.current?.exportData();\n    console.log('Exported data:', data);\n  };\n\n  return (\n    \u003cdiv\u003e\n      \u003cdiv className=\"controls\"\u003e\n        \u003cbutton onClick={() =\u003e handleGeneSelection(['TP53', 'KRAS'])}\u003e\n          Select Key Genes\n        \u003c/button\u003e\n        \u003cbutton onClick={handleExportData}\u003e\n          Export Data\n        \u003c/button\u003e\n      \u003c/div\u003e\n      \n      \u003cOncoprint\n        ref={oncoprintRef}\n        mafData={mafData}\n        metadataData={metadataData}\n        config={{\n          cellWidth: 8,\n          cellHeight: 16,\n          metadataFields: ['Cancer_Type', 'Stage', 'Age'],\n          showPercentages: true,\n          sortGenes: 'frequency'\n        }}\n        onGeneClick={(gene) =\u003e console.log('Gene clicked:', gene)}\n        onCellClick={(gene, sample) =\u003e console.log('Cell clicked:', gene, sample)}\n      /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## File Format Requirements\n\n### MAF File Format\n\nYour MAF file must contain at minimum these columns:\n\n- `Hugo_Symbol` - Gene symbol\n- `Tumor_Sample_Barcode` - Sample identifier  \n- `Variant_Classification` - Type of mutation\n\nOptional columns:\n- `Protein_Change` - Protein-level change\n- `Chromosome` - Chromosome number\n- `Start_Position` - Genomic start position\n- `End_Position` - Genomic end position\n\n### Metadata File Format\n\nTab-separated or comma-separated file with:\n\n- `Tumor_Sample_Barcode` - Must match MAF sample IDs\n- Additional columns for clinical/sample metadata\n\nExample:\n```\nTumor_Sample_Barcode\tCancer_Type\tStage\tAge\tGender\nSample_1\tLUAD\tStage II\t65\tMale\nSample_2\tBRCA\tStage I\t52\tFemale\n```\n\n## Mutation Type Colors\n\nDefault color scheme for common mutation types:\n\n- **Missense_Mutation**: Teal (#16a085)\n- **Nonsense_Mutation**: Dark Gray (#34495e)  \n- **Frame_Shift_Del**: Blue (#2980b9)\n- **Frame_Shift_Ins**: Red (#c0392b)\n- **Splice_Site**: Green (#27ae60)\n- **In_Frame_Del**: Orange (#f39c12)\n- **In_Frame_Ins**: Purple (#8e44ad)\n\nUnknown mutation types are automatically assigned colors from a predefined palette.\n\n## Development\n\n### Prerequisites\n\n- Node.js ≥ 16.0.0\n- npm ≥ 8.0.0\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/poisonalien/oncoprint-js.git\ncd oncoprint-js\n\n# Install dependencies\nnpm install\n\n# Build the library\nnpm run build\n\n# Run tests\nnpm test\n\n# Start development mode\nnpm run dev\n\n# Run examples server\nnpm run examples\n```\n\n### Reporting Issues\n\n- Use the [issue tracker](https://github.com/poisonalien/oncoprint-js/issues)\n- Include a minimal reproduction case\n- Specify your environment (browser, Node.js version, etc.)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoisonalien%2Foncoprint-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpoisonalien%2Foncoprint-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoisonalien%2Foncoprint-js/lists"}