Working with blockr

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")`
- Visualization Blocks `vignette("blockr-ggplot-showcase", package = "blockr.ggplot")`
- Import/Export Blocks `vignette("blockr-io-showcase", package = "blockr.io")`