🌌 技術調査 - Cosmograph 2.0

npm install @cosmograph/cosmograph

npm install @cosmograph/react

pip install cosmograph

# インストール済みバージョンを確認
npm list @cosmograph/cosmograph
npm list @cosmograph/react

# レジストリの最新バージョンを確認
npm view @cosmograph/cosmograph version
npm view @cosmograph/react version

pip show cosmograph

const config = {
  points: [
    { id: '1', idx: 0, status: 'active' },
    { id: '2', idx: 1, status: 'inactive' },
  ],
  pointColorBy: 'status',
  pointColorStrategy: 'map',
  pointColorByMap: {
    'active': '#4caf50',     // 16 進文字列
    'inactive': [244, 67, 54, 1], // RGBA 配列
  },
}

import { prepareCosmographData, CosmographDataPrepConfig } from '@cosmograph/cosmograph'

const dataConfig: CosmographDataPrepConfig = {
  points: { pointIdBy: 'id' },
  links: { linkSourceBy: 'source', linkTargetsBy: ['target'] },
}

const rawPoints = [
  { id: 'a', value: 10 },
  { id: 'b', value: 20 },
  { id: 'c', value: 30 },
]
const rawLinks = [
  { source: 'a', target: 'b' },
  { source: 'b', target: 'c' },
]

// Arrow 形式に変換（非同期）
const result = await prepareCosmographData(dataConfig, rawPoints, rawLinks)
// result: { points, links, cosmographConfig, pointsSummary, linksSummary,
//           pointsProcessedFully, linksProcessedFully }

import { prepareCosmographDataFiles } from '@cosmograph/cosmograph'

const filesResult = await prepareCosmographDataFiles(dataConfig, rawPoints, rawLinks)
// filesResult.points / filesResult.links が Blob

import { downloadCosmographData } from '@cosmograph/cosmograph'

await downloadCosmographData(
  {
    points: { pointIdBy: 'id', outputFilename: 'my-graph-points' },
    links: { linkSourceBy: 'source', linkTargetsBy: ['target'], outputFilename: 'my-graph-links' },
  },
  rawPoints,
  rawLinks
)

import { Cosmograph, prepareCosmographData } from '@cosmograph/cosmograph'

// 1. データ準備
const dataConfig = {
  points: { pointIdBy: 'id' },
  links: { linkSourceBy: 'source', linkTargetsBy: ['target'] },
}
const result = await prepareCosmographData(dataConfig, rawPoints, rawLinks)
if (!result) return

const { points, links, cosmographConfig } = result

// 2. DOM 要素を取得してインスタンスを生成
const container = document.getElementById('graph') as HTMLElement
const cosmograph = new Cosmograph(container, {
  points,
  links,
  ...cosmographConfig,
})

new Cosmograph(
  containerElement: HTMLElement,
  config: CosmographConfig,
  duckDbConnection?: string | WasmDuckDBConnection
)

cosmograph.setConfig({ showDynamicLabels: true, pointSizeRange: [2, 12] })

import React, { useEffect, useState } from 'react'
import { Cosmograph, CosmographConfig, prepareCosmographData } from '@cosmograph/react'

const rawPoints = [
  { id: 'a', category: 'A' },
  { id: 'b', category: 'B' },
  { id: 'c', category: 'A' },
]
const rawLinks = [
  { source: 'a', target: 'b' },
  { source: 'b', target: 'c' },
  { source: 'c', target: 'a' },
]

export const GraphComponent = () => {
  const [config, setConfig] = useState<CosmographConfig>({})

  useEffect(() => {
    const load = async () => {
      const dataConfig = {
        points: { pointIdBy: 'id' },
        links: { linkSourceBy: 'source', linkTargetsBy: ['target'] },
      }
      const result = await prepareCosmographData(dataConfig, rawPoints, rawLinks)
      if (result) {
        const { points, links, cosmographConfig } = result
        setConfig({ points, links, ...cosmographConfig })
      }
    }
    load()
  }, [])

  return <Cosmograph {...config} />
}

import pandas as pd
from cosmograph import cosmo

points = pd.DataFrame({
    'id': [1, 2, 3, 4, 5],
    'label': ['Node A', 'Node B', 'Node C', 'Node D', 'Node E'],
    'value': [10, 20, 15, 25, 30],
    'category': ['A', 'B', 'A', 'B', 'A'],
})

links = pd.DataFrame({
    'source': [1, 2, 3, 1, 2],
    'target': [2, 3, 4, 5, 4],
    'value': [1.0, 2.0, 1.5, 0.5, 1.8],
})

