add gensurf function (#27)

* add gensurf function

* comment out gensurf tests and update tutorial

* update changelog

Author: lucaferranti

docs/make.jl

@@ -172,6 +172,7 @@ makedocs(;
                  "Membership functions" => "api/memberships.md",
                  "Reading/Writing" => "api/readwrite.md",
                  "Learning fuzzy models" => "api/genfis.md",
+                 "Plotting" => "api/plotting.md",
              ],
              "Contributor's Guide" => "contributing.md",
              "Release notes" => "changelog.md",

docs/src/api/plotting.md

@@ -0,0 +1,6 @@
+# Plotting functionalities
+
+
+```@docs
+gensurf
+```

docs/src/changelog.md

@@ -5,6 +5,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## Unreleased
 
 - ![](https://img.shields.io/badge/new%20feature-green.svg) added semi-elliptic membership functions
+- ![](https://img.shields.io/badge/new%20feature-green.svg) added `gensurf` to plot generating surface
 
 ## v0.1.2 -- 2023-03-12
 

docs/src/literate/tutorials/mamdani.jl

@@ -172,6 +172,11 @@ plot(fis, :service)
 
 plot(fis)
 
+# If the FIS has at most 2 inputs, we can plot the generating surface of the system using the function [`gensurf`](@ref).
+# This is a surface visualizing how the output changes as a function of the input.
+
+gensurf(fis)
+
 #=
 ## Inference
 

src/plotting.jl

@@ -123,3 +123,47 @@ end
         end
     end
 end
+
+@userplot GenSurf
+@recipe function f(plt::GenSurf;
+                   Npoints = 100)
+    fis = first(plt.args)
+
+    if length(fis.inputs) > 2
+        throw(ArgumentError("Cannot plot generating surface for a system with more than 2 inputs"))
+    end
+
+    if length(fis.outputs) > 1
+        throw(ArgumentError("Cannot plot generating surface for a system with more than one output."))
+    end
+
+    o = first(keys(fis.outputs))
+    if length(fis.inputs) == 2
+        x, y = fis.inputs
+        seriestype := :surface
+        xlabel --> first(keys(fis.inputs))
+        ylabel --> last(keys(fis.inputs))
+        zlabel --> o
+        range(x.domain.low, x.domain.high, Npoints),
+        range(x.domain.low, x.domain.high, Npoints), (x, y) -> fis((x, y))[o]
+    else
+        x = first(fis.inputs)
+        xlabel --> first(keys(fis.inputs))
+        ylabel --> o
+        legend --> nothing
+        range(x.domain.low, x.domain.high, Npoints), x -> fis((x,))[o]
+    end
+end
+
+"""
+    gensurf(fis::AbstractFuzzySystem; Npoints=100)
+
+Plots the generating surface of the given fuzzy inference system.
+The given FIS must have exactly one output and at most two inputs.
+
+### Inputs
+
+- `fis::AbstractFuzzySystem` -- fuzzy inference system to plot
+- `Npoints::Int64 (default 100)` -- number of sample points used for each input to plot the generating surface.
+"""
+gensurf

test/test_plotting.jl

@@ -1,5 +1,5 @@
 using FuzzyLogic
-using FuzzyLogic: Domain, Variable
+using FuzzyLogic: Domain, Variable, GenSurf
 using RecipesBase
 using Dictionaries
 using Test
@@ -119,3 +119,66 @@ end
     @test keys(plt.plotattributes) == Set([:fillrange, :legend, :fillalpha, :linealpha])
     @test plt.plotattributes[:fillrange](0.0) == mf.hi(0.0)
 end
+
+# @testset "Plotting generating surface" begin
+#     fis = @mamfis function tipper(service, food)::tip
+#         service := begin
+#             domain = 0:10
+#             poor = GaussianMF(0.0, 1.5)
+#             good = GaussianMF(5.0, 1.5)
+#             excellent = GaussianMF(10.0, 1.5)
+#         end
+
+#         food := begin
+#             domain = 0:10
+#             rancid = TrapezoidalMF(-2, 0, 1, 3)
+#             delicious = TrapezoidalMF(7, 9, 10, 12)
+#         end
+
+#         tip := begin
+#             domain = 0:30
+#             cheap = TriangularMF(0, 5, 10)
+#             average = TriangularMF(10, 15, 20)
+#             generous = TriangularMF(20, 25, 30)
+#         end
+
+#         service == poor || food == rancid --> tip == cheap
+#         service == good --> tip == average
+#         service == excellent || food == delicious --> tip == generous
+#     end
+
+#     plt = RecipesBase.apply_recipe(Dict{Symbol, Any}(), GenSurf((fis,)))[1]
+
+#     @test plt.args[1] == range(0, 10, 100)
+#     @test plt.args[2] == range(0, 10, 100)
+#     @test plt.args[3](1, 2) == fis((1, 2))[:tip]
+#     @test plt.plotattributes[:seriestype] == :surface
+#     @test plt.plotattributes[:xlabel] == :service
+#     @test plt.plotattributes[:ylabel] == :food
+#     @test plt.plotattributes[:zlabel] == :tip
+
+#     fis1 = @mamfis function fis1(x)::y
+#         x := begin
+#             domain = 0:10
+#             low = TriangularMF(0, 2, 4)
+#             med = TriangularMF(4, 6, 8)
+#             high = TriangularMF(8, 9, 10)
+#         end
+
+#         y := begin
+#             domain = 0:10
+#             low = TriangularMF(0, 2, 4)
+#             med = TriangularMF(4, 6, 8)
+#             high = TriangularMF(8, 9, 10)
+#         end
+
+#         x == low --> y == low
+#         x == med --> y == med
+#         x == high --> y == high
+#     end
+#     plt = RecipesBase.apply_recipe(Dict{Symbol, Any}(), FuzzyLogic.GenSurf((fis1,)))[1]
+#     @test plt.args[1] == range(0, 10, 100)
+#     @test plt.args[2](2.5) == 2.0
+#     @test plt.plotattributes ==
+#           Dict{Symbol, Any}(:ylabel => :y, :legend => nothing, :xlabel => :x)
+# end