Add Param and methods to Spark.ML (#586)

Author: GoEddie

.ionide/symbolCache.db

@@ -5,6 +5,7 @@
 using System.Collections.Generic;
 using System.IO;
 using Microsoft.Spark.ML.Feature;
+using Microsoft.Spark.ML.Feature.Param;
 using Microsoft.Spark.Sql;
 using Microsoft.Spark.UnitTest.TestUtils;
 using Xunit;
@@ -58,6 +59,19 @@ public void TestBucketizer()
                 Bucketizer loadedBucketizer = Bucketizer.Load(savePath);
                 Assert.Equal(bucketizer.Uid(), loadedBucketizer.Uid());
             }
+            
+            Assert.NotEmpty(bucketizer.ExplainParams());
+            
+            Param handleInvalidParam = bucketizer.GetParam("handleInvalid");
+            Assert.NotEmpty(handleInvalidParam.Doc);
+            Assert.NotEmpty(handleInvalidParam.Name);
+            Assert.Equal(handleInvalidParam.Parent, bucketizer.Uid());
+
+            Assert.NotEmpty(bucketizer.ExplainParam(handleInvalidParam));
+            bucketizer.Set(handleInvalidParam, "keep");
+            Assert.Equal("keep", bucketizer.GetHandleInvalid());
+             
+            Assert.Equal("error", bucketizer.Clear(handleInvalidParam).GetHandleInvalid());
         }
 
         [Fact]

src/csharp/Microsoft.Spark.E2ETest/IpcTests/ML/Feature/BucketizerTests.cs

@@ -0,0 +1,35 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Microsoft.Spark.ML.Feature.Param;
+using Microsoft.Spark.Sql;
+using Xunit;
+
+namespace Microsoft.Spark.E2ETest.IpcTests.ML.ParamTests
+{
+    [Collection("Spark E2E Tests")]
+    public class ParamTests
+    {
+        private readonly SparkSession _spark;
+
+        public ParamTests(SparkFixture fixture)
+        {
+            _spark = fixture.Spark;
+        }
+
+        [Fact]
+        public void Test()
+        {
+            const string expectedParent = "parent";
+            const string expectedName = "name";
+            const string expectedDoc = "doc";
+            
+            var param = new Param(expectedParent, expectedName, expectedDoc);
+            
+            Assert.Equal(expectedParent, param.Parent);
+            Assert.Equal(expectedDoc, param.Doc);
+            Assert.Equal(expectedName, param.Name);
+        }
+    }
+}

src/csharp/Microsoft.Spark.E2ETest/IpcTests/ML/Param/ParamTests.cs

@@ -56,7 +56,49 @@ internal FeatureBase(JvmObjectReference jvmObject)
         public T Save(string path) => 
             WrapAsType((JvmObjectReference)_jvmObject.Invoke("save", path));
 
