Struct agnes::view::DataView

pub struct DataView<Labels, Frames> { /* fields omitted */ }

A DataView is a specific view of data stored inside a DataStore. It consists of a list of DataFrame objects, which themselves reference individual DataStores.

The type parameter Frames is a ViewFrameCons cons-list which contains the DataFrame objects referenced by this DataView. The type parameter Labels is a FrameLookupCons which provides lookup functionality from a specific Label into the Frames cons-list.

Methods

impl<Labels, Frames> DataView<Labels, Frames>

pub fn new(frames: Frames) -> DataView<Labels, Frames>

Creates a new DataView with frames.

impl<Labels, Frames> DataView<Labels, Frames>

pub fn fieldnames<'a>(&'a self) -> Vec<&'a str> where
    Labels: StrLabels, 

Field names in this data view

impl<Labels, Frames> DataView<Labels, Frames> where
    Frames: Clone, 

pub fn v<LabelList>(&self) -> Self::Output where
    Self: Subview<LabelList>, 

Generate a new subview of this DataView. LabelList is a LabelCons list of labels, which can be generated using the Labels macro.

pub fn subview<LabelList>(&self) -> Self::Output where
    Self: Subview<LabelList>, 

Generate a new subview of this DataView. Equivalent to v.

impl<Labels, Frames> DataView<Labels, Frames> where
    Self: NRows, 

pub fn nrows(&self) -> usize

Number of rows in this data view

impl<Labels, Frames> DataView<Labels, Frames> where
    Labels: Len,
    Frames: Len, 

pub fn is_empty(&self) -> bool

Returns true if the DataView is empty (has no rows or has no fields)

impl<Labels, Frames> DataView<Labels, Frames> where
    Labels: Len, 

pub fn nfields(&self) -> usize

Number of fields in this data view

impl<Labels, Frames> DataView<Labels, Frames> where
    Frames: Len, 

pub fn nframes(&self) -> usize

Number of frames this data view covers

impl<Labels, Frames> DataView<Labels, Frames>

pub fn relabel<CurrLabel, NewLabel>(
    self
) -> DataView<<Labels as Relabel<CurrLabel, NewLabel>>::Output, Frames> where
    Labels: Relabel<CurrLabel, NewLabel>, 

Construct a new DataView with the label CurrLabel relabeled with the label NewLabel.

impl<Labels, Frames> DataView<Labels, Frames>

pub fn merge<RLabels, RFrames>(
    &self,
    right: &DataView<RLabels, RFrames>
) -> Result<Self::Output> where
    Self: ViewMerge<DataView<RLabels, RFrames>>, 

Merge this DataView with another DataView object, creating a new DataView with the same number of rows and all the fields from both source DataView objects.

Fails if the two DataViews have different number of rows.

impl<Labels, Frames> DataView<Labels, Frames>

pub fn join<Join, RLabels, RFrames>(
    &self,
    right: &DataView<RLabels, RFrames>
) -> Self::Output where
    Self: SortMergeJoin<RLabels, RFrames, Join>, 

Combine two DataView objects using specified join, creating a new DataStore object with a subset of records from the two source DataViews according to the join parameters.

Note that since this is creating a new DataStore object, it will be allocated new data to store the contents of the joined DataViews.

impl<Labels, Frames> DataView<Labels, Frames> where
    Frames: UpdatePermutation, 

pub fn sort_by_label<Label>(&mut self) -> Vec<usize> where
    Self: SelectFieldByLabel<Label>,
    Self::Output: SortOrder, 

Sorts this DataView by the provided label. This sort is stable -- it preserves the original order of equal elements. Returns the permutation (list of indices in sorted order) of values in field identified by Label.

The resulting permutation denotes the order of values in ascending order, with missing (NA) values at the beginning of the order (considered to be of 'lesser' value than existing values).

pub fn sort_unstable_by_label<Label>(&mut self) -> Vec<usize> where
    Self: SelectFieldByLabel<Label>,
    Self::Output: SortOrderUnstable, 

Sorts this DataView by the provided label. This sort is unstable -- it does not necessarily preserve the original order of equal elements, but may be faster. Returns the permutation (list of indices in sorted order) of values in field identified by Label.

The resulting permutation denotes the order of values in ascending order, with missing (NA) values at the beginning of the order (considered to be of 'lesser' value than existing values).