widget = cosmo(
    points=points,
    links=links,
    point_id_by='id',
    link_source_by='source',
    link_target_by='target',
    point_color_by='category',
    point_label_by='label',
    point_size_by='value',
    point_include_columns=['value'],
    link_include_columns=['value'],
)
widget  # セルの最後に置くとノートブック内に描画される

widget = cosmo(
    points=points,
    point_id_by='id',
    point_color_by='category',
    point_size=12,
    point_size_scale=1.5,
    links=links,
    link_source_by='source',
    link_target_by='target',
    link_color='#666666',
    link_width=2,
    link_arrows=True,
    curved_links=False,
    # シミュレーション
    disable_simulation=False,
    simulation_repulsion=0.4,
    simulation_link_spring=1.5,
    simulation_link_distance=3,
    simulation_gravity=0.1,
    simulation_friction=0.8,
    simulation_decay=2000,
    # 表示
    background_color='#0a0a0a',
    scale_points_on_zoom=True,
    initial_zoom_level=1.2,
    # ラベル
    show_top_labels=True,
    show_top_labels_limit=20,
    show_hovered_point_label=True,
    # パフォーマンス
    pixel_ratio=2,
    show_FPS_monitor=True,
)
widget

from cosmograph import set_api_key
set_api_key("your-api-key-here")

import { prepareCosmographData } from '@cosmograph/cosmograph'

// File オブジェクト（input[type=file] 等から取得）
const parquetFile: File = event.target.files[0]  // .parquet ファイル

const result = await prepareCosmographData(
  { points: { pointIdBy: 'id' }, links: { linkSourceBy: 'src', linkTargetsBy: ['dst'] } },
  parquetFile,
  'https://example.com/links.arrow'  // URL 文字列も渡せる
)

import { Cosmograph, CosmographTimeline } from '@cosmograph/cosmograph'

const cosmograph = new Cosmograph(container, config)

const timelineContainer = document.getElementById('timeline') as HTMLElement
const timeline = new CosmographTimeline(cosmograph, timelineContainer, {
  accessor: 'timestamp',
  showAnimationControls: true,
  animationSpeed: 100,
  initialSelection: [new Date('2024-01-01'), new Date('2024-12-31')],
  onSelection: (selection, isManual) => {
    console.log('Selected range:', selection, 'Manual:', isManual)
  },
})

// アニメーション制御
timeline.playAnimation()
timeline.pauseAnimation()
timeline.stopAnimation()

// 選択範囲の取得と設定
const current = timeline.getCurrentSelection()
timeline.setSelection([new Date('2024-06-01'), new Date('2024-09-30')])

import { Cosmograph, CosmographHistogram } from '@cosmograph/cosmograph'

const cosmograph = new Cosmograph(container, {
  points,
  links,
  ...cosmographConfig,
  // Histogram で使うカラムを事前に含める
  pointIncludeColumns: ['pagerank'],
  linkIncludeColumns: ['weight'],
})

const histogramContainer = document.getElementById('histogram') as HTMLElement
const histogram = new CosmographHistogram(cosmograph, histogramContainer, {
  accessor: 'pagerank',
  useQuantiles: true,
  highlightSelectedData: true,
  onSelection: (selection) => {
    console.log('Histogram selection:', selection)
  },
})

histogram.setSelection([0.1, 0.9])

import { Cosmograph, CosmographSearch } from '@cosmograph/cosmograph'

const cosmograph = new Cosmograph(container, config)

const searchContainer = document.getElementById('search') as HTMLElement
const search = new CosmographSearch(cosmograph, searchContainer, {
  accessor: 'name',
  placeholderText: 'ノードを検索...',
  showAccessorsMenu: true,
  suggestionFields: { name: '名前', category: 'カテゴリ' },
  debounceTime: 200,
  onInput: (value, results, event) => {
    console.log('Input:', value, 'Results:', results)
  },
  onSelect: (item) => {
    console.log('Selected:', item)
  },
})

search.focus()
search.clearInput()

// シミュレーションを開始（alpha=1.0 がデフォルト：最大エネルギー）
graph.start(alpha?: number)   // alpha 範囲: 0.0〜1.0

// シミュレーションを一時停止（状態を保持）
graph.pause()

// 一時停止から再開
graph.unpause()

// 完全停止
graph.stop()

// 1 フレームだけ進める（デバッグ・静的確認用）
graph.step()

// 実行状態の確認
const running: boolean = graph.isSimulationRunning

widget.start(alpha=1.0)   # シミュレーション開始
widget.pause()            # 一時停止
widget.restart()          # 再開
widget.step()             # 1 ステップ実行