-        private T WrapAsType(JvmObjectReference reference)
+        /// <summary>
+        /// Clears any value that was previously set for this <see cref="Param"/>. The value is
+        /// reset to the default value.
+        /// </summary>
+        /// <param name="param">The <see cref="Param"/> to set back to its original value</param>
+        /// <returns>Object reference that was used to clear the <see cref="Param"/></returns>
+        public T Clear(Param.Param param) => 
+            WrapAsType((JvmObjectReference)_jvmObject.Invoke("clear", param));
+
+        /// <summary>
+        /// Returns a description of how a specific <see cref="Param"/> works and is currently set.
+        /// </summary>
+        /// <param name="param">The <see cref="Param"/> to explain</param>
+        /// <returns>Description of the <see cref="Param"/></returns>
+        public string ExplainParam(Param.Param param) => 
+            (string)_jvmObject.Invoke("explainParam", param);
+
+        /// <summary>
+        /// Returns a description of how all of the <see cref="Param"/>'s that apply to this object
+        /// work and how they are currently set.
+        /// </summary>
+        /// <returns>Description of all the applicable <see cref="Param"/>'s</returns>
+        public string ExplainParams() => (string)_jvmObject.Invoke("explainParams");
+
+        /// <summary>
+        /// Retrieves a <see cref="Param"/> so that it can be used to set the value of the
+        /// <see cref="Param"/> on the object.
+        /// </summary>
+        /// <param name="paramName">The name of the <see cref="Param"/> to get.</param>
+        /// <returns><see cref="Param"/> that can be used to set the actual value</returns>
+        public Param.Param GetParam(string paramName) => 
+            new Param.Param((JvmObjectReference)_jvmObject.Invoke("getParam", paramName));
+
+        /// <summary>
+        /// Sets the value of a specific <see cref="Param"/>.
+        /// </summary>
+        /// <param name="param"><see cref="Param"/> to set the value of</param>
+        /// <param name="value">The value to use</param>
+        /// <returns>The object that contains the newly set <see cref="Param"/></returns>
+        public T Set(Param.Param param, object value) => 
+            WrapAsType((JvmObjectReference)_jvmObject.Invoke("set", param, value));
+
+        private static T WrapAsType(JvmObjectReference reference)
         {
             ConstructorInfo constructor = typeof(T)
                 .GetConstructors(BindingFlags.NonPublic | BindingFlags.Instance)

src/csharp/Microsoft.Spark/ML/Feature/FeatureBase.cs

@@ -0,0 +1,83 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using Microsoft.Spark.Interop;
+using Microsoft.Spark.Interop.Ipc;
+
+namespace Microsoft.Spark.ML.Feature.Param
+{
+    /// <summary>
+    /// A <see cref="Param"/> with self-contained documentation and optionally default value.
+    ///
+    /// A <see cref="Param"/> references an individual parameter that includes documentation, the
+    /// name of the parameter and optionally a default value. Params can either be set using the
+    /// generic <see cref="Param"/> methods or by using explicit methods. For example
+    /// <see cref="Bucketizer"/> has <c>SetHandleInvalid</c> or you can call 
+    /// <c>GetParam("handleInvalid")</c>and then <see cref="Bucketizer"/>. Set using the
+    /// <see cref="Param"/> and the value you want to use.
+    /// </summary>
+    public class Param : IJvmObjectReferenceProvider
+    {
+        private static readonly string s_ParamClassName = 
+            "org.apache.spark.ml.param.Param";
+        
+        private readonly JvmObjectReference _jvmObject;
+        
+        /// <summary>
+        /// Creates a new instance of a <see cref="Param"/> which will be attached to the parent
+        /// specified. The most likely use case for a <see cref="Param"/> is being read from a 
+        /// parent object such as <see cref="Bucketizer"/> rather than independently
+        /// <param name="parent">The parent object to assign the <see cref="Param"/> to</param>
+        /// <param name="name">The name of this <see cref="Param"/></param>
+        /// <param name="doc">The documentation for this <see cref="Param"/></param>
+        /// </summary>
+        public Param(Identifiable parent, string name, string doc)
+            : this(SparkEnvironment.JvmBridge.CallConstructor(
+                s_ParamClassName, parent.Uid(), name, doc))
+        {
+        }
+        
+        /// <summary>
+        /// Creates a new instance of a <see cref="Param"/> which will be attached to the parent 
+        /// with the UID specified. The most likely use case for a <see cref="Param"/> is being 
+        /// read from a parent object such as <see cref="Bucketizer"/> rather than independently
+        /// <param name="parent">
+        /// The UID of the  parent object to assign the <see cref="Param"/> to
+        /// </param>
+        /// <param name="name">The name of this <see cref="Param"/></param>
+        /// <param name="doc">The documentation for this <see cref="Param"/></param>
+        /// </summary>
+        public Param(string parent, string name, string doc)
+            : this(SparkEnvironment.JvmBridge.CallConstructor(s_ParamClassName, parent, name, doc))
+        {
+        }
+
+        internal Param(JvmObjectReference jvmObject)
+        {
+            _jvmObject = jvmObject;
+        }
+        
+        JvmObjectReference IJvmObjectReferenceProvider.Reference => _jvmObject;
+        
+        /// <summary>
+        /// The description of what the <see cref="Param"/> does and how it works including any
+        /// defaults and the current value
+        /// </summary>
+        /// <returns>A description of how the <see cref="Param"/> works</returns>
+        public string Doc => (string)_jvmObject.Invoke("doc");
+        
+        /// <summary>
+        /// The name of the <see cref="Param"/>
+        /// </summary>
+        /// <returns>The name of the <see cref="Param"/></returns>
+        public string Name => (string)_jvmObject.Invoke("name");
+
+        /// <summary>
+        /// The object that contains the <see cref="Param"/>
+        /// </summary>
+        /// <returns>The UID of the parent oject that this <see cref="Param"/> belongs to</returns>
+        public string Parent => (string)_jvmObject.Invoke("parent");
+    }
+}