Filament Tutorial

Welcome to Filament, a humanist programming language. Computers are amazing. They can calculate incredible things super fast. They can answer questions and draw graphics. However, computers are actually very dumb. All they do is simple arithmetic. What makes them amazing is that they can do it super duper fast . To do smart things humans have to teach them. This is called programming. Anyone can program, including you!

Arithmetic

Filament understands arithmetic. Try typing in a math question like 2+2 then press the 'run' button (or type control-return on your keyboard). Filament will show you the answer: 4 . Now try dividing 4 by 2 or multiplying 3 by 5. Type in 4/2 . Run it. Then type 3 * 5 . Filament uses / to mean division and * for multiplication.

Filament understands longer math equations too. For example, imagine you have a refrigerator box that is 7 feet tall by 4 feet wide by 4 feet deep. You could find out the volume of the box by multiplying all of the sides.

7 * 4 * 4
112

Units

In the above problem only we know that the 7 meant 7 feet . The computer doesn't know because we didn't tell it. Fortunately Filament lets us tell the computer exactly what units we mean. Let's try that again with units:

7feet * 4feet * 4feet
112 foot

Now we get 112 cuft . Cool. Filament knows to convert the answer into cubic feet. But what if we didn't want cubic feet. We are talking about volume and there are several different units that could represent volume. Let's ask Filament to convert it into gallons instead.

7ft * 4ft * 4ft as gal
837.8153963540069 gallon

which gives us the answer 837.81 gallons .

Notice that this time we abbreviated feet to ft and gal for gallons . Filament understands the full names and abbrevations for over a hundred kinds of units, and it can convert between any of them. Here's a few more examples to try.

Convert your height into centimeters. I'm 5 foot four inches so

5feet + 4inches as cm
162.55999479808014 centimeter

Some kitchen math:

2cups + 4tablespoons
36 tablespoon

Calculate your age in seconds.

today ( ) - date ( month : 1, day : 15, year : 2003 ) as seconds
568857600 second

If you try to convert something that can't be converted, like area to volume, then Filament will let you know. Try this:

7ft * 4ft as gal
209.45384908850173 gallon

results in Error. Cannot convert ft^2 to gallons.

Units are very important. They help make sure our calculations are correct. Even professionals get this wrong some times. NASA once lost a space probe worth over 100 million dollars because the software didn't convert correctly between imperial and metric units.

Superman

Now lets try a more complex problem. In one of the Superman movies he flies so fast that the world turns backwards and reverses time. That got me thinking. Is that realistic? The earth is pretty big. How long would it really take him to fly around the world?

We need some information first. How fast can Superman fly? Apparently the comics are pretty vague about his speed. Some say it's faster than light, some say it's infinite, some say it's just slighly slower than The Flash. Since this is about the real world let's go with an older claim, that Superman is faster than a speeding bullet . According to the internet, the fastest bullet ever made was was the .220 Swift which can regularly exceed 4,000 feet per second. The fastest recorded shot was at 4,665 ft/s , so we'll go with that.

Now wee need to know how big the earth is. The earth isn't perfectly spherical and of course it would depend on exactly which part of the earth superman flew, but according to Wikipedia the average (mean) radius of the Earth is 6,371.0 kilometers. We also know the circumference of a circle is 2 * pi * radius . So the equation is

(6371.0km * pi * 2) / 4000ft/s as hours

Pretty fast. He could almost go three times around the earth in a single 24 hour day. But not as fast as the movie said.

Programming is both fun and useful. We can instruct computers to help us answer all sorts of interesting questions. In the next section we'll learn about groups of numbers called lists, and how to do interesting math with them.

Lists

Now let's take a look at lists. Imagine you want to add up some numbers. You could do it by adding each number separately like this:

4 + 5 + 6 + 7 + 8
30

or you could make them a list and use the sum function.

sum ( [4, 5, 6, 7, 8] )
30

Sum is a built in function that will add all of the items in a list. There are a lot of other cool functions that work on lists. You can sort a list