pub fn sort_by_label_comparator<Label, F>(&mut self, compare: F) -> Vec<usize> where
    Self: SelectFieldByLabel<Label>,
    Self::Output: SortOrderComparator<F>, 

Sorts this DataView by the provided label using a specific comparator. This sort is stable -- it preserves the original order of equal elements. Returns the permutation (list of indices in sorted order) of values in field identified by Label.

The resulting permutation denotes the order of values in ascending order, with missing (NA) values at the beginning of the order (considered to be of 'lesser' value than existing values).

pub fn sort_unstable_by_label_comparator<Label, F>(
    &mut self,
    compare: F
) -> Vec<usize> where
    Self: SelectFieldByLabel<Label>,
    Self::Output: SortOrderUnstableComparator<F>, 

Sorts this DataView by the provided label using a specific comparator. This sort is unstable -- it does not necessarily preserve the original order of equal elements, but may be faster. Returns the permutation (list of indices in sorted order) of values in field identified by Label.

The resulting permutation denotes the order of values in ascending order, with missing (NA) values at the beginning of the order (considered to be of 'lesser' value than existing values).

pub fn filter<Label, P>(&mut self, predicate: P) -> Vec<usize> where
    Self: SelectFieldByLabel<Label>,
    Self::Output: FilterPerm<P>, 

Filters this DataView by predicate (a function mapping from Value<&T> to bool where T is the type of the field with label Label). Mutates this DataView so only those rows where values within the field with label Label matching prediate remain.

Returns the indices of the values that matched predicate in the oringal DataView (before filtering).

impl<Labels, Frames> DataView<Labels, Frames>

pub fn field_list<LabelList>(
    &self
) -> <Labels as FieldList<LabelList, Frames>>::Output where
    Labels: FieldList<LabelList, Frames>, 

Returns a cons-list of fields (implementing DataIndex) that match the labels in LabelList.

pub fn unique_indices<LabelList>(&self) -> Vec<usize> where
    Labels: FieldList<LabelList, Frames>,
    <Labels as FieldList<LabelList, Frames>>::Output: HashIndex + PartialEqIndex,
    Frames: NRows, 

Computes the set of unique composite values among the fields in this DataView associated with labels in LabelList. Returns the indices of exemplar rows, one index for each unique value. Taken as a set, the values of the LabelList-labeled fields at the indices returned by this method represent all the possible combinations of values of these fields that exist in this DataView.

Fields referenced by LabelList must implement Hash.

pub fn unique_values<LabelList>(
    &self
) -> DataView<<Labels as LabelSubset<LabelList>>::Output, <Frames as SubsetClone<<Labels as FrameIndexList>::LabelList>>::Output> where
    Labels: HasLabels<LabelList> + LabelSubset<LabelList> + FrameIndexList,
    Frames: SubsetClone<<Labels as FrameIndexList>::LabelList>,
    <Frames as SubsetClone<<Labels as FrameIndexList>::LabelList>>::Output: UpdatePermutation,
    Labels: FieldList<LabelList, Frames>,
    <Labels as FieldList<LabelList, Frames>>::Output: HashIndex + PartialEqIndex,
    Frames: NRows, 

Computes the set of unique composite values among the fields in this DataView associated with labels in LabelList. Returns a new DataView with those specific sets of values. The returned DataView contains the values of the LabelList-labeled fields that represent all the possible combinations of values of these fields that exist in the original DataView.

Fields referenced by LabelList must implement Hash.

impl<Labels, Frames> DataView<Labels, Frames>

pub fn melt<MeltLabels, NameLabel, ValueLabel, HoldLabels>(
    &self
) -> <<<<MeltLabels as IntoStrFrame<NameLabel>>::Output as IntoView>::Output as AddFrame<<Self::Output as IntoFrame>::Output>>::Output as AddFrame<<Self::Output as IntoMeltFrame<ValueLabel>>::Output>>::Output where
    Frames: NRows + Clone,
    NameLabel: Debug,
    Labels: SetDiff<MeltLabels, Set = HoldLabels>,
    MeltLabels: Len + IntoStrFrame<NameLabel>,
    <MeltLabels as IntoStrFrame<NameLabel>>::Output: IntoView,
    Self: Subview<HoldLabels>,
    Self::Output: IntoFrame,
    <Self::Output as IntoFrame>::Output: UpdatePermutation,
    <<MeltLabels as IntoStrFrame<NameLabel>>::Output as IntoView>::Output: AddFrame<<Self::Output as IntoFrame>::Output>,
    Self: Subview<MeltLabels>,
    Self::Output: IntoMeltFrame<ValueLabel>,
    <<<MeltLabels as IntoStrFrame<NameLabel>>::Output as IntoView>::Output as AddFrame<<Self::Output as IntoFrame>::Output>>::Output: AddFrame<<Self::Output as IntoMeltFrame<ValueLabel>>::Output>, 

