update membership functiosn (#4)

Author: lucaferranti

.gitignore

@@ -3,8 +3,10 @@
 *.jl.mem
 Manifest.toml
 
+# automatically generated files during docs building
 /docs/build/
 indigo.css
 /docs/src/tutorials/
 /docs/src/applications/
-/docs/src/notebooks/
+/docs/src/notebooks/
+/docs/src/api/memberships.md

docs/make.jl

@@ -13,6 +13,7 @@ Pkg.add(Pkg.PackageSpec(name = "Documenter", rev = "30baed5")) # TODO remove onc
 
 using Documenter
 using DocThemeIndigo
+using InteractiveUtils
 using FuzzyLogic
 using Literate
 
@@ -53,6 +54,46 @@ for (root, _, files) in walkdir(jldir), file in files
     Literate.notebook(ipath, nbdir; execute = IS_CI, credit = false)
 end
 
+###################
+# CREATE API DOCS #
+###################
+
+function generate_memberships()
+    mfs = subtypes(FuzzyLogic.AbstractMembershipFunction)
+    open(joinpath(@__DIR__, "src", "api", "memberships.md"), "w") do f
+        write(f, """```@setup memberships
+        using FuzzyLogic
+        using Plots
+        ```
+
+        # Membership functions
+
+        """)
+        for mf in mfs
+            sec = string(mf)[1:(end - 2)] * " membership function"
+            write(f, """## $sec
+
+            ```@docs
+            $mf
+            ```
+
+            """)
+            docstring = match(r"```julia\nmf = (\w+\(.+\))\n```", string(Docs.doc(mf)))
+            if !isnothing(docstring)
+                mfex = only(docstring.captures)
+                write(f, """
+                ```@example memberships
+                plot($mfex, 0, 10) # hide
+                ```
+
+                """)
+            end
+        end
+    end
+end
+
+generate_memberships()
+
 ###############
 # CREATE HTML #
 ###############

docs/src/api/memberships.md

@@ -9,7 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 **initial public release**
 
 - initial domain specific language design and parser
-- initial membership functions: triangular, trapezoidal, gaussian, bell, linear, sigmoid, sum of sigmoids, product of sigmoids.
+- initial membership functions: triangular, trapezoidal, gaussian, bell, linear, sigmoid, sum of sigmoids, product of sigmoids, s-shaped, z-shaped, pi-shaped.
 - initial implementation of Mamdani and Sugeno inference systems (type 1)
   - min, prod and Łukasiewicz t-norms with corresponding conorms
   - min and prod implication

docs/src/changelog.md

@@ -13,7 +13,7 @@ include("evaluation.jl")
 include("plotting.jl")
 
 export DifferenceSigmoidMF, LinearMF, GeneralizedBellMF, GaussianMF, ProductSigmoidMF,
-       SigmoidMF, TrapezoidalMF, TriangularMF,
+       SigmoidMF, TrapezoidalMF, TriangularMF, SShapeMF, ZShapeMF, PiShapeMF,
        ProdAnd, MinAnd, ProbSumOr, MaxOr, MinImplication, ProdImplication,
        MaxAggregator, ProbSumAggregator, CentroidDefuzzifier, BisectorDefuzzifier,
        @fis, FuzzyInferenceSystem, Domain, Variable

src/FuzzyLogic.jl

@@ -12,7 +12,4 @@ using DocStringExtensions
                 $(TYPEDEF)
 
                 $(DOCSTRING)
-
-                ## Fields
-                $(TYPEDFIELDS)
                 """

src/docstrings.jl

@@ -2,8 +2,18 @@
 
 abstract type AbstractMembershipFunction end
 
-@doc raw"""
-Generalized Bell membership function ``\frac{1}{1+\vert\frac{x-c}{a}\vert^{2b}}``.
+"""
+Generalized Bell membership function ``\\frac{1}{1+\\vert\\frac{x-c}{a}\\vert^{2b}}``.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = GeneralizedBellMF(2, 4, 5)
+```
 """
 struct GeneralizedBellMF{T <: Real, S <: Real} <: AbstractMembershipFunction
     "Width of the curve, the bigger the wider."
@@ -17,6 +27,16 @@ end
 
 """
 Gaussian membership function ``e^{-\\frac{(x-μ)²}{2σ²}}``.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = GaussianMF(5.0, 1.5)
+```
 """
 struct GaussianMF{T <: Real} <: AbstractMembershipFunction
     "mean ``μ``."
@@ -28,6 +48,16 @@ end
 
 """
 Triangular membership function.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = TriangularMF(3, 5, 7)
+```
 """
 struct TriangularMF{T <: Real} <: AbstractMembershipFunction
     "left foot."
@@ -41,6 +71,16 @@ end
 
 """
 Trapezoidal membership function.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = TrapezoidalMF(1, 3, 7, 9)
+```
 """
 struct TrapezoidalMF{T <: Real} <: AbstractMembershipFunction
     "left foot."
@@ -59,6 +99,16 @@ end
 """
 Linear membership function.
 If ``a < b``, it is increasing (S-shaped), otherwise it is decreasing (Z-shaped).
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = LinearMF(2, 8)
+```
 """
 struct LinearMF{T <: Real} <: AbstractMembershipFunction
     "foot."
@@ -68,8 +118,18 @@ struct LinearMF{T <: Real} <: AbstractMembershipFunction
 end
 (mf::LinearMF)(x) = max(min((x - mf.a) / (mf.b - mf.a), 1), 0)
 
-@doc raw"""
-Sigmoid membership function ``\frac{1}{1+e^{-a(x-c)}}``.
+"""
+Sigmoid membership function ``\\frac{1}{1+e^{-a(x-c)}}``.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = SigmoidMF(2, 5)
+```
 """
 struct SigmoidMF{T <: Real} <: AbstractMembershipFunction
     "parameter controlling the slope of the curve."
@@ -81,6 +141,16 @@ end
 
 """
 Difference of two sigmoids. See also [`SigmoidMF`](@ref).
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = DifferenceSigmoidMF(5, 2, 5, 7)
+```
 """
 struct DifferenceSigmoidMF{T <: Real} <: AbstractMembershipFunction
     "slope of the first sigmoid."
@@ -99,6 +169,16 @@ end
 
 """
 Product of two sigmoids. See also [`SigmoidMF`](@ref).
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = ProductSigmoidMF(2, 3, -5, 8)
+```
 """
 struct ProductSigmoidMF{T <: Real} <: AbstractMembershipFunction
     "slope of the first sigmoid."
@@ -113,3 +193,87 @@ end
 function (mf::ProductSigmoidMF)(x)
     return 1 / ((1 + exp(-mf.a1 * (x - mf.c1))) * (1 + exp(-mf.a2 * (x - mf.c2))))
 end
+
+"""
+S-shaped membership function.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = SShapeMF(1, 8)
+```
+"""
+struct SShapeMF{T <: Real} <: AbstractMembershipFunction
+    "foot."
+    a::T
+    "shoulder."
+    b::T
+end
+function (s::SShapeMF)(x::T) where {T <: Real}
+    x <= s.a && return zero(float(T))
+    x >= s.b && return one(float(T))
+    x >= (s.a + s.b) / 2 && return 1 - 2 * ((x - s.b) / (s.b - s.a))^2
+    return 2 * ((x - s.a) / (s.b - s.a))^2
+end
+
+"""
+Z-shaped membership function.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = ZShapeMF(3, 7)
+```
+"""
+struct ZShapeMF{T <: Real} <: AbstractMembershipFunction
+    "shoulder."
+    a::T
+    "foot."
+    b::T
+end
+function (z::ZShapeMF)(x::T) where {T <: Real}
+    x <= z.a && return one(float(T))
+    x >= z.b && return zero(float(T))
+    x >= (z.a + z.b) / 2 && return 2 * ((x - z.b) / (z.b - z.a))^2
+    return 1 - 2 * ((x - z.a) / (z.b - z.a))^2
+end
+
+"""
+Π-shaped membership function.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Example
+
+```julia
+mf = PiShapeMF(1, 4, 5, 10)
+```
+"""
+struct PiShapeMF{T <: Real} <: AbstractMembershipFunction
+    "left foot."
+    a::T
+    "left shoulder."
+    b::T
+    "right shoulder."
+    c::T
+    "right foot."
+    d::T
+end
+function (p::PiShapeMF)(x::T) where {T <: Real}
+    (x <= p.a || x >= p.d) && return zero(float(T))
+    p.b <= x <= p.c && return one(float(T))
+    x <= (p.a + p.b) / 2 && return 2 * ((x - p.a) / (p.b - p.a))^2
+    x <= p.b && return 1 - 2 * ((x - p.b) / (p.b - p.a))^2
+    x <= (p.c + p.d) / 2 && return 1 - 2 * ((x - p.c) / (p.d - p.c))^2
+    return 2 * ((x - p.d) / (p.d - p.c))^2
+end

src/membership_functions.jl

@@ -78,3 +78,32 @@ end
     @test f(8) == 0
     @test f(9) == 0
 end
+
+@testset "S-shaped MF" begin
+    mf = SShapeMF(1, 8)
+    @test mf(0) == 0
+    @test mf(1) == 0
+    @test mf(4.5) == 0.5
+    @test mf(8) == 1
+    @test mf(9) == 1
+end
+
+@testset "Z-shaped MF" begin
+    mf = ZShapeMF(3, 7)
+    @test mf(2) == 1
+    @test mf(3) == 1
+    @test mf(5) == 0.5
+    @test mf(7) == 0
+    @test mf(9) == 0
+end
+
+@testset "Pi-shaped MF" begin
+    mf = PiShapeMF(1, 4, 5, 10)
+    @test mf(1) == 0
+    @test mf(2.5) == 0.5
+    @test mf(4) == 1
+    @test mf(4.5) == 1
+    @test mf(5) == 1
+    @test mf(7.5) == 0.5
+    @test mf(10) == 0
+end