sort ( [8, 4, 7, 1] )
1, 4, 7, 8

get the length

length ( [8, 4, 7, 1] )
4

or combine sum and length to find the average

nums << [8, 4, 7, 1] sum ( nums ) / length ( nums )
5

Making Lists

Sometimes you need to generate a list. Suppose you wanted to know the sum of every number from 0 to 100. Of course you could write out the numbers directly, but Filament has a way to generate lists for you. It's called range .

range ( 10 ) sum ( range ( 100 ) )
4950

Range is flexible. You can give it both a start and end number, or even jump by steps.

range ( min : 20, max : 30 )
20, 21, 22, 23, 24, 25, 26, 27, 28, 29
range ( 100, step : 10 )
0, 10, 20, 30, 40, 50, 60, 70, 80, 90

Remember that range will start at the minmum and go to one less than the max. So 0 to 10 will go up to 9.

Filament can handle big lists. If you ask for range(0,10_000_000) it will show the the first few and then ... before the last few.

range ( 10000 )
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24 ... 9975, 9976, 9977, 9978, 9979, 9980, 9981, 9982, 9983, 9984, 9985, 9986, 9987, 9988, 9989, 9990, 9991, 9992, 9993, 9994, 9995, 9996, 9997, 9998, 9999]

Lists are very useful for lots of things, but sometimes you get more numbers than you need. Suppose you wanted all the numbers from from 0 to 20 minus the first three. Use take(list,3). Want just the last three use take(list,-3)

list << range ( 10 ) take ( list, 3 )
0, 1, 2
list << range ( 10 ) take ( list, -3 )
7, 8, 9

You can also remove items from a list with drop

drop ( range ( 10 ), 8 )
8, 9

And finally you can join two lists together

join ( [4, 2], [8, 6] )
4, 2, 8, 6

In addition to holding data, lists let you do things that you could do on a single number, but in bulk. You can add a single number to a list

1 + [1, 2, 3]
2, 3, 4

or add two lists together

[1, 2, 3] + [4, 5, 6]
5, 7, 9

Math with Lists

It might seem strange to do math on lists but it's actually quite useful. Image you had a list of prices and you would like to offer a 20% discount. You can do that with a single multiplication.

prices << [4.86, 5.23, 10.99, 8.43] sale_prices << 0.8 * prices
3.8880000000000003, 4.184, 8.792, 6.744

Suppose you sold lemonade on four weekends in april, and another four in july. It would be nice to compare the sales for the different weekends to see if july did better thanks to warmer weather. You can do this by just subtracting two lists.

april << [34, 44, 56, 42] july << [67, 45, 77, 98] july - april
33, 1, 21, 56

Doing math with lists is also great for working with vectors. You can add them, multiply as the dot product, and calculate the magnitude.

V1 << [0, 0, 5] V2 << [1, 0, 1] V1 + V2 V1 * V2 sqrt ( sum ( power ( V1, 2 ) ) )
5

Lists let you search for data too. You can find items using select and a small function. Let's find all of the prime numbers up to 10000

select ( range ( 100 ), where : is_prime )
2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97

or all numbers evenly divisible by 5

def div5 ( x : ? ) { x mod5 =0 } select ( range ( 100 ), where : div5 )
0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95

Charts

One of the coolest things about lists is that you can draw them. Just send a list into the chart function to see it as a bar chart. Suppose you had a list of heights of your friends.

chart ( [88, 64, 75, 59] )

or just want to draw the numbers from 0 to 9.

chart ( range ( 10 ) )

Plotting equations

While you could use range , map , and chart to draw pictures of x , power(x,2) , sin() or other math equations, there is a much better way: using the plot function.

A quadratic equation

def quad ( x : ? ) { x ** 2 - 3 * x - 4 } plot ( y : quad )

Sine wave

def fun ( theta : ? ) { sin ( theta * 2 ) } plot ( y : fun )

A polar Archimedes spiral

def fun ( theta : ? ) { 0.25 * theta } plot ( polar : fun, min : 0, max : pi * 32 )