Creates a new a DataView that accesses source data in a different way, viewing the data as a series of identifier / value pairs instead of a having values in multiple related fields.

This is useful when converting a data table in a wide format where several fields represent different instances of some quantity to a long format where each record only has one instance of the appropriate value.

The type parameter MeltLabels is a LabelCons list of the labels of the fields containing the values to 'melt'. NameLabel is the desired label for the new identifier field, which will contain the String identifiers for where a record's value originally came from. ValueLabel is the desired label for the new value field, which will contain the values associated with each of the corresponding String identifiers. HoldLabels should be left for the compiler to infer using _ -- it specifies the remaining fields that are not affected by this method.

Since the values from the fields denoted in MeltLabels will all be combined into one field they must be the same data type.

Example

Let us consider a table of employee salaries with the tablespace:

tablespace![
    table salary {
        EmpId: u64,
        Year2010: f64,
        Year2011: f64,
        Year2012: f64,
        Year2013: f64,
        Year2014: f64,
    }
];

which, when first loaded from the source file, looks like this:

 EmpId | Year2010 | Year2011 | Year2012 | Year2013 | Year2014
-------+----------+----------+----------+----------+----------
 0     | 1500     | 1600     | 1700     | 1850     | 2000
 1     | 900      | 920      | 940      | 940      | 970
 2     | 600      | 800      | 900      | 1020     | 1100

While this is a valid way to store and present this data, there are definitely cases where you might want to have the different years separated into different records instead of having a column for each year. That's what melt is for!

For the first step, we need to create new labels for melt's NameLabel and ValueLabel type arguments. The NameLabel will be filled in with String identifiers for the field a data point came from, and the ValueLabel will be filled with the data values themselves. We can add these two labels to our previous tablespace call.

Next, after we load the original data, we call melt:

tablespace![
    table salary {
        EmpId: u64,
        Year2010: f64,
        Year2011: f64,
        Year2012: f64,
        Year2013: f64,
        Year2014: f64,
        SalaryYear: String,
        Salary: f64,
    }
];
fn main() {
    // <load data into DataView orig_table>
    // quick check to make sure we loaded the right table: with 3 rows, 6 fields
    assert_eq!((orig_table.nrows(), orig_table.nfields()), (3, 6));

    let melted_table = orig_table.melt::<
        Labels![Year2010, Year2011, Year2012, Year2013, Year2014],
        SalaryYear,
        Salary,
        _,
    >();

    // melted table should have 15 rows -- 5 for each of our 3 employees -- and 3 fields
    assert_eq!((melted_table.nrows(), melted_table.nfields()), (15, 3));
    println!("{}", melted_table);
}

This call to melt transforms the year fields into two new fields: one which contains the salary year (text) and has the label SalaryYear, and one which contains the salary values (floating-point) with the label Salary.

The first type argument is the list of year labels we want to melt, the second is the new label for the year specifier field, the third is the new label for the year value field, and we let the compiler compute the list of labels we aren't melting (in this case, the EmpId field).

As a result we should have a table with 15 rows, five for each of our three employees, and three fields: EmpId, SalaryYear, and Salary. This code should output:

 SalaryYear | EmpId | Salary
------------+-------+--------
 Year2010   | 0     | 1500
 Year2011   | 0     | 1600
 Year2012   | 0     | 1700
 Year2013   | 0     | 1850
 Year2014   | 0     | 2000
 Year2010   | 1     | 900
 Year2011   | 1     | 920
 Year2012   | 1     | 940
 Year2013   | 1     | 940
 Year2014   | 1     | 970
 Year2010   | 2     | 600
 Year2011   | 2     | 800
 Year2012   | 2     | 900
 Year2013   | 2     | 1020
 Year2014   | 2     | 1100

