Daru::DataFrame is a two-dimensional size-mutable, potentially heterogeneous tabular data structure with labeled axes (rows and vectors).
Arithmetic operations align on both row and vector labels. Can be thought of as a container for Daru::Vector objects. This is primary data structure used by daru and gems that depend on it (like statsample).
You should use DataFrame because it allows you to easily store, access and manipulate labelled data, plot it using an interactive graph library and perform various statistics operations by ignoring missing data.
require 'daru'
Daru offers many options for creating DataFrames. You can create it from Hashes, Arrays, Daru::Vectors or even load it from CSV files, Excel spreadsheets or SQL databases.
From Array of Arrays
In the example below, I'm specifying the vertical Vectors of the DataFrame as an Array of Arrays and I specify their names in the :order option, by supplying an Array of names that the vectors should be called by.
In the :index option, we'll specify the names of the rows of the DataFrame. If the :index is not given, DataFrame will assign numerical indexes starting from 0 to each row.
df = Daru::DataFrame.new([[1,2,3,4], [1,2,3,4]],order: [:a, :b], index: [:one, :two, :three, :four])
From Hash of Arrays
A similar DataFrame can be created from a Hash. In this case the keys of the Hash are the names of the vectors in the DataFrame. The :order option, if specified, will only serve to decide the orientation of the Vectors in the DataFrame. Not specfiying :order in this case will align the vectors alphabetically.
df = Daru::DataFrame.new({a: [1,2,3,4], b: [1,2,3,4]},order: [:b, :a])
From Hash of Vectors
A DataFrame can be created from a Hash of Daru::Vectors and their names. The name of the vector will be the key and the corresponding value, a Daru::Vector.
The values of the DataFrame are aligned according to the index of each Daru::Vector. A nil is assigned whenever a particular index is not available for one Vector but is present in any of the other Vectors, and the resulting index of the DataFrame is a union of the indexes of all the Vectors in alphabetical order.
The sizes or indexes of the supplied Vectors don't matter.
v1 = Daru::Vector.new([1,2,3,4,5], index: [:a, :b, :c, :d, :e])
v2 = Daru::Vector.new([11,22,33,44], index: [:b, :e, :a, :absent])
Daru::DataFrame.new({v1: v1, v2: v2})
The 'clone' option
If you have Vectors that have exactly the same index, you can specify the :clone option to DataFrame. Setting :clone to false will direct daru to utilize the same Vector objects in creating the DataFrame, that you have specified in the Hash and will prevent their cloning when being stored in the DataFrame. Thus the object IDs of the Vectors will remain the same.
Be wary of making changes in the DataFrame or the supplied vectors if you set :clone to false.
v1 = Daru::Vector.new([1,2,3,4,5])
v2 = Daru::Vector.new([11,22,33,44,55])
df = Daru::DataFrame.new({a: v1, b: v2}, clone: false)
puts "equalness a : #{v1.object_id == df[:a].object_id}\nequalness b : #{v2.object_id == df[:b].object_id}"
Creating with rows
If you want to create a DataFrame by specifying the rows, you can do so by specifying an Array of Arrays or Array of Vectors to the .rows method.
Lets first see creating DataFrames from an Array of Arrays:
Daru::DataFrame.rows([
[1,11,10,'a'],
[2,22,20 ,4 ],
[3,33,30,'g'],
[4,44,40, 3 ]
], order: [:a, :b, :c, :d])
If you supply an Array of Vectors to the .rows method, the index of the Vectors will be automatically assigned as the names of the vectors of the DataFrame. Moreover, elements will be aligned by their indexes in the completed DataFrame.
If a Vector does not have a particular index that is present in other Vectors, a nil will be placed in that position.
The :order option should be set in this case to whatever values you want to keep in your DataFrame to avoid unexpected behaviour.
r1 = Daru::Vector.new([1,2,3,4,5], index: [:a, :b, :c, :d, :e])
r2 = Daru::Vector.new([11,22,33,44,55], index: [:a, :c, :e, :b, :odd])
Daru::DataFrame.rows([r1,r2], order: [:a, :b, :c, :d, :odd])
Daru::DataFrame currently supports loading data from CSV files, Excel spreadsheets and SQL databases. You can also write your DataFrames to these kinds of files using some simple functions. Daru also supports saving and loading data by Marshalling. Lets go through them one by one.
CSV (Comma Separated Values) files
To demonstrate loading and writing to CSV files, we'll read some sales data from this CSV file.
Daru::DataFrame.from_csv 'data/sales-funnel.csv'
You can specify all the options to the .from_csv function that you do to the Ruby CSV.read() function, since this is what is used internally.
For example, if the columns in your CSV file are separated by something other that commas, you can use the :col_sep option. If you want to convert numeric values to numbers and not keep them as strings, you can use the :converters option and set it to :numeric.
The .from_csv function uses the following defaults for reading CSV files (that are passed into the CSV.read() function):
{
:col_sep => ',',
:converters => :numeric
}
The #write_csv function is used for writing the contents of a DataFrame to a CSV file.
Excel Files
The ::from_excel method can be used for loading Excel files. The spreadsheet gem is used in the background in this case, so whatever variants of Excel compatible files can be loaded by spreadsheet should be easily loadable in this case too.
Let me demonstrate this using this Excel file.
df = Daru::DataFrame.from_excel 'data/test_xls.xls'
Likewise, the #write_excel method can be used for writing data stored in the DataFrame to an Excel file.
SQL Databases
Similar to the examples above you can use the ::from_sql and #write_sql methods for interacting with SQL databases.
Plaintext Files
In case your data is stored as columns in plaintext (for example this file), you can use the ::from_plaintext method for loading data from the file.
Daru::DataFrame consists of rows and vectors, both of which can be accessed by their labels using an intuitive syntax.
Consider the following DataFrame:
df = Daru::DataFrame.new({
a: [1,2,3,4,5,6,7],
b: ['a','b','c','d','e','f','g'],
c: [11,22,33,44,55,66,77]
}, index: [:a,:b,:c,:d,:e,:f,:g])
You can access any Vector using the #[] operator. The resultant Vector is returned as a Daru::Vector which preserves the index of the DataFrame.
df[:b]
You can also specify a Range inside #[] to return a DataFrame which contains the columns within the Range.
df[:b..:c]
A row can be accessed using the #row[] method. The row is also returned as a Daru::Vector and any operations so any operations on a Daru::Vector will be valid on the row too.
The index of the returned row corresponds to the names of the Vectors.
df.row[:c]
Here too, you can specify a Range, and you will receive a Daru::DataFrame instead of a Daru::Vector containing the relevant rows specified by the Range.
df.row[:d..:f]
Rows can be accessed using numerical indices too (this works for columns too).
df.row[3]
You can get the top 3 rows by passing an argument to the #head method (or the bottom 3 using #tail).
df.head 3
A column can be added by simply specifying it's name and value using the #[]= operator.
df[:d] = df[:a] * df[:c]
df
You can delete a vector with the #delete_vector method.
df.delete_vector :b
If you try to insert a Daru::Vector that does not conform to the index of the DataFrame, the values will be appropriately placed such that they conform to the DataFrame's index.
nil is inserted wherever a similar index cannot be found on the DataFrame.
Inserting an Array will require the Array to be of the same length as that of the DataFrame.
df[:b] = Daru::Vector.new(['a',33,'b','c','d',88,'e'], index: [:a,:c,:d,:b,:e,:f,:extra])
df
Inserting a row also works similarly.
df.row[:latest] = Daru::Vector.new([10,20,30,40], index: [:c,:b,:a,:d])
df
In both row and vector insertion, if the index specified is not present in the DataFrame, a new index is created and appended or if it is present then the existing index will be over-ridden.
For filtering out certain rows/vectors based on their values, use the #filter method. By default it iterates over vectors and keeps those vectors for which the block returns true. It accepts an optional axis argument which lets you specify whether you want to iterate over vectors or rows.
# Filter vectors.
# The `type` method returns either :numeric or :object. The :numeric type states
# that the Vector consists only of numerical data (combined with missing data).
# If the type happens to be :object, it contains non-numerical data like strings
# or symbols. Statistical operations will not be possible on Vectors of type :object.
df.filter do |vector|
vector.type == :numeric and vector.median < 50
end
# Filter rows
df.filter(:row) do |row|
row[:a] + row[:d] < 100
end
A DataFrame can be transposed using the #transpose method.
df.transpose
All arithmetic operations can be performed on a Daru::DataFrame and you can a DataFrame with another DataFrame, a Vector or a scalar.
Indexes are aligned appropriately whenever an operation is performed with a non-scalar quantity.
With a Scalar
Adding a scalar quantity will add that number to all the numeric type vectors, keeping :object type Vectors the way they originally were.
df + 10
With another DataFrame
Performing arithmetic between two data frames will align the elements by row and column indexes of either dataframe.
If a column is present in one dataframe but not in the other, the resultant dataframe will be populated with a column full of nils of that name.
DataFrames need not be of the same size for this operation to succeed.
df1 = Daru::DataFrame.new({
a: 7.times.map { rand(100) },
f: 7.times.map { rand(100) },
c: 7.times.map { rand(100) }
}, index: [:a,:b,:c,:d,:latest,:older,:f])
df1 + df
Statistical methods perform basic statistics on numerical Vectors only.
For a whole list of methods see the Daru::Maths::Statistics::DataFrame module in the docs.
To demonstrate, the #mean method calculates the mean of each numeric vector and returns a Daru::Vector with the vector's name as the index alongwith the corresponding value.
df.mean
The #describe method can be used for knowing various statistics in one shot.
df.describe
#cov will return a covariance matrix of the DataFrame, and it will be properly indexed so you can see the data clearly.
df.cov
Likewise #corr computes the correlation matrix.
df.corr
You can use report builder to create a quick summary of the DataFrame using the #summary method.
puts df.summary
Daru::DataFrame offers many iterators to loop over either rows or columns.
#each
#each works exactly like Array#each. The default mode for each is to iterate over the columns of the DataFrame. To iterate over rows you must pass the axis, i.e :row as an argument.
# Iterate over vectors
e = []
df.each do |vector|
e << vector[:a].to_s + vector[:latest].to_s
end
puts e
# Iterate over rows
r = []
df.each(:row) do |row|
r << row[:a] * row[:c]
end
puts r
#map
The #map iterator works like Array#map. The value returned by each run of the block is added to an Array and the Array is returned.
This method also accepts an axis argument, like #each. The default is :vector.
# Map over vectors.
# The `only_numerics` method returns a DataFrame which contains vectors
# with only numerical values. Setting the `:clone` option to false will
# return the same Vector objects that are contained in the original DataFrame.
df.only_numerics(clone: false).map do |vector|
vector.mean
end
# Map over rows.
# Calling `only_numerics` on a Daru::Vector will return a Vector with only numeric and
# missing data. Data marked as 'missing' is not considered during statistical computation.
df.map(:row) do |row|
row.only_numerics.mean
end
#recode
Recode works similarly to #map, but an important difference between the two is that recode returns a modified Daru::DataFrame instead of an Array. For this reason, #recodeexpects that every run of the block to return a Daru::Vector.
Just like map and each, recode also accepts an optional axis argument.
# Recode vectors
df.only_numerics(clone: false).recode do |vector|
vector[:a] = vector[:d] + vector[:c]
vector[:b] = vector.mean + vector[:a]
vector # <- return the vector to the block
end
# Recode rows
df.recode(:row) do |row|
row[:a] = row[:c] - row[:d]
row[:b] = row[:b].to_i if row[:b].is_a?(String)
row
end
#collect
The #collect iterator works similar to #map, the only difference being that it returns a Daru::Vector comprising of the results of each block run. The resultant Vector has the same index as that of the axis over which collect has iterated.
It also accepts the optional axis argument.
# Collect Vectors
df.collect do |vector|
vector[:c] + vector[:f]
end
# Collect Rows
df.collect(:row) do |row|
row[:a] + row[:d] - row[:c]
end
#vector_by_calculation
#vector_by_calculation is a DSL that can be used for generating a Daru::Vector based on the results returned by the block.
This DSL lets you refer to elements directly as methods inside the block.
df.vector_by_calculation { a + c + d }
Daru::DataFrame offers a robust #sort function which can be used for hierarchically sorting the Vectors in the DataFrame.
Here are couple of examples to demonstrate a lot of the options:
df = Daru::DataFrame.new({
a: ['g', 'g','g','sort', 'this'],
b: [4,4,335,32,11],
c: ['This', 'dataframe','is','for','sorting']
})
The Array passed as an argument to 'sort' tells the method the order in which preference of sorting should be given to each Vector.
The :ascending option will tell DataFrame the order in which you want the Vectors to be sorted. true for ascending sort and false for descending sort.
The :by option lets you define a custom attribute for each vector to sort by. This works similarly to passing a block to Array#sort_by.
df.sort([:a,:b,:c], ascending: [true, false, true], by: {c: lambda { |a| a.size }})
Sort a dataframe with a vector sequence.
df = Daru::DataFrame.new({a: [1,2,1,2,3], b: [5,4,3,2,1]})
df.sort [:a, :b]
Sort a dataframe without a block. Here nils will be handled automatically and appear at top.
df = Daru::DataFrame.new({a: [-3,nil,-1,nil,5], b: [4,3,2,1,4]})
df.sort([:a])
Sort a dataframe with a block with nils handled automatically.
df = Daru::DataFrame.new({a: [nil,-1,1,nil,-1,1], b: ['aaa','aa',nil,'baaa','x',nil] })
# df.sort [:b], by: {b: lambda { |a| a.length } }
# This would give "NoMethodError: undefined method `length' for nil:NilClass"
# Instead you could do the following if you want the nils to be handled automatically
df.sort [:b], by: {b: lambda { |a| a.length } }, handle_nils: true
Sort a dataframe with a block with nils handled manually.
df = Daru::DataFrame.new({a: [nil,-1,1,nil,-1,1], b: ['aaa','aa',nil,'baaa','x',nil] })
# To print nils at the bottom one can use lambda { |a| (a.nil?)[1]:[0,a.length] }
df.sort [:b], by: {b: lambda { |a| (a.nil?)?[1]:[0,a.length] } }, handle_nils: true