> For the complete documentation index, see [llms.txt](https://docs.datalovelace.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datalovelace.app/nodules.md).

# Nodules

Manipulate Your Data

## The Power of Nodules

Tables me be foundational to Lovelace, but Nodules are the power! After you have imported some tables, you can perform some pretty nifty calculations on them. First we will explore the common configuration options that all nodules share. Then we will continue by exploring the three available types of `Nodules` that are available in the UI of Lovelace.

Just like a `Table`, a `Nodule` needs you to give it a label value, so you can find it later. Then we can import the tables that we want to perform our operations on. After that, lets select which type of operation we want to perform!

{% hint style="info" %}
Quick Note: More than one table can be imported to a Nodule at a time; incase you have data of the same shape spread into several files.
{% endhint %}

#### Filter Nodule

A `Filter Nodule` is something you might want to use if you want to limit your data set by only certain criteria. Choose this option by selecting the `Filter Nodule` in the create `Nodule` form.

For example lets look at my current data:

| Ticket Number | Equipt Cert # | Debris Type |
| ------------- | ------------- | ----------- |
| 32M3ZF6       | 7JVX6PM       | VEG         |
| 7ZMKT7A       | 86FAPL8       | VEG         |
| 3NF2S89       | 5GVW8QZ       | C\&D        |

I want to have a new dataset consisting of rows that only have the Debris Type equaling `VEG`.

To do this I will start by selecting the `Comparison Type` of `Equal`. Then I will enter `Debris Type` into the `Key` field. Along with it I will enter `VEG` into the `Value` field directly beside it. The `Add` button must also be selected to confirm that filter option. Now I will select `Confirm` to create my `Nodule`.

Now my new `Nodule` should show up in the `Nodule` list just as my table did. I can also delete my `Nodule` and view the data it exports just as I could the `Table`(s) that I imported into it.

{% hint style="info" %}
Quick Note: A Filter Nodule may have many Key | Value sets, but only one Comparison Type at a time. Remember that when manipulating your data.
{% endhint %}

#### Join Nodule

The `Join Nodule` is a little more involved than the `Filter Nodule`. You would use a `Join` if you have multiple tables that have data that related to one another by some kind of identifier.

Lets build upon the data from earlier. I have this `Table` called `Operations`:

| Ticket Number | Project Name       | Equipt Cert # | Debris Type |
| ------------- | ------------------ | ------------- | ----------- |
| EDG5D5        | Birmingham Cleanup | 56TF9D        | VEG         |
| RF567T        | Birmingham Cleanup | E4GQ1         | C\&D        |
| EFBE0R        | Birmingham Cleanup | 56TF9D        | C\&D        |

And I have another `Table` called `Equipment Certifications`:

| Type          | Placard | Active |
| ------------- | ------- | ------ |
| Grapple Truck | 56TF9D  | true   |
| Trailer       | E4GQ1   | false  |

Now each one of my Operations has a related piece of equipment stored in the `Equipment Certification` table. I want to be able to merge the row of the related piece of equipment on to each Operation. That is where the `Join Nodule` comes in handy.

I can see that each Operation has a `Equipt Cert #` column that correlates with the `Placard` of the `Equipment Certification` We will use that in our `Join`.

After we have selected the `Join Nodule` type in the form and the imported tables, we need to set what our `Primary Table` will be. This is the table related rows in other tables will be merged into. For us the `Primary Table` will be `Operations`.

Then we will select the `Primary Key` of `Equpt Cert #`. 

Next lets select the `Foreign Table` as our `Equipment Certifications`.

Now lets select the `Foreign Key` of `Placard`.

Hold up, lets look at the why of those options again. In an `Operation` row, we have a, `Equipt Cert #` and this related to a piece of `Equipment Certification` by the `Placard`. So this will give us a new table with `Operations` combined with related `Equipment Certifications` like so:

| Ticket Number | Project Name       | Equipt Cert # | Debris Type | Equipment Certification::Type | Equipment Certification::Placard | Equipment Certification::Status |
| ------------- | ------------------ | ------------- | ----------- | ----------------------------- | -------------------------------- | ------------------------------- |
| EDG5D5        | Birmingham Cleanup | 56TF9D        | VEG         | Grapple Truck                 | 56TF9D                           | true                            |
| RF567T        | Birmingham Cleanup | E4GQ1         | C\&D        | Trailer                       | E4GQ1                            | false                           |
| EFBE0R        | Birmingham Cleanup | 56TF9D        | C\&D        | Grapple Truck                 | 56TF9D                           | true                            |

{% hint style="warning" %}
If you are getting unexpected results, consider switching your Primary and Foreign Tables, you may have confused the direction of the Join.
{% endhint %}

This is an extremely powerful and sometimes confusing Nodule, lets move on to something a little simpler, but just as useful.

#### Transform Nodule

The `Transform Nodule` allows you to see only the data points you want to see and how you want to see them.

For instance, my latest dataset has some complicated column headers. I also do not care to have some of them. I want this:

| Ticket Number | Project Name       | Equipt Cert # | Debris Type | Equipment Certification::Type | Equipment Certification::Placard | Equipment Certification::Status |
| ------------- | ------------------ | ------------- | ----------- | ----------------------------- | -------------------------------- | ------------------------------- |
| EDG5D5        | Birmingham Cleanup | 56TF9D        | VEG         | Grapple Truck                 | 56TF9D                           | true                            |
| RF567T        | Birmingham Cleanup | E4GQ1         | C\&D        | Trailer                       | E4GQ1                            | false                           |
| EFBE0R        | Birmingham Cleanup | 56TF9D        | C\&D        | Grapple Truck                 | 56TF9D                           | true                            |

To look like this:

| Ticket Number | Debris Type | Equipment Type | Equipment Placard |
| ------------- | ----------- | -------------- | ----------------- |
| EDG5D5        | VEG         | Grapple Truck  | 56TF9D            |
| RF567T        | C\&D        | Trailer        | E4GQ1             |
| EFBE0R        | C\&D        | Grapple Truck  | 56TF9D            |

So after selecting the `Transform Nodule` type and importing my previous table, I am going to enter some values into the `Initial Key` and `New Key` fields in the form. The `Initial Key` field is for the name of the header that currently exist in the `Table`. The `New Key` field is for what you want it to be called.

{% hint style="info" %}
Only the columns you enter will be the columns you return, even if you do not want to change the name of any column. This is why I have some Initial Keys identical to the New Keys
{% endhint %}

This is what i would need to enter to achieve the results I am looking for:

| Initial Key                      | New Key           |
| -------------------------------- | ----------------- |
| Ticket Number                    | Ticket Number     |
| Debris Type                      | Debris Type       |
| Equipment Certification::Type    | Equipment Type    |
| Equipment Certification::Placard | Equipment Placard |

Make sure to select `Add` after each `Key` set to apply the configuration options.

{% hint style="warning" %}
Other Nodules can not be imported as Tables. To convert Nodules into Table, select the "To Table" option on the Nodule List Item. It will then be an option as a Table to Import as well as appear in the Table List.
{% endhint %}

That is it for Nodules in the UI of Lovelace. They do not take to long to set up and once you get use to the configuration options you will be able to do outstanding mutations on your data. If you are a JavaScript Developer you can take advantage of the `GroupByNodule` with the library `lovelacejs` on NPM! 

Next up, lets start visualizing your data as charts!