impl<Labels, Frames> DataView<Labels, Frames> where
    Frames: Len + NRows + AssocDataIndexCons<Labels>,
    AssocDataIndexConsOf<Labels, Frames>: DeriveCapabilities<MinFn>,
    AssocDataIndexConsOf<Labels, Frames>: DeriveCapabilities<MaxFn>,
    AssocDataIndexConsOf<Labels, Frames>: DeriveCapabilities<SumFn>,
    AssocDataIndexConsOf<Labels, Frames>: DeriveCapabilities<MeanFn>,
    AssocDataIndexConsOf<Labels, Frames>: DeriveCapabilities<StDevFn>,
    Labels: Len + StrLabels + StrTypes, 

pub fn view_stats(&self) -> ViewStats

Compute and return general statistics for this DataView.

Trait Implementations

impl<Labels, Frames> NRows for DataView<Labels, Frames> where
    Frames: NRows, 

fn nrows(&self) -> usize

Return the number of rows in this data structure.

impl<Labels, Frames> IntoFrame for DataView<Labels, Frames> where
    Labels: SimpleFrameFields,
    DataFrame<<Labels as SimpleFrameFields>::Fields, DataView<Labels, Frames>>: From<DataView<Labels, Frames>>, 

type FrameFields = <Labels as SimpleFrameFields>::Fields

The FrameFields type parameter for the output DataFrame.

type FramedStore = DataView<Labels, Frames>

The FramedStore type parameter for the output DataFrame.

type Output = DataFrame<Self::FrameFields, Self::FramedStore>

The output DataFrame (should always be DataFrame<Self::FrameFields, Self::FramedStore>).

fn into_frame(self) -> Self::Output

Convert self into a DataFrame object.

impl<MeltLabel, Labels, Frames> IntoMeltFrame<MeltLabel> for DataView<Labels, Frames> where
    Labels: MeltFrameFields<MeltLabel>, 

type FrameFields = <Labels as MeltFrameFields<MeltLabel>>::Fields

The FrameFields type parameter for the output DataFrame.

type FramedStore = DataView<Labels, Frames>

The FramedStore type parameter for the output DataFrame.

type Output = DataFrame<Self::FrameFields, Self::FramedStore>

The output DataFrame (should always be DataFrame<Self::FrameFields, Self::FramedStore>).

fn into_melt_frame(self) -> Self::Output

Convert self into a DataFrame object.

impl<Labels, Frames, NewFrame> AddFrame<NewFrame> for DataView<Labels, Frames> where
    NewFrame: AsFrameLookup<<Frames as Len>::Len>,
    Frames: Len,
    Labels: Append<<NewFrame as AsFrameLookup<<Frames as Len>::Len>>::Output>,
    Frames: Clone + PushBack<Labeled<<Frames as Len>::Len, NewFrame>>, 

type Output = DataView<<Labels as Append<<NewFrame as AsFrameLookup<<Frames as Len>::Len>>::Output>>::Appended, <Frames as PushBack<Labeled<<Frames as Len>::Len, NewFrame>>>::Output>

DataView type after adding Frame.

fn add_frame(&self, frame: NewFrame) -> Self::Output

Add a new frame to self, returning a new DataView with the extra frame.

impl<LLabels, LFrames, RLabels, RFrames> Merge<RLabels, RFrames> for DataView<LLabels, LFrames> where
    LFrames: Len,
    RLabels: UpdateFrameIndexMarker<<LFrames as Len>::Len>,
    LLabels: Append<<RLabels as UpdateFrameIndexMarker<<LFrames as Len>::Len>>::Output>,
    RFrames: Clone + UpdateFrameIndex<<LFrames as Len>::Len>,
    LFrames: Append<<RFrames as UpdateFrameIndex<<LFrames as Len>::Len>>::Output> + Clone, 

type OutLabels = <LLabels as Append<<RLabels as UpdateFrameIndexMarker<<LFrames as Len>::Len>>::Output>>::Appended

Resulting Labels type parameter of merged DataView object.

type OutFrames = <LFrames as Append<<RFrames as UpdateFrameIndex<<LFrames as Len>::Len>>::Output>>::Appended

Resulting Frames type parameterof merged DataView object.

fn merge(
    &self,
    right: &DataView<RLabels, RFrames>
) -> DataView<Self::OutLabels, Self::OutFrames>

Merge this object with right, producing a new DataView with OutLabels and OutFrames type parameters.

