Adding Data

You can add any kind of data to an Aspen project, so long as you can write enough Ruby to convert non-Aspen data to Aspen.

Locally Stored Data

Locally stored data is any data that lives on your computer. The section Remote Resources will go over data stored on the internet.

You can add data directly by storing it in the src folder. Data must be easily read by a Ruby program, ideally in CSV format. If you have a more complex spreadsheet (like an Excel file), export the data to CSV.

Tutorial

In src, create a new file and save it as data.csv.

Paste the following content into the file:

Origin,Origin_Type,Verb,Target,Target_Type
Liz,Person,KNOWS,Jack,Person
Tracy,Person,IS FRIENDS WITH,Kenneth,Person
Tracy,Person,OWNS,Reef shark,Animal
Reef shark,Animal,NEEDS,A bathtub with a reef,Object

Now open up bin/convert in your code editor. Add the following code below the requires and includes:

Aspen.convert.csv('src/data.csv').to_aspen do |csv_file, aspen_file|
  csv_file.each do |row|
    aspen_file << [
      Aspen.node(row['Origin_Type'] => row['Origin']),
      Aspen.edge(row['Verb'].downcase),
      Aspen.node(row['Target_Type'] => row['Target']),
    ].join(" ")
  end
end

This script loops through the spreadsheet, and creates a line of Aspen for every row. It sets the values in Object_Type and Target_Type as labels, Object and Target as the attribute values, and Verb as the edge.

This script will create a file in src/data.aspen

The resulting Aspen file will look like this:

(Person: Liz) [knows] (Person: Jack)
(Person: Tracy) [is friends with] (Person: Kenneth)
(Person: Tracy) [owns] (Animal: Reef shark)
(Animal: Reef shark) [needs] (Object: A bathtub with a reef)

Aspen#convert, Aspen#node, and Aspen#edge are all special helper functions stored in Aspen::Helpers and Aspen::Conversion.

This bin/convert script gets run every time you run aspen build.

Remote Resources

You can also add remote resources from Airtable. (Google Sheets support is not yet ready.)

To add a remote resource, put the following block in manifest.yml (in the project root folder).

Let's imagine the Airtable looks like the CSV above, but we only want the Origin, Verb, and Target columns.

attached:
  -
    name:   30 Rock Data      # This is just the display name, it doesn't have to line up with the actual Airtable.
    source: airtable
    app_id: appNxxxxxxxxNxxxN # When viewing your Airtable, this is the part of the URL that comes after airtable.com
    table:  Tracy Jordan      # The name of the table in Airtable
    columns:                  # List the columns you want to download.
      - Origin
      - Verb
      - Target

During the build process, this Airtable will be downloaded into a CSV file in src based off the display name, so in this case it would be src/30_rock_data.csv. Only the columns listed in the columns key will be included in the CSV.

If you don't want the resource to download every time you run aspen build (to save build time and/or network data), you can set a cache time. In manifest.yml, add this line towards the bottom and all the way to the left (not part of the attached block):

cache_seconds: 300

Now, any remote resources will only download if it's been more than 300 seconds (5 minutes) since the last download.

You then have to write a script in bin/convert to take this file and turn it into Aspen. For example:

Aspen.convert.csv('src/data.csv').to_aspen do |csv_file, aspen_file|
  csv_file.each do |row|
    aspen_file << [
      Aspen.node(row['Origin']),
      Aspen.edge(row['Verb'].downcase),
      Aspen.node(row['Target']),
    ].join(" ")
  end
end