Usage Guide
===========

Basic Plotting
--------------

Use ``plot()`` for the fastest path to any chart type:

.. code-block:: python

   from glyphx import plot

   # Line chart
   plot([1, 2, 3, 4], [5, 7, 3, 9], kind="line",
        color="#2563eb", label="Series A",
        xlabel="X Axis", ylabel="Y Axis", title="Line Chart")

   # Bar chart with categorical X axis
   plot(["Mon","Tue","Wed","Thu","Fri"], [42, 61, 38, 75, 53],
        kind="bar", color="#7c3aed", title="Daily Active Users")

   # Scatter plot with colormap encoding
   plot(x_data, y_data, kind="scatter",
        c=color_values, cmap="viridis", size=7)

   # Histogram from raw data
   import numpy as np
   plot(data=np.random.normal(50, 10, 500), kind="hist", bins=25)

   # Pie chart
   plot(data=[35, 28, 22, 15], kind="pie",
        labels=["Product A","Product B","Product C","Other"])

.. image:: examples/basic_plotting.svg
   :alt: Scatter plot with viridis continuous color encoding
   :width: 760px
   :align: center

.. image:: examples/histogram.svg
   :alt: Bimodal histogram
   :width: 760px
   :align: center


Method Chaining
---------------

Every mutating ``Figure`` method returns ``self``, enabling full fluent chains:

.. code-block:: python

   from glyphx import Figure
   from glyphx.series import LineSeries, BarSeries

   fig = (
       Figure(width=800, height=500)
       .set_title("Revenue Dashboard")
       .set_theme("dark")
       .set_size(900, 520)
       .set_xlabel("Month")
       .set_ylabel("USD ($M)")
       .set_legend("top-left")
       .add(LineSeries(months, revenue, color="#60a5fa", label="Revenue", width=2.5))
       .add(LineSeries(months, costs, color="#f87171", label="Costs", linestyle="dashed"))
       .annotate("Record High", x=11, y=2.9, arrow=True, color="#fbbf24")
       .tight_layout()
       .share("dashboard.html")
   )

Chainable ``Figure`` methods:

.. list-table::
   :widths: 35 65
   :header-rows: 1

   * - Method
     - Description
   * - ``.add(series, use_y2=False)``
     - Add a series; bind to right Y-axis with ``use_y2=True``
   * - ``.set_title(text)``
     - Set chart title
   * - ``.set_theme(name_or_dict)``
     - Apply a named or custom theme
   * - ``.set_size(width, height)``
     - Resize canvas
   * - ``.set_xlabel(text)``
     - X-axis label
   * - ``.set_ylabel(text)``
     - Y-axis label
   * - ``.set_legend(position)``
     - Legend position or ``False`` to hide
   * - ``.annotate(text, x, y, ...)``
     - Add a text annotation with optional arrow
   * - ``.add_stat_annotation(x1, x2, p_value)``
     - Add a significance bracket
   * - ``.tight_layout()``
     - Auto-adjust padding and rotate crowded labels
   * - ``.enable_crosshair()``
     - Synchronized crosshair across all charts on the page
   * - ``.show()``
     - Display (Jupyter or browser)
   * - ``.save(filename)``
     - Save to ``.svg``, ``.html``, ``.png``, ``.jpg``, or ``.pptx``
   * - ``.share(filename, title)``
     - Self-contained, zero-CDN HTML


DataFrame Accessor
------------------

Import ``glyphx`` once and every ``pd.DataFrame`` gains a ``.glyphx`` namespace.
All methods return a ``Figure`` for further chaining:

.. code-block:: python

   import pandas as pd
   import glyphx          # registers the .glyphx accessor

   df = pd.read_csv("sales.csv")

   # Basic charts
   df.glyphx.line(x="date",    y="revenue", title="Daily Revenue")
   df.glyphx.bar( x="product", y="units",   title="Units by Product")
   df.glyphx.scatter(x="spend", y="conversions")
   df.glyphx.hist(col="response_time", bins=20)
   df.glyphx.box(col="score", groupby="treatment_group")
   df.glyphx.pie(labels="category", values="share")
   df.glyphx.heatmap()        # uses all numeric columns

   # Groupby aggregation in one call
   df.glyphx.bar(
       groupby="region",
       y="revenue",
       agg="sum",             # sum | mean | count | max | min
       title="Revenue by Region",
   )

   # Full chain from the accessor
   (df.glyphx
      .bar(x="month", y="revenue", label="Revenue", auto_display=False)
      .set_theme("colorblind")
      .add_stat_annotation("Jan", "Jun", p_value=0.001)
      .set_xlabel("Month")
      .set_ylabel("Revenue ($M)")
      .share("monthly_report.html"))

.. image:: examples/pandas_example.svg
   :alt: Bar chart generated via the DataFrame accessor
   :width: 760px
   :align: center


Dual Y-Axis
-----------

Bind any series to the secondary (right-hand) Y-axis with ``use_y2=True``:

.. code-block:: python

   from glyphx import Figure
   from glyphx.series import LineSeries, BarSeries

   fig = Figure(width=800, height=480)
   fig.set_title("Price & Volume")
   fig.add(LineSeries(dates, prices, color="#2563eb", label="Price (left)"))
   fig.add(BarSeries(dates, volume, color="#d97706", label="Volume (right)"),
           use_y2=True)
   fig.show()

.. image:: examples/dual_y.svg
   :alt: Dual Y-axis line and bar chart
   :width: 760px
   :align: center


Auto Display
------------

GlyphX detects its runtime environment automatically:

- **Jupyter notebook** — renders inline as an SVG cell output
- **CLI / script** — writes a temporary HTML file and opens it in the default browser
- **IDE** — falls back to the browser viewer

To suppress auto-display (e.g. when building charts to export only):

.. code-block:: python

   fig = Figure(auto_display=False)
   fig.save("chart.html")   # explicit save, no auto-open


Export and Sharing
------------------

.. code-block:: python

   fig.save("chart.svg")        # vector SVG
   fig.save("chart.html")       # interactive HTML (zoom, pan, tooltips, export buttons)
   fig.save("chart.png")        # raster PNG  — requires: pip install "glyphx[export]"
   fig.save("chart.jpg")        # raster JPG  — requires: pip install "glyphx[export]"
   fig.save("chart.pptx")       # PowerPoint  — requires: pip install "glyphx[pptx]"

   # Self-contained HTML — zero external dependencies
   html = fig.share()                    # returns HTML string
   fig.share("report.html")             # also writes to disk
   fig.share("report.html", title="Q3") # custom <title> tag

``fig.share()`` inlines all JavaScript into a single file that works in email
clients, Confluence, Notion, GitHub Pages, and offline environments.


Log Scale
---------

Pass ``xscale`` or ``yscale`` to the ``Figure`` constructor:

.. code-block:: python

   fig = Figure(yscale="log")
   fig.add(LineSeries(x, y))
   fig.show()


Natural Language Chart Generation
----------------------------------

Requires ``pip install "glyphx[nlp]"`` and an ``ANTHROPIC_API_KEY`` environment variable.

.. code-block:: python

   from glyphx import from_prompt
   import pandas as pd

   df = pd.read_csv("sales.csv")

   fig = from_prompt("bar chart of total revenue by region, dark theme", df=df)
   fig = from_prompt("scatter plot showing a strong positive correlation")
   fig = from_prompt("top 10 products by revenue, sorted descending", df=df)


CLI Tool
--------

Plot any CSV, JSON, or Excel file directly from the terminal:

.. code-block:: bash

   glyphx plot sales.csv --x month --y revenue --kind bar -o chart.html
   glyphx plot data.csv --x date --y revenue --kind line --theme dark --open
   glyphx suggest data.csv
   glyphx version

Supported input formats: ``.csv`` ``.tsv`` ``.json`` ``.jsonl`` ``.xlsx`` ``.xls``

Supported output formats: ``.svg`` ``.html`` ``.png`` ``.jpg`` ``.pptx``