const cosmograph = new Cosmograph(container, {
  points,
  links,
  ...cosmographConfig,
  enableSimulation: false,  // リンクがないか座標が提供済なら自動で無効
  pointXBy: 'x',
  pointYBy: 'y',
})

const config: CosmographConfig = {
  onSimulationStart:   () => console.log('started'),
  onSimulationEnd:     () => console.log('converged'),
  onSimulationPause:   () => console.log('paused'),
  onSimulationTick:    (alpha) => console.log('tick', alpha),
}

// 保存：シミュレーション収束を onSimulationEnd で検知して全座標を取得
const config: CosmographConfig = {
  onSimulationEnd: () => {
    const flat = cosmograph.getPointPositions() // [x0, y0, x1, y1, ...]
    const layout = rawPoints.map((p, i) => ({
      id: p.id,
      x: flat[i * 2],
      y: flat[i * 2 + 1],
    }))
    localStorage.setItem('graph_layout', JSON.stringify(layout))
  },
}

// 復元：保存済み座標を points に付与し、再シミュレーションを無効化
const savedLayout = JSON.parse(localStorage.getItem('graph_layout') || '[]')
const layoutMap = new Map(savedLayout.map((e: { id: string; x: number; y: number }) => [e.id, e]))
const pointsWithLayout = rawPoints.map(p => ({
  ...p,
  x: (layoutMap.get(p.id) as { x: number })?.x ?? 0,
  y: (layoutMap.get(p.id) as { y: number })?.y ?? 0,
}))
const restoreConfig: CosmographConfig = {
  pointXBy: 'x',
  pointYBy: 'y',
  enableSimulation: false,
}

project_id = widget.export_project_by_name("my-network-2026")

const config: CosmographConfig = {
  showFPSMonitor: true,   // WebGL FPS モニタを表示（default: false）
  pixelRatio: 2,          // デバイスピクセル比（default: 2）
}

widget = cosmo(show_FPS_monitor=True, pixel_ratio=2, ...)

// 設定のみ更新（データ再投入なし）
cosmograph.setConfig({ simulationRepulsion: 0.8 })

// データと設定を同時更新
cosmograph.setConfig({ points, links, ...cosmographConfig })

// 現在の設定を取得
const current = cosmograph.getConfig()

const dataConfig: CosmographDataPrepConfig = {
  points: {
    pointIdBy: 'id',
    pointIncludeColumns: ['category', 'value'],  // 必要列だけ
  },
  links: {
    linkSourceBy: 'source',
    linkTargetsBy: ['target'],
    linkIncludeColumns: ['weight'],
  },
}

const config: CosmographConfig = {
  pixelRatio: 1,              // Retina 画面での GPU 負荷を半減（品質とのトレードオフ）
  renderLinks: false,         // リンクが多い場合、非表示で劇的に高速化
  scalePointsOnZoom: false,   // ズーム中の再計算を省略
}

const histogramConfig = {
  highlightSelectedData: false,  // true は全点を再評価するため重い（default: true）
}

# Python: 埋め込み可視化の典型パターン
widget = cosmo(
    points=points_df,
    point_id_by='id',
    point_x_by='umap_x',
    point_y_by='umap_y',
    disable_simulation=True,
    render_links=False,
    point_label_by='label',
)

// 大規模グラフ（50 万ノード以上）向けの初期値例
const config: CosmographConfig = {
  simulationRepulsion: 0.5,
  simulationGravity: 0.1,
  simulationFriction: 0.9,
  simulationDecay: 10000,
  simulationLinkSpring: 0.8,
  simulationLinkDistance: 5,
}

// ズーム時のコールバック内などで代表点だけを取得する
const sampledPositions = cosmograph.getSampledPointPositionsMap()
renderLabelsOverlay(sampledPositions)

const config: CosmographConfig = {
  enableSimulation: false,
  pointXBy: 'x',
  pointYBy: 'y',
  renderLinks: false,
  scalePointsOnZoom: true,
  showTopLabels: true,
  showTopLabelsLimit: 30,
  showHoveredPointLabel: true,
}

// 初期化完了を待ってからアクセス
console.log('isSimulationRunning:', graph.isSimulationRunning)
console.log('zoomLevel:', graph.getZoomLevel())
console.log('config:', graph.getConfig())

// 1 ステップだけ進めて位置を確認
graph.step()
const pos = cosmograph.getPointPositions() // [x0, y0, x1, y1, ...]
console.log('positions sample:', pos?.slice(0, 10))

# Python: デバッグ向け単一ステップ実行
widget.step()
print(widget.clicked_point_id)
print(widget.selected_point_ids[:5])