impl<LLabels, LFrames, RLabels, RFrames, LLabel, RLabel, Pred> SortMergeJoin<RLabels, RFrames, Join<LLabel, RLabel, Pred>> for DataView<LLabels, LFrames> where
    LFrames: JoinIntoStore<LLabels, DataStore<Nil>>,
    RFrames: JoinIntoStore<RLabels, <LFrames as JoinIntoStore<LLabels, DataStore<Nil>>>::Output>,
    <RFrames as JoinIntoStore<RLabels, <LFrames as JoinIntoStore<LLabels, DataStore<Nil>>>::Output>>::Output: IntoView,
    Self: SelectFieldByLabel<LLabel>,
    Self::Output: SortOrder,
    VFieldTypeOf<Self, LLabel>: Ord + PartialEq,
    DataView<RLabels, RFrames>: SelectFieldByLabel<RLabel, DType = VFieldTypeOf<Self, LLabel>>,
    <DataView<RLabels, RFrames> as SelectFieldByLabel<RLabel>>::Output: SortOrder,
    Pred: Predicate, 

type Output = <<RFrames as JoinIntoStore<RLabels, <LFrames as JoinIntoStore<LLabels, DataStore<Nil>>>::Output>>::Output as IntoView>::Output

Resultant data structure after join.

fn join(&self, right: &DataView<RLabels, RFrames>) -> Self::Output

Join this object with a DataView, using the join details specified with Join.

impl<Labels, Frames> FieldSelect for DataView<Labels, Frames>

fn field<Label>(&self) -> Self::Output where
    Self: SelectFieldByLabel<Label>, 

Returns a struct containing the data for the field specified by Label.

impl<Labels, Frames, Label> SelectFieldByLabel<Label> for DataView<Labels, Frames> where
    Frames: SelectFieldFromLabels<Labels, Label>, 

type DType = <Frames as SelectFieldFromLabels<Labels, Label>>::DType

Data type of accessed data.

type Output = <Frames as SelectFieldFromLabels<Labels, Label>>::Output

The return type for the select_field method.

fn select_field(&self) -> Self::Output

Returns an object that provides DataIndex access to the data in the field specified by Label.

impl<Labels, Frames, LabelList> Subview<LabelList> for DataView<Labels, Frames> where
    Labels: FrameIndexList + HasLabels<LabelList> + LabelSubset<LabelList>,
    Frames: Clone + SubsetClone<<Labels as FrameIndexList>::LabelList>, 

type Output = DataView<<Labels as LabelSubset<LabelList>>::Output, <Frames as SubsetClone<<Labels as FrameIndexList>::LabelList>>::Output>

Resulting subview DataView type.

fn subview(&self) -> Self::Output

Generate a new subview of this DataView, resulting in a newly created DataView object only containing the fields matching the labels in LabelList.

impl<Labels, Frames, RLabels, RFrames> ViewMerge<DataView<RLabels, RFrames>> for DataView<Labels, Frames> where
    Self: Merge<RLabels, RFrames>,
    RFrames: NRows,
    Frames: NRows,
    Self::OutLabels: IsLabelSet<IsSet = True>, 

type Output = DataView<Self::OutLabels, Self::OutFrames>

Resultant DataView type.

fn merge(&self, right: &DataView<RLabels, RFrames>) -> Result<Self::Output>

Merge this DataView with another DataView. Can fail if the DataViews do not have the same number of rows.

impl<Labels: Clone, Frames: Clone> Clone for DataView<Labels, Frames>

fn clone(&self) -> DataView<Labels, Frames>

Returns a copy of the value.

default fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Labels: Default, Frames: Default> Default for DataView<Labels, Frames>

fn default() -> DataView<Labels, Frames>

Returns the "default value" for a type.

impl<Labels, Frames> From<DataView<Labels, Frames>> for DataFrame<<Labels as SimpleFrameFields>::Fields, DataView<Labels, Frames>> where
    Labels: SimpleFrameFields, 

fn from(
    view: DataView<Labels, Frames>
) -> DataFrame<<Labels as SimpleFrameFields>::Fields, DataView<Labels, Frames>>

Performs the conversion.

impl<Labels, Frames> Display for DataView<Labels, Frames> where
    Frames: Len + NRows + AssocDataIndexCons<Labels>,
    AssocDataIndexConsOf<Labels, Frames>: DeriveCapabilities<AddCellToRowFn>,
    Labels: StrLabels, 

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl<Labels: Debug, Frames: Debug> Debug for DataView<Labels, Frames>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<Labels, Frames> Serialize for DataView<Labels, Frames> where
    Labels: Len + SerializeViewField<Frames>, 

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.