And one of the best parts about lists is that they can hold more than numbers. You can work with lists of strings, numbers, booleans. Consider this simple list of people.

friends << ["Bart", "homer", "Ned"]
"Bart", "homer", "Ned"

or a list of booleans

[true, false, true]
true, false, true

Charts from lists and datasets

Even better than pulling in your own data, is working with curated datasets that have already been assembled. Filament comes with datasets for

  • Periodic table of elements
  • Letters of the English Alphabet
  • Planets of the solar system
  • Countries of the world
  • When you load a dataset it will be shown as a table.

    elements << dataset ( "elements" )
    namenumberweightsymboldiscovered_bydiscovery_dateprovenance
    Hydrogen11.008HHenry CavendishJanuary 1, 1766https://en.wikipedia.org/wiki/Hydrogen
    Helium24.0026022HePierre JanssenAugust 18, 1868https://en.wikipedia.org/wiki/Helium
    Lithium36.94LiJohan August ArfwedsonJanuary 1, 1800https://en.wikipedia.org/wiki/Lithium
    Beryllium49.01218315BeLouis Nicolas VauquelinJanuary 1, 1798https://en.wikipedia.org/wiki/Beryllium
    Boron510.81BJoseph Louis Gay-LussacJanuary 1, 1808https://en.wikipedia.org/wiki/Boron
    Carbon612.011CAncient EgyptJanuary 1, 2500https://en.wikipedia.org/wiki/Carbon
    Nitrogen714.007NDaniel RutherfordJanuary 1, 1772https://en.wikipedia.org/wiki/Nitrogen
    Oxygen815.999OCarl Wilhelm ScheeleJanuary 1, 1771https://en.wikipedia.org/wiki/Oxygen
    Fluorine918.9984031636FAndré-Marie AmpèreAugust 26, 1812https://en.wikipedia.org/wiki/Fluorine
    Neon1020.17976NeMorris Travershttps://en.wikipedia.org/wiki/Neon
    Sodium1122.989769282NaHumphry Davyhttps://en.wikipedia.org/wiki/Sodium
    Magnesium1224.305MgJoseph Blackhttps://en.wikipedia.org/wiki/Magnesium
    Aluminium1326.98153857Alnullhttps://en.wikipedia.org/wiki/Aluminium
    Silicon1428.085SiJöns Jacob Berzeliushttps://en.wikipedia.org/wiki/Silicon
    Phosphorus1530.9737619985PHennig Brandhttps://en.wikipedia.org/wiki/Phosphorus
    Sulfur1632.06SAncient chinahttps://en.wikipedia.org/wiki/Sulfur
    Chlorine1735.45ClCarl Wilhelm Scheelehttps://en.wikipedia.org/wiki/Chlorine
    Argon1839.9481ArLord Rayleighhttps://en.wikipedia.org/wiki/Argon
    Potassium1939.09831KHumphry Davyhttps://en.wikipedia.org/wiki/Potassium
    Calcium2040.0784CaHumphry Davyhttps://en.wikipedia.org/wiki/Calcium
    Scandium2144.9559085ScLars Fredrik Nilsonhttps://en.wikipedia.org/wiki/Scandium
    Titanium2247.8671TiWilliam Gregorhttps://en.wikipedia.org/wiki/Titanium
    Vanadium2350.94151VAndrés Manuel del Ríohttps://en.wikipedia.org/wiki/Vanadium
    Chromium2451.99616CrLouis Nicolas Vauquelinhttps://en.wikipedia.org/wiki/Chromium
    Manganese2554.9380443MnTorbern Olof Bergmanhttps://en.wikipedia.org/wiki/Manganese
    Iron2655.8452Fe5000 BChttps://en.wikipedia.org/wiki/Iron
    Cobalt2758.9331944CoGeorg Brandthttps://en.wikipedia.org/wiki/Cobalt
    Nickel2858.69344NiAxel Fredrik Cronstedthttps://en.wikipedia.org/wiki/Nickel
    Copper2963.5463CuMiddle Easthttps://en.wikipedia.org/wiki/Copper
    Zinc3065.382ZnIndiahttps://en.wikipedia.org/wiki/Zinc
    Gallium3169.7231GaLecoq de Boisbaudranhttps://en.wikipedia.org/wiki/Gallium
    Germanium3272.6308GeClemens Winklerhttps://en.wikipedia.org/wiki/Germanium
    Arsenic3374.9215956AsBronze Agehttps://en.wikipedia.org/wiki/Arsenic
    Selenium3478.9718SeJöns Jakob Berzeliushttps://en.wikipedia.org/wiki/Selenium
    Bromine3579.904BrAntoine Jérôme Balardhttps://en.wikipedia.org/wiki/Bromine
    Krypton3683.7982KrWilliam Ramsayhttps://en.wikipedia.org/wiki/Krypton
    Rubidium3785.46783RbRobert Bunsenhttps://en.wikipedia.org/wiki/Rubidium
    Strontium3887.621SrWilliam Cruickshank (chemist)https://en.wikipedia.org/wiki/Strontium
    Yttrium3988.905842YJohan Gadolinhttps://en.wikipedia.org/wiki/Yttrium
    Zirconium4091.2242ZrMartin Heinrich Klaprothhttps://en.wikipedia.org/wiki/Zirconium
    Niobium4192.906372NbCharles Hatchetthttps://en.wikipedia.org/wiki/Niobium
    Molybdenum4295.951MoCarl Wilhelm Scheelehttps://en.wikipedia.org/wiki/Molybdenum
    Technetium4398TcEmilio Segrèhttps://en.wikipedia.org/wiki/Technetium
    Ruthenium44101.072RuKarl Ernst Claushttps://en.wikipedia.org/wiki/Ruthenium
    Rhodium45102.905502RhWilliam Hyde Wollastonhttps://en.wikipedia.org/wiki/Rhodium
    Palladium46106.421PdWilliam Hyde Wollastonhttps://en.wikipedia.org/wiki/Palladium
    Silver47107.86822Agunknown, before 5000 BChttps://en.wikipedia.org/wiki/Silver
    Cadmium48112.4144CdKarl Samuel Leberecht Hermannhttps://en.wikipedia.org/wiki/Cadmium
    Indium49114.8181InFerdinand Reichhttps://en.wikipedia.org/wiki/Indium
    Tin50118.7107Snunknown, before 3500 BChttps://en.wikipedia.org/wiki/Tin
    Antimony51121.7601Sbunknown, before 3000 BChttps://en.wikipedia.org/wiki/Antimony
    Tellurium52127.603TeFranz-Joseph Müller von Reichensteinhttps://en.wikipedia.org/wiki/Tellurium
    Iodine53126.904473IBernard Courtoishttps://en.wikipedia.org/wiki/Iodine
    Xenon54131.2936XeWilliam Ramsayhttps://en.wikipedia.org/wiki/Xenon
    Cesium55132.905451966CsRobert Bunsenhttps://en.wikipedia.org/wiki/Cesium
    Barium56137.3277BaCarl Wilhelm Scheelehttps://en.wikipedia.org/wiki/Barium
    Lanthanum57138.905477LaCarl Gustaf Mosanderhttps://en.wikipedia.org/wiki/Lanthanum
    Cerium58140.1161CeMartin Heinrich Klaprothhttps://en.wikipedia.org/wiki/Cerium
    Praseodymium59140.907662PrCarl Auer von Welsbachhttps://en.wikipedia.org/wiki/Praseodymium
    Neodymium60144.2423NdCarl Auer von Welsbachhttps://en.wikipedia.org/wiki/Neodymium
    Promethium61145PmChien Shiung Wuhttps://en.wikipedia.org/wiki/Promethium
    Samarium62150.362SmLecoq de Boisbaudranhttps://en.wikipedia.org/wiki/Samarium
    Europium63151.9641EuEugène-Anatole Demarçayhttps://en.wikipedia.org/wiki/Europium
    Gadolinium64157.253GdJean Charles Galissard de Marignachttps://en.wikipedia.org/wiki/Gadolinium
    Terbium65158.925352TbCarl Gustaf Mosanderhttps://en.wikipedia.org/wiki/Terbium
    Dysprosium66162.5001DyLecoq de Boisbaudranhttps://en.wikipedia.org/wiki/Dysprosium
    Holmium67164.930332HoMarc Delafontainehttps://en.wikipedia.org/wiki/Holmium
    Erbium68167.2593ErCarl Gustaf Mosanderhttps://en.wikipedia.org/wiki/Erbium
    Thulium69168.934222TmPer Teodor Clevehttps://en.wikipedia.org/wiki/Thulium
    Ytterbium70173.0451YbJean Charles Galissard de Marignachttps://en.wikipedia.org/wiki/Ytterbium
    Lutetium71174.96681LuGeorges Urbainhttps://en.wikipedia.org/wiki/Lutetium
    Hafnium72178.492HfDirk Costerhttps://en.wikipedia.org/wiki/Hafnium
    Tantalum73180.947882TaAnders Gustaf Ekeberghttps://en.wikipedia.org/wiki/Tantalum
    Tungsten74183.841WCarl Wilhelm Scheelehttps://en.wikipedia.org/wiki/Tungsten
    Rhenium75186.2071ReMasataka Ogawahttps://en.wikipedia.org/wiki/Rhenium
    Osmium76190.233OsSmithson Tennanthttps://en.wikipedia.org/wiki/Osmium
    Iridium77192.2173IrSmithson Tennanthttps://en.wikipedia.org/wiki/Iridium
    Platinum78195.0849PtAntonio de Ulloahttps://en.wikipedia.org/wiki/Platinum
    Gold79196.9665695AuMiddle Easthttps://en.wikipedia.org/wiki/Gold
    Mercury80200.5923Hgunknown, before 2000 BCEhttps://en.wikipedia.org/wiki/Mercury (Element)
    Thallium81204.38TlWilliam Crookeshttps://en.wikipedia.org/wiki/Thallium
    Lead82207.21PbMiddle Easthttps://en.wikipedia.org/wiki/Lead_(element)
    Bismuth83208.980401BiClaude François Geoffroyhttps://en.wikipedia.org/wiki/Bismuth
    Polonium84209PoPierre Curiehttps://en.wikipedia.org/wiki/Polonium
    Astatine85210AtDale R. Corsonhttps://en.wikipedia.org/wiki/Astatine
    Radon86222RnFriedrich Ernst Dornhttps://en.wikipedia.org/wiki/Radon
    Francium87223FrMarguerite Pereyhttps://en.wikipedia.org/wiki/Francium
    Radium88226RaPierre Curiehttps://en.wikipedia.org/wiki/Radium
    Actinium89227AcFriedrich Oskar Gieselhttps://en.wikipedia.org/wiki/Actinium
    Thorium90232.03774ThJöns Jakob Berzeliushttps://en.wikipedia.org/wiki/Thorium
    Protactinium91231.035882PaWilliam Crookeshttps://en.wikipedia.org/wiki/Protactinium
    Uranium92238.028913UMartin Heinrich Klaprothhttps://en.wikipedia.org/wiki/Uranium
    Neptunium93237NpEdwin McMillanhttps://en.wikipedia.org/wiki/Neptunium
    Plutonium94244PuGlenn T. Seaborghttps://en.wikipedia.org/wiki/Plutonium
    Americium95243AmGlenn T. Seaborghttps://en.wikipedia.org/wiki/Americium
    Curium96247CmGlenn T. Seaborghttps://en.wikipedia.org/wiki/Curium
    Berkelium97247BkLawrence Berkeley National Laboratoryhttps://en.wikipedia.org/wiki/Berkelium
    Californium98251CfLawrence Berkeley National Laboratoryhttps://en.wikipedia.org/wiki/Californium
    Einsteinium99252EsLawrence Berkeley National Laboratoryhttps://en.wikipedia.org/wiki/Einsteinium
    Fermium100257FmLawrence Berkeley National Laboratoryhttps://en.wikipedia.org/wiki/Fermium
    Mendelevium101258MdLawrence Berkeley National Laboratoryhttps://en.wikipedia.org/wiki/Mendelevium
    Nobelium102259NoJoint Institute for Nuclear Researchhttps://en.wikipedia.org/wiki/Nobelium
    Lawrencium103266LrLawrence Berkeley National Laboratoryhttps://en.wikipedia.org/wiki/Lawrencium
    Rutherfordium104267RfJoint Institute for Nuclear Researchhttps://en.wikipedia.org/wiki/Rutherfordium
    Dubnium105268DbJoint Institute for Nuclear Researchhttps://en.wikipedia.org/wiki/Dubnium
    Seaborgium106269SgLawrence Berkeley National Laboratoryhttps://en.wikipedia.org/wiki/Seaborgium
    Bohrium107270BhGesellschaft für Schwerionenforschunghttps://en.wikipedia.org/wiki/Bohrium
    Hassium108269HsGesellschaft für Schwerionenforschunghttps://en.wikipedia.org/wiki/Hassium
    Meitnerium109278MtGesellschaft für Schwerionenforschunghttps://en.wikipedia.org/wiki/Meitnerium
    Darmstadtium110281DsGesellschaft für Schwerionenforschunghttps://en.wikipedia.org/wiki/Darmstadtium
    Roentgenium111282RgGesellschaft für Schwerionenforschunghttps://en.wikipedia.org/wiki/Roentgenium
    Copernicium112285CnGesellschaft für Schwerionenforschunghttps://en.wikipedia.org/wiki/Copernicium
    Nihonium113286NhRIKENhttps://en.wikipedia.org/wiki/Ununtrium
    Flerovium114289FlJoint Institute for Nuclear Researchhttps://en.wikipedia.org/wiki/Flerovium
    Moscovium115289McJoint Institute for Nuclear Researchhttps://en.wikipedia.org/wiki/Ununpentium
    Livermorium116293LvJoint Institute for Nuclear Researchhttps://en.wikipedia.org/wiki/Livermorium
    Tennessine117294TsJoint Institute for Nuclear Researchhttps://en.wikipedia.org/wiki/Tennessine
    Oganesson118294OgJoint Institute for Nuclear Researchhttps://en.wikipedia.org/wiki/Oganesson
    Ununennium119315UueGSI Helmholtz Centre for Heavy Ion Researchhttps://en.wikipedia.org/wiki/Ununennium

    Each column in the table is a field of each record in the datasets.

    Let's suppose you want to compare the sizes of the planets. First load the planets dataset.

    planets << dataset ( "planets" )
    namemean_radiusorbital_radiusorbital_period
    Mercury24400.38710.2408
    Venus60520.72330.6152
    Earth637111
    Mars33901.52731.8809
    Jupiter699115.202811.862
    Saturn582329.538829.458
    Uranus2536219.191484.01
    Neptune2462230.0611164.79

    Now add a chart to draw the planets.

    planets << dataset ( "planets" ) chart ( planets )

    Hmm. That doesn't look right. Chart doesn't know what part of the planets dataset we want to draw. We have to tell it. Let's use mean_radius for the height of the bar chart. For the label under each bar we can use the name property. We can tell the chart function what to do using the named arguments x_label and y .

    Now let's compare the radius of the orbit to the radius of the planet. This will show us if the smaller planets are clustered together or spread out.

    planets << dataset ( "planets" ) chart ( planets, type : "scatter", x : "orbital_radius", y : "mean_radius" )

    Here's a fun one. Let's see which letters have one syllable vs two.

    //TODO: this is broken when doing builddocs chart(dataset('letters'), y_value:'syllables')

    Let's check out the relative heights of the tallest buildings in the world:

    buildings << dataset ( "tallest_buildings" ) b2 << take ( buildings, 5 ) chart ( b2, y : "height", x_label : "name" )