---
title: "Working with blockr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Working with blockr}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

This guide walks you through building a complete data workflow in blockr. You'll learn how to import data, transform it, create a visualization, and export the results.

## The workspace

When you open blockr, you see a workspace where you can add and connect blocks. Each block performs a specific operation and shows a preview of its output.

Blocks are organized into categories:

- **Input** - Import Data
- **Transform** - Filter, Select, Calculate, Aggregate, Sort, and more
- **Plot** - ggplot, Theme, Facet, Grid
- **Output** - Export Data

## Building a workflow: Step by step

Let's build a workflow that loads data, filters it, and creates a chart.

### Step 1: Import your data

Add an **Import Data** block to load your dataset. You can:

- **From Browser** - Upload a file from your computer
- **From Server** - Browse files on a server (if configured)
- **From URL** - Load data from a web address

blockr automatically detects the file format and shows a preview of the data.

Supported formats: CSV, Excel, SPSS, SAS, Stata, Parquet, Feather.

### Step 2: Filter the data

Add a **Filter Rows** block and connect it to your data. This block lets you keep only the rows you need.

Use the dropdowns to:

1. Select a column
2. Choose a comparison (equals, greater than, contains, etc.)
3. Pick the value(s) to filter by

For example, to keep only rows where `cyl` equals 4:

- Column: `cyl`
- Comparison: `equals`
- Value: `4`

The preview updates immediately to show the filtered data.

For more complex filters with AND/OR logic, use **Filter (Advanced)** instead.

### Step 3: Select columns

Add a **Select Columns** block to choose which columns to keep.

Drag columns to reorder them. Toggle "Remove duplicates" to keep only unique rows.

### Step 4: Create a visualization

Add a **ggplot** block to create a chart.

1. Choose a chart type: point (scatter), bar, line, boxplot, histogram, etc.
2. Map columns to aesthetics:
   - **x** - Column for the horizontal axis
   - **y** - Column for the vertical axis (not needed for histogram)
   - **color** - Color points/bars by a column
   - **size** - Size points by a column

The chart updates as you make selections.

### Step 5: Export results

Add an **Export Data** block to save your results.

Choose a format:

- **CSV** - For spreadsheets and other tools
- **Excel** - With support for multiple sheets
- **Parquet** - For large datasets

Select **To Browser** to download the file, or **To Server** to save it to a configured location.

## More blocks

### Data transformation

| Block | What it does |
|-------|--------------|
| Filter Rows | Keep rows matching specific values |
| Filter (Advanced) | Filter with R expressions and AND/OR logic |
| Select Columns | Choose and reorder columns |
| Calculate Columns | Create new columns using formulas |
| Aggregate Data | Calculate totals, averages, counts (no coding) |
| Aggregate (Advanced) | Summarize with R expressions |
| Sort Rows | Order data by column values |
| Lookup & Merge | Combine tables by matching columns |
| Stack Tables | Combine tables vertically |
| Combine Side-by-Side | Place tables next to each other |
| Rename Columns | Change column names |
| Pick Rows | Select first N, last N, random sample, or min/max rows |
| Unpivot (Wide to Long) | Turn columns into rows |
| Pivot (Long to Wide) | Turn rows into columns |
| Split Column | Separate one column into multiple |
| Combine Columns | Merge columns into one |

### Visualization

| Block | What it does |
|-------|--------------|
| ggplot | Create scatter plots, bar charts, line graphs, histograms, and more |
| Theme | Customize colors, fonts, and styling |
| Facet | Split a plot into panels by a categorical variable |
| Grid | Arrange multiple plots into a single figure |

## Working with multiple inputs

Some blocks accept data from multiple sources:

- **Lookup & Merge** - Connect two data sources to combine them by matching columns
- **Stack Tables** - Connect multiple sources to stack them vertically
- **Grid** - Connect multiple plots to arrange them in a grid

## Tips

**Start simple.** Begin with one data source and one transformation. Add complexity gradually.

**Use previews.** Each block shows its output - use this to verify each step works correctly.

**Build incrementally.** Add one block at a time and check the result before continuing.

## Block reference

For detailed documentation on each block, see:

- Data Transformation Blocks [`vignette("blockr-dplyr-showcase", package = "blockr.dplyr")`](https://bristolmyerssquibb.github.io/blockr/showcase/dplyr.html)
- Visualization Blocks [`vignette("blockr-ggplot-showcase", package = "blockr.ggplot")`](https://bristolmyerssquibb.github.io/blockr/showcase/ggplot.html)
- Import/Export Blocks [`vignette("blockr-io-showcase", package = "blockr.io")`
](https://bristolmyerssquibb.github.io/blockr/showcase/io.html)