diff --git a/src/Microsoft.Data.Analysis/DataFrame.cs b/src/Microsoft.Data.Analysis/DataFrame.cs index 905a6e1d4e..9ac0c4c3bb 100644 --- a/src/Microsoft.Data.Analysis/DataFrame.cs +++ b/src/Microsoft.Data.Analysis/DataFrame.cs @@ -79,44 +79,68 @@ public DataFrame(params DataFrameColumn[] columns) } /// - /// Returns a new DataFrame using the boolean values in + /// Returns a new containing the rows selected by . /// - /// A column of booleans + /// + /// A column whose value at each position selects the row at the same position. + /// A value of includes the row; or excludes it. + /// If the column is shorter than this , rows beyond the column's length are excluded. + /// public DataFrame Filter(PrimitiveDataFrameColumn filter) => Clone(filter); /// - /// Returns a new DataFrame using the row indices in + /// Returns a new containing the rows specified by . /// - /// A column of row indices + /// + /// A column whose values are zero-based row indices into this . + /// The values determine the order of the rows in the result, and repeated values produce repeated rows. + /// public DataFrame Filter(PrimitiveDataFrameColumn rowIndices) => Clone(rowIndices); /// - /// Returns a new DataFrame using the row indices in + /// Returns a new containing the rows specified by . /// - /// A column of row indices + /// + /// A column whose values are zero-based row indices into this . + /// The values determine the order of the rows in the result, and repeated values produce repeated rows. + /// public DataFrame Filter(PrimitiveDataFrameColumn rowIndices) => Clone(rowIndices); /// - /// Returns a new DataFrame using the boolean values in filter + /// Returns a new containing the rows selected by . /// - /// A column of booleans + /// + /// A column whose value at each position selects the row at the same position. + /// A value of includes the row; or excludes it. + /// If the column is shorter than this , rows beyond the column's length are excluded. + /// public DataFrame this[PrimitiveDataFrameColumn rowFilter] => Filter(rowFilter); /// - /// Returns a new DataFrame using the row indices in + /// Returns a new containing the rows specified by . /// - /// A column of row indices + /// + /// A column whose values are zero-based row indices into this . + /// The values determine the order of the rows in the result, and repeated values produce repeated rows. + /// public DataFrame this[PrimitiveDataFrameColumn rowIndices] => Filter(rowIndices); /// - /// Returns a new DataFrame using the row indices in + /// Returns a new containing the rows specified by . /// - /// A column of row indices + /// + /// A column whose values are zero-based row indices into this . + /// The values determine the order of the rows in the result, and repeated values produce repeated rows. + /// public DataFrame this[PrimitiveDataFrameColumn rowIndices] => Filter(rowIndices); /// - /// Returns a new DataFrame using the row indices in + /// Returns a new containing the rows specified by . /// + /// + /// A collection of zero-based row indices into this . + /// The enumeration order determines the order of the rows in the result, and repeated values produce repeated rows. + /// public DataFrame this[IEnumerable rowIndices] { get @@ -127,8 +151,12 @@ public DataFrame this[IEnumerable rowIndices] } /// - /// Returns a new DataFrame using the row indices in + /// Returns a new containing the rows specified by . /// + /// + /// A collection of zero-based row indices into this . + /// The enumeration order determines the order of the rows in the result, and repeated values produce repeated rows. + /// public DataFrame this[IEnumerable rowIndices] { get @@ -139,8 +167,13 @@ public DataFrame this[IEnumerable rowIndices] } /// - /// Returns a new DataFrame using the boolean values in + /// Returns a new containing the rows selected by . /// + /// + /// A collection whose value at each position selects the row at the same position. + /// A value of includes the row and excludes it. + /// If the collection contains fewer values than this has rows, the remaining rows are excluded. + /// public DataFrame this[IEnumerable rowFilter] { get diff --git a/src/Microsoft.Data.Analysis/DataFrameColumn.Computations.cs b/src/Microsoft.Data.Analysis/DataFrameColumn.Computations.cs index fedfb36325..9804e936ca 100644 --- a/src/Microsoft.Data.Analysis/DataFrameColumn.Computations.cs +++ b/src/Microsoft.Data.Analysis/DataFrameColumn.Computations.cs @@ -47,6 +47,12 @@ public virtual DataFrameColumn CumulativeMax(bool inPlace = false) /// /// Updates column values at rowIndices with its cumulative rowIndices maximum /// + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// + /// + /// to update this column; to return a new column. + /// public virtual DataFrameColumn CumulativeMax(IEnumerable rowIndices, bool inPlace = false) { throw new NotImplementedException(); @@ -63,6 +69,12 @@ public virtual DataFrameColumn CumulativeMin(bool inPlace = false) /// /// Updates column values at rowIndices with its cumulative rowIndices minimum /// + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// + /// + /// to update this column; to return a new column. + /// public virtual DataFrameColumn CumulativeMin(IEnumerable rowIndices, bool inPlace = false) { throw new NotImplementedException(); @@ -79,6 +91,12 @@ public virtual DataFrameColumn CumulativeProduct(bool inPlace = false) /// /// Updates column values at rowIndices with its cumulative rowIndices product /// + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// + /// + /// to update this column; to return a new column. + /// public virtual DataFrameColumn CumulativeProduct(IEnumerable rowIndices, bool inPlace = false) { throw new NotImplementedException(); @@ -95,6 +113,12 @@ public virtual DataFrameColumn CumulativeSum(bool inPlace = false) /// /// Updates column values at rowIndices with its cumulative rowIndices sum /// + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// + /// + /// to update this column; to return a new column. + /// public virtual DataFrameColumn CumulativeSum(IEnumerable rowIndices, bool inPlace = false) { throw new NotImplementedException(); @@ -111,6 +135,9 @@ public virtual object Max() /// /// Returns the maximum of the values at rowIndices /// + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// public virtual object Max(IEnumerable rowIndices) { throw new NotImplementedException(); @@ -127,6 +154,9 @@ public virtual object Min() /// /// Returns the minimum of the values at the rowIndices /// + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// public virtual object Min(IEnumerable rowIndices) { throw new NotImplementedException(); @@ -143,6 +173,9 @@ public virtual object Product() /// /// Returns the product of the values at the rowIndices /// + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// public virtual object Product(IEnumerable rowIndices) { throw new NotImplementedException(); @@ -159,6 +192,9 @@ public virtual object Sum() /// /// Returns the sum of the values at the rowIndices /// + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// public virtual object Sum(IEnumerable rowIndices) { throw new NotImplementedException(); diff --git a/src/Microsoft.Data.Analysis/DataFrameColumn.Computations.tt b/src/Microsoft.Data.Analysis/DataFrameColumn.Computations.tt index ebe4785ae7..6f784e38d1 100644 --- a/src/Microsoft.Data.Analysis/DataFrameColumn.Computations.tt +++ b/src/Microsoft.Data.Analysis/DataFrameColumn.Computations.tt @@ -22,6 +22,16 @@ namespace Microsoft.Data.Analysis /// /// <#=compMethod.MethodComments#> /// +<# if (compMethod.SupportsRowSubsets == true) {#> + /// + /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly. + /// +<# } #> +<# if (compMethod.MethodType == MethodType.ElementwiseComputation && compMethod.HasReturnValue == false && compMethod.SupportsRowSubsets == true) {#> + /// + /// to update this column; to return a new column. + /// +<# } #> <# if (compMethod.MethodType == MethodType.ElementwiseComputation && compMethod.HasReturnValue == false && compMethod.SupportsRowSubsets == true) {#> public virtual DataFrameColumn <#=compMethod.MethodName#>(IEnumerable rowIndices, bool inPlace = false) <# } else if (compMethod.MethodType == MethodType.ElementwiseComputation && compMethod.HasReturnValue == false) {#> diff --git a/src/Microsoft.Data.Analysis/DataFrameColumn.cs b/src/Microsoft.Data.Analysis/DataFrameColumn.cs index b88ffc93d7..2f7fae57b4 100644 --- a/src/Microsoft.Data.Analysis/DataFrameColumn.cs +++ b/src/Microsoft.Data.Analysis/DataFrameColumn.cs @@ -210,18 +210,26 @@ public object this[long rowIndex] protected internal virtual void Resize(long length) => throw new NotImplementedException(); /// - /// Clone column to produce a copy + /// Clones the column. /// - /// + /// The number of null values to append to the copied values. /// A new public DataFrameColumn Clone(long numberOfNullsToAppend = 0) => CloneImplementation(numberOfNullsToAppend); /// - /// Clone column to produce a copy potentially changing the order of values by supplying mapIndices and an invert flag + /// Clones the column, selecting and ordering values according to . /// - /// - /// - /// + /// + /// A Boolean, , or column that determines which values to copy. + /// For a Boolean column, the value at each position selects the value at the same position when it is + /// . For an integer column, each value is a zero-based index into this column; + /// the map order determines the result order, and repeated indices produce repeated values. + /// + /// + /// to process integer values in in reverse order; + /// otherwise, . This parameter does not affect a Boolean map. + /// + /// The number of null values to append after the selected values. /// A new public DataFrameColumn Clone(DataFrameColumn mapIndices, bool invertMapIndices = false, long numberOfNullsToAppend = 0) => CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend); diff --git a/src/Microsoft.Data.Analysis/DataFrameColumns/ArrowStringDataFrameColumn.cs b/src/Microsoft.Data.Analysis/DataFrameColumns/ArrowStringDataFrameColumn.cs index a6280dd78a..82732facb2 100644 --- a/src/Microsoft.Data.Analysis/DataFrameColumns/ArrowStringDataFrameColumn.cs +++ b/src/Microsoft.Data.Analysis/DataFrameColumns/ArrowStringDataFrameColumn.cs @@ -365,11 +365,13 @@ protected internal override Apache.Arrow.Array ToArrowArray(long startIndex, int protected internal override PrimitiveDataFrameColumn GetSortIndices(bool ascending, bool putNullValuesLast) => throw new NotSupportedException(); + /// public new ArrowStringDataFrameColumn Clone(long numberOfNullsToAppend = 0) { return (ArrowStringDataFrameColumn)CloneImplementation(numberOfNullsToAppend); } + /// public new ArrowStringDataFrameColumn Clone(DataFrameColumn mapIndices, bool invertMapIndices = false, long numberOfNullsToAppend = 0) { return (ArrowStringDataFrameColumn)CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend); diff --git a/src/Microsoft.Data.Analysis/DataFrameColumns/StringDataFrameColumn.cs b/src/Microsoft.Data.Analysis/DataFrameColumns/StringDataFrameColumn.cs index fb11576311..e1a6036582 100644 --- a/src/Microsoft.Data.Analysis/DataFrameColumns/StringDataFrameColumn.cs +++ b/src/Microsoft.Data.Analysis/DataFrameColumns/StringDataFrameColumn.cs @@ -275,11 +275,13 @@ ValueTuple GetFirstNonNullValueStartingAtIndex(int stringBufferInde return columnSortIndices; } + /// public new StringDataFrameColumn Clone(DataFrameColumn mapIndices, bool invertMapIndices, long numberOfNullsToAppend) { return (StringDataFrameColumn)CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend); } + /// public new StringDataFrameColumn Clone(long numberOfNullsToAppend = 0) { return (StringDataFrameColumn)CloneImplementation(numberOfNullsToAppend); diff --git a/src/Microsoft.Data.Analysis/DataFrameColumns/VBufferDataFrameColumn.cs b/src/Microsoft.Data.Analysis/DataFrameColumns/VBufferDataFrameColumn.cs index 7b3c0d49a3..b86c6d6367 100644 --- a/src/Microsoft.Data.Analysis/DataFrameColumns/VBufferDataFrameColumn.cs +++ b/src/Microsoft.Data.Analysis/DataFrameColumns/VBufferDataFrameColumn.cs @@ -267,11 +267,13 @@ private VBufferDataFrameColumn CloneImplementation(PrimitiveDataFrameColumn public new VBufferDataFrameColumn Clone(DataFrameColumn mapIndices, bool invertMapIndices, long numberOfNullsToAppend) { return (VBufferDataFrameColumn)CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend); } + /// public new VBufferDataFrameColumn Clone(long numberOfNullsToAppend = 0) { return (VBufferDataFrameColumn)CloneImplementation(numberOfNullsToAppend); diff --git a/src/Microsoft.Data.Analysis/PrimitiveDataFrameColumn.cs b/src/Microsoft.Data.Analysis/PrimitiveDataFrameColumn.cs index 33ecd05e65..696a0d0b6d 100644 --- a/src/Microsoft.Data.Analysis/PrimitiveDataFrameColumn.cs +++ b/src/Microsoft.Data.Analysis/PrimitiveDataFrameColumn.cs @@ -400,20 +400,28 @@ public override bool HasDescription() /// /// Returns a clone of this column. /// - /// - /// + /// The number of null values to append to the copied values. + /// A new . public new PrimitiveDataFrameColumn Clone(long numberOfNullsToAppend = 0) { return (PrimitiveDataFrameColumn)CloneImplementation(numberOfNullsToAppend); } /// - /// Returns a clone of this column. + /// Clones the column, selecting and ordering values according to . /// - /// A column who values are used as indices - /// - /// - /// + /// + /// A Boolean, , or column that determines which values to copy. + /// For a Boolean column, the value at each position selects the value at the same position when it is + /// . For an integer column, each value is a zero-based index into this column; + /// the map order determines the result order, and repeated indices produce repeated values. + /// + /// + /// to process integer values in in reverse order; + /// otherwise, . This parameter does not affect a Boolean map. + /// + /// The number of null values to append after the selected values. + /// A new . public new PrimitiveDataFrameColumn Clone(DataFrameColumn mapIndices, bool invertMapIndices = false, long numberOfNullsToAppend = 0) { return (PrimitiveDataFrameColumn)CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend); @@ -494,6 +502,16 @@ private PrimitiveDataFrameColumn CloneImplementation(PrimitiveDataFrameCol return ret; } + /// + /// Clones the column using the values in as zero-based indices into this column. + /// + /// + /// The indices of values to copy. Their order determines the result order, and repeated indices produce repeated values. + /// + /// + /// to process the indices in reverse order; otherwise, . + /// + /// A new . public PrimitiveDataFrameColumn Clone(PrimitiveDataFrameColumn mapIndices, bool invertMapIndices = false) { if (mapIndices is null) @@ -502,6 +520,16 @@ public PrimitiveDataFrameColumn Clone(PrimitiveDataFrameColumn mapIndic return CloneImplementation(mapIndices, invertMapIndices); } + /// + /// Clones the column using the values in as zero-based indices into this column. + /// + /// + /// The indices of values to copy. Their order determines the result order, and repeated indices produce repeated values. + /// + /// + /// to process the indices in reverse order; otherwise, . + /// + /// A new . public PrimitiveDataFrameColumn Clone(PrimitiveDataFrameColumn mapIndices, bool invertMapIndices = false) { if (mapIndices is null) @@ -510,6 +538,13 @@ public PrimitiveDataFrameColumn Clone(PrimitiveDataFrameColumn mapIndice return CloneImplementation(mapIndices, invertMapIndices); } + /// + /// Clones the column using the values in as zero-based indices into this column. + /// + /// + /// The indices of values to copy. Their enumeration order determines the result order, and repeated indices produce repeated values. + /// + /// A new . public PrimitiveDataFrameColumn Clone(IEnumerable mapIndices) { IEnumerator rows = mapIndices.GetEnumerator(); @@ -525,6 +560,13 @@ public PrimitiveDataFrameColumn Clone(IEnumerable mapIndices) return ret; } + /// + /// Clones the column using the values in as zero-based indices into this column. + /// + /// + /// The indices of values to copy. Their enumeration order determines the result order, and repeated indices produce repeated values. + /// + /// A new . public PrimitiveDataFrameColumn Clone(IEnumerable mapIndices) { return Clone(mapIndices.Select(x => (long)x));