# Getting Started

## Installation

Pick the packages you need:

| Package | Command |
|---|---|
| Core (SVG + JSON) | `dotnet add package MatPlotLibNet` |
| PNG & PDF export | `dotnet add package MatPlotLibNet.Skia` |
| DataFrame integration | `dotnet add package MatPlotLibNet.DataFrame` |
| Blazor components | `dotnet add package MatPlotLibNet.Blazor` |
| ASP.NET Core / SignalR | `dotnet add package MatPlotLibNet.AspNetCore` |
| Browser popup | `dotnet add package MatPlotLibNet.Interactive` |
| GraphQL | `dotnet add package MatPlotLibNet.GraphQL` |
| MAUI control | `dotnet add package MatPlotLibNet.Maui` |
| Avalonia 12 control | `dotnet add package MatPlotLibNet.Avalonia` |
| Uno Platform control | `dotnet add package MatPlotLibNet.Uno` |
| WPF control | `dotnet add package MatPlotLibNet.Wpf` |
| Geographic maps | `dotnet add package MatPlotLibNet.Geo` |
| Polyglot / Jupyter | `#r "nuget: MatPlotLibNet.Notebooks"` |

JavaScript (TypeScript + SignalR clients):

```bash
npm install @matplotlibnet/angular   # Angular
npm install @matplotlibnet/react     # React
npm install @matplotlibnet/vue       # Vue 3
```

> **Looking for more examples?** Browse the [Cookbook](https://xkqg.github.io/MatPlotLibNet/cookbook/) — runnable code with rendered images for every chart type.

---

## Your First Chart

```csharp
using MatPlotLibNet;
using MatPlotLibNet.Styling;

double[] x = [1, 2, 3, 4, 5];
double[] y = [2, 4, 3, 5, 1];

Plt.Create()
    .WithTitle("My First Chart")
    .Plot(x, y, line => { line.Color = Color.Blue; line.Label = "Data"; })
    .Save("chart.svg");
```

`Save()` auto-detects format from the file extension. No `Build()` call needed for simple file output.

---

## Output Formats

```csharp
Plt.Create().Plot(x, y).Save("chart.svg");    // SVG — built-in, zero dependencies
Plt.Create().Plot(x, y).Save("chart.json");   // JSON — portable, re-loadable
Plt.Create().Plot(x, y).Save("chart.png");    // PNG — requires MatPlotLibNet.Skia
Plt.Create().Plot(x, y).Save("chart.pdf");    // PDF — requires MatPlotLibNet.Skia

// Get strings directly
string svg  = Plt.Create().Plot(x, y).ToSvg();
string json = Plt.Create().Plot(x, y).ToJson();
```

### Setting up PNG/PDF

Register the Skia transforms once at startup:

```csharp
using MatPlotLibNet.Skia;

FigureExtensions.RegisterTransform(".png", new PngTransform());
FigureExtensions.RegisterTransform(".pdf", new PdfTransform());
```

---

## When You Need the Figure Object

If you need to pass the figure to Blazor components, publishers, or servers, call `.Build()`:

```csharp
var figure = Plt.Create().Plot(x, y).Build();

// Blazor component
<MplChart Figure="figure" />

// Publisher
await publisher.PublishSvgAsync("chart-1", figure);

// Interactive browser popup
await figure.ShowAsync();
```

---

## Subplots

```csharp
Plt.Create()
    .WithSize(1200, 600)
    .AddSubPlot(1, 2, 1, ax => ax.WithTitle("Line").Plot(x, y))
    .AddSubPlot(1, 2, 2, ax => ax.WithTitle("Bar").Bar(["A", "B", "C"], [10, 20, 15]))
    .Save("subplots.svg");
```

---

## Legend

```csharp
double[] temp     = [22.1, 23.4, 21.8, 24.2, 22.9];
double[] humidity = [61.0, 58.0, 65.0, 60.0, 63.0];

Plt.Create()
    .AddSubPlot(1, 1, 1, ax => ax
        .Plot(x, temp,     s => s.Label = "Temperature")
        .Plot(x, humidity, s => s.Label = "Humidity")
        .WithLegend(LegendPosition.UpperRight))
    .Save("legend.svg");
```

---

## DataFrame Package

Plot, compute indicators, and run regressions directly from `Microsoft.Data.Analysis.DataFrame` column names:

```csharp
dotnet add package MatPlotLibNet.DataFrame
```

```csharp
using MatPlotLibNet.DataFrame;

// Line/scatter/histogram from named columns
df.Line(x: "date", y: "price", hue: "ticker").Save("prices.svg");
df.Scatter(x: "longitude", y: "latitude", hue: "category").Save("map.svg");

// Technical indicators
double[] sma   = df.Sma("close", period: 20);
double[] rsi   = df.Rsi("close", period: 14);
var      bands = df.BollingerBands("close", period: 20);

// Polynomial regression + confidence band
double[] coefs = df.PolyFit("x", "y", degree: 2);
var      ci    = df.ConfidenceBand("x", "y", coefs, evalX);
```

---

## Prerequisites

- **.NET 10 SDK** (or .NET 8 for `MatPlotLibNet` and `MatPlotLibNet.Skia`)
- Visual Studio 2022 / VS Code / JetBrains Rider

---

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| SVG renders blank / axes only | Data arrays empty, all-NaN, or X range too narrow | Check your data before plotting; verify `x.Length > 0` |
| `Save("chart.png")` throws | `MatPlotLibNet.Skia` not installed | `dotnet add package MatPlotLibNet.Skia` and register transforms (see above) |
| Legend labels missing | Series added without `.Label` | Set `s.Label = "..."` in the configure lambda |
| Subplots overlap | No spacing configured | Add `.TightLayout()` or `.WithSubPlotSpacing(...)` |
| `ShowAsync()` hangs | `MatPlotLibNet.Interactive` not installed | `dotnet add package MatPlotLibNet.Interactive` |