Skip to content

NetLogo/CSV-Extension

Repository files navigation

NetLogo CSV extension

This NetLogo extension adds CSV parsing capabilities to models.

Building

Run sbt package.

If compilation succeeds, csv.jar will be created. This file and commons-csv-1.0.jar should then be placed in a folder named csv in your NetLogo extensions directory.

Common use cases and examples

Read a file all at once

Just use csv:from-file "/path/to/myfile.csv"! See from-file for more information.

Read a file one line at a time

For really big files, you may not want to store the entire file in memory, but rather just process it a line at a time. For instance, if you want to sum each of the columns of a numeric CSV file, you can do:

to-report sum-columns [ file ]
  file-open file
  set result csv:from-row file-read-line
  while [ not file-at-end? ] [
    let row csv:from-row file-read-line
    set result (map [ [ [col-total new-val] -> col-total + new-val] result row)
  ]
  file-close
  report result
end

You can also use this technique to...

Read a file one line per tick

Here's an example model that reads in a file one line per tick:

globals [ data ]

to setup
  clear-all
  file-close-all % Close any files open from last run
  file-open "data.csv"
  % other setup goes here
  reset-ticks
end

to go
  if file-at-end? [ stop ]
  set data csv:from-row file-read-line
  % model update goes here
  tick
end

Write a file

Just use csv:to-file "/path/to/myfile.csv" my-data! See to-file for more information.

Primitives

Formatting NetLogo data as CSV

csv:to-row csv:to-string csv:to-file

Parsing CSV input to NetLogo data

csv:from-row csv:from-string csv:from-file

csv:from-row

csv:from-row *string*
(csv:from-row *string* *delimiter*)

Parses the given string as though it were a row from a CSV file and returns it as a list of values. For example:

observer> show csv:from-row "one,two,three"
observer: ["one" "two" "three"]

Quotes can be used when items contain commas:

observer> show csv:from-row "there's,a,comma,\"in,here\""
observer: ["there's" "a" "comma" "in,here"]

You can put two quotes in a row to put an actual quote in an entry. If the entry is not quoted, you can just use one quote:

observer> foreach (csv:from-row "he said \"hi there\",\"afterwards, she said \"\"hello\"\"\"") print
he said "hi there"
afterwards, she said "hello"

Number-like-entries will be parsed as numbers:

observer> show csv:from-row "1,-2.5,1e3"
observer: [1 -2.5 1000]

true and false with any capitalization will be parsed as booleans:

observer> show csv:from-row "true,TRUE,False,falsE"
observer: [true true false false]

To use a different delimiter, you can specify a second, optional argument. Only single character delimiters are supported:

observer> show (csv:from-row "1;2;3" ";")
observer: [1 2 3]

Different types of values can be mixed freely:

observer> show csv:from-row "one,2,true"
observer: ["one" 2 true]

csv:from-string

csv:from-string *string*
(csv:from-string *string* *delimiter*)

Parses a string representation of one or more CSV rows and returns it as a list of lists of values. For example:

observer> show csv:from-string "1,two,3\nfour,5,true"
observer: [[1 "two" 3] ["four" 5 true]]

csv:from-file

csv:from-file *csv-file*
(csv:from-file *csv-file* *delimiter*)

Parses an entire CSV file to a list of lists of values. For example, if we have a file example.csv that contains:

1,2,3
4,5,6
7,8,9
10,11,12

Then, we get:

observer> show csv:from-file "example.csv"
observer: [[1 2 3] [4 5 6] [7 8 9] [10 11 12]]

The parser doesn't care if the rows have different numbers of items on them. The number of items in the rows list will always be <number of delimiters> + 1, though blank lines are skipped. This makes handling files with headers quite easy. For instance, if we have header.csv that contains:

My Data
2/1/2015

Parameters:
start,stop,resolution,population,birth?
0,4,1,100,true

Data:
time,x,y
0,0,0
1,1,1
2,4,8
3,9,27

This gives:

observer> foreach csv:from-file "header.csv" show
observer: ["My Data"]
observer: ["2/1/2015"]
observer: ["Parameters:"]
observer: ["start" "stop" "resolution" "population" "birth?"]
observer: [0 4 1 100 true]
observer: ["Data:"]
observer: ["time" "x" "y"]
observer: [0 0 0]
observer: [1 1 1]
observer: [2 4 8]
observer: [3 9 27]

csv:to-row

csv:to-row *list*
(csv:to-row *list* *delimiter*)

Reports the given list as a CSV row. For example:

observer> show csv:to-row ["one" 2 true]
observer: "one,2,true"

csv:to-string

csv:to-string *list*
(csv:to-string *list* *delimiter*)

Reports the given list of lists as a CSV string. For example:

observer> show csv:to-string [[1 "two" 3] [4 5]]
observer: "1,two,3\n4,5"

csv:to-file

csv:to-file *csv-file* *list*
(csv:to-file *csv-file* *list* *delimiter*)

Writes the given list of lists to a new CSV file. For example:

observer> csv:to-file "myfile.csv" [[1 "two" 3] [4 5]]

will result in a file myfile.csv containing:

1,two,3
4,5