/// <summary>
/// Groups the data by the values in the given column, and computes aggregate quantities for each group.
/// </summary>
/// <param name="groupByColumnName">The name of the column to group by.</param>
/// <param name="aggregator">A function that computes the aggregate quantities.</param>
/// <returns>A new data frame containing the aggregates for each group.</returns>
/// <remarks>
/// <para>The first column of the returned <see cref="FrameTable"/> has the same name as the
/// original <paramref name="groupByColumnName"/> and contains all the distinct
/// values of that column in the original view. There is an additional column for each
/// dictionary entry returned by <paramref name="aggregator"/>, whose name is the returned
/// key and whose values are values returned for each group.</para>
/// <para>The function that computes the aggregate receives a <see cref="FrameView"/> containing
/// all the rows in the group. To produce aggregate results, it can use values in any of
/// the columns. Each invocation of the <paramref name="aggregator"/> must return the same keys
/// and values for the same keys must be of the same type. (Values for different keys may be
/// of different types.) Aggregate column names are taken from the keys and storage types are
/// inferred from the returned values.</para>
/// <para>To produce just one aggregate value, you may find it simpler and more efficient
/// to use the <see cref="GroupBy(string, Func{FrameView, IReadOnlyDictionary{string, object}})"/>
/// overload.</para>
/// </remarks>
public FrameTable GroupBy(string groupByColumnName, Func <FrameView, IReadOnlyDictionary <string, object> > aggregator)
{
// Collect rows into groups.
int groupByColumnIndex = GetColumnIndex(groupByColumnName);
NamedList groupByColumn = columns[groupByColumnIndex];
NullableDictionary <object, List <int> > groups = FindGroups(groupByColumn);
// Create a column to hold the group values.
NamedList groupsColumn = NamedList.Create(groupByColumnName, groupByColumn.StorageType);
// Create an enumerator that feeds the groups into the aggregator and presents them as dictionaries.
IEnumerable <IReadOnlyDictionary <string, object> > aggregatesEnumerator = GetGroupEnumerator(groups, aggregator, groupsColumn);
// Column-ify and validate the presented dictionaries.
List <NamedList> aggregateColumns = DictionaryHelper.ReadDictionaries(aggregatesEnumerator);
// Collect the results into a frame table.
FrameTable result = new FrameTable();
// First column is the group values.
result.AddColumn(groupsColumn);
// Remaining columns are aggregate columns.
foreach (NamedList aggregateColumn in aggregateColumns)
{
result.AddColumn(aggregateColumn);
}
return(result);
}
/// <summary>
/// Constructs a new frame table from a sequence of dictionaries.
/// </summary>
/// <param name="dictionaries">A enumerable set of dictionaries, one for each row, whose
/// keys are the column names and whose values are the cell value of the column for that row.</param>
/// <returns>A new frame table with data from the dictionaries.</returns>
/// <remarks><para>The storage type of each column is inferred from the types of objects
/// encountered are the frame table is constructed.</para></remarks>
public static FrameTable FromDictionaries(IEnumerable <IReadOnlyDictionary <string, object> > dictionaries)
{
if (dictionaries == null)
{
throw new ArgumentNullException(nameof(dictionaries));
}
List <NamedList> columns = DictionaryHelper.ReadDictionaries(dictionaries);
// Collect the results into a frame table.
FrameTable result = new FrameTable(columns);
return(result);
}
/// <summary>
/// Creates a new frame table from a file of comma-separated values.
/// </summary>
/// <param name="reader">A reader positioned at the beginning of the file.</param>
/// <returns>A new data frame with data from the file.</returns>
/// <remarks>
/// <para>The column names are taken from the first line of the file.</para>
/// <para>The storage type of each column is inferred from the types of objects
/// encountered are the frame table is constructed.</para>
/// </remarks>
public static FrameTable FromCsv(TextReader reader)
{
if (reader == null)
{
throw new ArgumentNullException(nameof(reader));
}
NamedList <string>[] textColumns;
DataAdaptor[] headers;
ReadCsvAsStrings(reader, out textColumns, out headers);
NamedList[] columns = new NamedList[headers.Length];
for (int columnIndex = 0; columnIndex < columns.Length; columnIndex++)
{
DataAdaptor header = headers[columnIndex];
if (header.TypeCandidates.Count == 0)
{
columns[columnIndex] = textColumns[columnIndex];
}
else
{
TypeParser adaptor = header.TypeCandidates.First.Value;
NamedList column = adaptor.CreateStorage(textColumns[columnIndex].Name, header.IsNullable);
foreach (string textValue in textColumns[columnIndex])
{
if (textValue == null)
{
column.AddItem(null);
}
else
{
object value = adaptor.Parse(textValue);
column.AddItem(value);
}
}
columns[columnIndex] = column;
}
}
FrameTable frame = new FrameTable(columns);
return(frame);
}
/// <summary>
/// Groups the data by the values in the given column, and computes the given aggregate quantity for each group.
/// </summary>
/// <typeparam name="T">The type of the aggregate output.</typeparam>
/// <param name="groupByColumnName">The name of the column to group by.</param>
/// <param name="aggregateColumnName">The name of the column for the aggregate output.</param>
/// <param name="aggregator">A function that computes the aggregate quantity.</param>
/// <returns>A new data frame containing the requested aggregate values for each group.</returns>
/// <remarks>
/// <para>The function that computes the aggregate receives a <see cref="FrameView"/> containing
/// all the rows in the group. To produce an aggregate result, it can use values in any of
/// the columns.</para>
/// <para>To produce more than one aggregate value, use <see cref="GroupBy(string, Func{FrameView, IReadOnlyDictionary{string, object}})"/>.</para>
/// </remarks>
public FrameTable GroupBy <T>(string groupByColumnName, Func <FrameView, T> aggregator, string aggregateColumnName)
{
if (groupByColumnName == null)
{
throw new ArgumentNullException(nameof(groupByColumnName));
}
if (aggregator == null)
{
throw new ArgumentNullException(nameof(aggregator));
}
if (aggregateColumnName == null)
{
throw new ArgumentNullException(nameof(aggregateColumnName));
}
// Collect the rows into groups.
int groupByColumnIndex = GetColumnIndex(groupByColumnName);
NamedList groupByColumn = columns[groupByColumnIndex];
NullableDictionary <object, List <int> > groups = FindGroups(groupByColumn);
// Form destination columns based on group aggregates.
NamedList groupsColumn = NamedList.Create(groupByColumnName, groupByColumn.StorageType);
NamedList <T> aggregateColumn = new NamedList <T>(aggregateColumnName);
foreach (KeyValuePair <object, List <int> > group in groups)
{
FrameView values = new FrameView(this.columns, group.Value);
T aggregateValue = aggregator(values);
aggregateColumn.AddItem(aggregateValue);
object groupKey = group.Key;
groupsColumn.AddItem(groupKey);
}
FrameTable result = new FrameTable(groupsColumn, aggregateColumn);
return(result);
}
