Dokument nie jest aktualizowany od lipca 2010, nowsze informacje w manualu Supermatrix.

FUNCTION FACTORY 2

1. KONWENCJA

2. TWORZENIE OBIEKTÓW

2.1 COMPARE FUNCTIONS
2.2. FILTERS
2.3. WEIGHTS
2.4. SIMFUNCTIONS
2.5. SELECTORS
2.6. ROW RELATIVE SELECTORS
2.7. LOCAL SIMFUNCTIONS
2.8. RANKBUILDERS
2.9. LOCAL WEIGHERS
2.10. RFF SELECTORS
2.11. DISTANCE FUNCTIONS

3. ROZBUDOWA I SZCZEGÓŁY IMPLEMENTACYJNE

3.1. ARCHITEKRUTA FUNCTION FACTORY 2
3.2. ROZBUDOWA O NOWE KLASY

-----------------------------------------------

1. KONWENCJA

FunctionFactory2 produkuje obiekty funkcyjne (przede wszystkim CompareFunction) w oparciu o opis tekstowy i SuperMatrixPtr (boostowo opakowany wskaźnik na SuperMatrix).

Ogólna konwencja tworzenia stringa pod zbudowanie obiektu to

nazwa(arg1=val1, arg2=val2, ...)

Gdzie:
nazwa - identyfikator typu budowanego obiektu (np. noisektf dla filtru NoiseKTF)
arg - identyfikator argumentu (np. k dla parametru k w filtrze NoiseKTF)
val - wartość argumentu (liczba, true/false lub ciąg do sparsowania tworzący inny obiekt funkcyjny)

Niektóre obiekty poza wskaźnikiem na SuperMatrix i listą parametrów liczbowych/logicznych przyjmują również wskaźniki na inne obiekty funkcyjne (CompareFunction na filter, funkcję podobieństwa itd., funkcje podobieństwa oparte o RWF na RankBuilder). Konstruuje się je zagnieżdżając wywołania:

nazwa(arg1=val1, arg2=nazwa2(arg21=val21))


W razie powodzenia parsowania, wywołanie odpowiedniej metody FunctionFactory2 zwróci wskaźnik SharedPtr na obiekt funkcyjny. Możliwe (i rozróżnialne) błędy parsowania to:

- niepoprawny format wywołania ( inny niż nazwa(arg1=val1, arg2=val2, ...) )
- niepoprawny identyfikator typu obiektu funkcyjnego (np. nieznana nazwa filtru)
- niepoprawny argument dla danego typu obiektu funkcyjnego
- niepoprawna wartość argumentu (wyjątki boost lexical cast)
- brak wymaganego argumentu dla danego typu obiektu funkcyjnego

2. TWORZENIE OBIEKTÓW

Tworzenie obiektów funkcyjnych odbywa się przez wywołanie odpowiedniej metody Create, np. CreateFilter dla filtrów. 

2.1. COMPARE FUNCTIONS

Metoda: CreateComparator(string, SuperMatrixPtr)

Identyfikator: cmp
Argumenty:
weight 			- string	- string do sparsowania tworzący obiekt funkcyjny przeważający macierz
selector		- string	- j/w dla selektora
relative_selector	- string	- j/w dla selektora względnego
simfunction		- string	- j/w dla funkcji podobieństwa
filter			- string	- j/w dla filtra

2.2. FILTERS

Metoda: CreateFilter(string, SuperMatrixPtr)

2.2.1. FeatureFilter01

Identyfikator: feature01
Argumenty: 
k (size_t) - domyślnie 2

2.2.2 FilterVector

Identyfikator: vector
Argumenty:
filter (string) - obowizkowy (minimum 1), zawiera opis filtru

2.2.3. NoiseKFilter

Identyfikator: noisek
Argumenty: 
k (size_t) - obowiązkowy

2.2.4. NoiseKTFFilter

Identyfikator: noisektf
Argumenty:
k (size_t) - obowiązkowy
mintf (size_t) - domyślnie 2

2.3. WEIGHTS

Metoda: CreateWeigher(string, SuperMatrixPtr)

2.3.1. CRMDt

Identyfikator: CRMDt
Argumenty: brak

2.3.2. CRmDmi

Identyfikator: CRmDmi
Argumenty: brak

2.3.3. LogEntNormalize

Identyfikator: logent_normalize
Argumenty:
useFilteredEntropy (bool) - domyślnie false

2.3.4. LogEnt

Identyfikator: logent
Argumenty:
useFilteredEntropy (bool) - domyślnie false

2.3.5. MIWeight

Identyfikator: MI
Argumenty: 
miFilter (double) - domyślnie 0

2.3.6. MIWeightQuantified

Identyfikator: MI_quant
Argumenty:
miFilter (double) - domyślnie 0
trail (int) - domyślnie 2
include_zeros (bool) - domyślnie false

2.3.7. MLEWeightFeature

Identyfikator: MLE
Argumenty: brak

2.3.8. NormalizeWeight

Identyfikator: normalize
Argumenty: brak

2.3.9. RFFWeight

Idenfytikator: rff
Argumenty: 
simmatrix (string) - obowiązkowy - ścieżka do pliku crs macierzy
top_k (size_t) - obowiązkowy
sim_threshold (double) - obowiązkowy
selector (string) - obowiązkowy - string zawierający opis selektora RFF (patrz 2.10.)

2.3.10. RWFChi2

Identyfikator: rwf_chi2
Argumenty:
rankbuilder (string) - obowiązkowy - string zawierający opis RankBuildera (patrz 2.8.)
threshold (double) - domyślnie 0

2.3.11. RWFEvertsMI

Identyfikator: rwf_evertsmi
Argumenty:
rankbuilder (string) - obowiązkowy - string zawierający opis RankBuildera (patrz 2.8.)
mi_threshold (double) - domyślnie 0 

2.3.12. RWFMILinFiltered

Identyfikator: rwf_lin_filtered
Argumenty:
rankbuilder (string) - obowiązkowy - string zawierający opis RankBuildera (patrz 2.8.)
threshold (double) - domyślnie 0

2.3.13. RWFLogLikelihood

Identyfikator: rwf_log
Argumenty:
rankbuilder (string) - obowiązkowy - string zawierający opis RankBuildera (patrz 2.8.)
threshold (double) - domyślnie 0

2.3.14. RWFNoWeight

Identyfikator: rwf_noweight
Argumenty:
rankbuilder (string) - obowiązkowy - string zawierający opis RankBuildera (patrz 2.8.)

2.3.15. RWFPMIWeight

Identyfikator: rwf_pmi
Argumenty:
rankbuilder (string) - obowiązkowy - string zawierający opis RankBuildera (patrz 2.8.)
discount (bool) - domyślnie true
threshold (double) - domyślnie 0 

2.3.16 RWFZScore

Identyfikator: rwf_zscore
Argumenty:
rankbuilder (string) - obowiązkowy - string zawierający opis RankBuildera (patrz 2.8.)
threshold (double) - domyślnie 2.57

2.3.17. SimpleMIWeight

Identyfikator: MI_simple
Argumenty:
discount (bool) - domyślnie true
mi_threshold (double) - domyślnie 0

2.3.18. TScoreWeight

Identyfikator: TScore
Argumenty: brak

2.3.19. TfidfNormalizeWeight

Identyfikator: Tfidf_normalize
Argumenty: brak

2.3.20. Tfidf

Identyfikator: Tfidf
Argumenty: brak

2.3.21. RowScaledWeight

Identyfikator: row_scaled
Argumenty: 
weight_inner (string) - obowiązkowy - string zawierający opis wagi

2.3.22. ColumnScaledWeight

Identyfikator: column_scaled
Argumenty: 
weight_inner (string) - obowiązkowy - string zawierający opis wagi

2.3.22. BoundaryScaledWeight

Identyfikator: boundary_scaled
Argumenty: 
weight_inner (string) - obowiązkowy - string zawierający opis wagi
AdjP (double) - domyślnie 0.8
AmISubj (double) - domyślnie 0.6
Coord (double) - domyślnie 0.8
NGen (double) - domyślnie 0.6

2.3.23. RWFAnyWeight

Identyfikator: rwf
Argumenty: 
weight_inner (string) - obowiązkowy - string zawierający opis wagi
rankbuilder (string) - obowiązkowy - string zawierający opis RankBuildera (patrz 2.8.)

2.3.24. QuantizationWeight
Identyfikator: quant
Argumenty:
weight_inner (string) - obowiązkowy - string zawierający opis wagi
trailing_digits (int) - domyślnie 2
zeros (bool) - domyślnie false

2.3.24. PMINoLog

Identyfikator: pmi_nolog
Argumenty:
discount (bool) - domyślnie true
mi_threshold (double) - domyślnie 0

2.4. SIMFUNCTIONS

Metoda: CreateSimfunction(string, SuperMatrixPtr)

2.4.1. CosineFilterSimilarity

Identyfikator: cosinefilter
Argumenty:
percentIter (double) - domyślnie 0.1
minIter (size_t) - domyślnie 2

2.4.2. CosineFunction

Identyfikator: cosine
Argumenty: 
matrixNormalized(bool) - domyślnie false

2.4.3. Dice

Identyfikator: dice
Argumenty: brak

2.4.4. EhlertSimilatiry

Identyfikator: ehlert
Argumenty: 
delta (double) - domyślnie 0.75
gamma (double) - domyślnie 0.75
alpha (double) - domyślnie 1.1

2.4.5. Jaccard

Identyfikator: jaccard
Argumenty: brak

2.4.6. LinSimilarity

Identyfikator: lin
Argumenty: brak

2.4.7. MCFSim

Identyfikator: mcf
Argumenty:
threshold (double) - domyślnie 0.14
weight (string) - obowiązkowy - string opisujący funkcję ważącą
sim_inner (string) - obowiązkowy - string opisujący simfunction

2.4.8. PEntP

Identyfikator: pentp
Argumenty: brak

2.4.9. SHD

Identyfikator: shd
Argumenty: alpha (double) - domyślnie 0.5

2.4.10. SimCRM

Identyfikator: crm
Argumenty: 
gamma (double) - domyślnie 0.25
beta (double) - domyślnie 0.2

2.4.11. filesimfunction

Identyfikator: filesim
Argumenty:
sim_matrix (string) - obowiązkowy

2.4.12. DistanceSim

Identyfikator: distancesim
Argumenty:
dist (string) - obowiązkowy - string opisujący distance function

2.4.13. RatioSim

Identyfikator: ratio
Argumenty: brak

2.5. SELECTORS

Metoda: CreateSelector(string, SuperMatrixPtr)

2.5.1. FrequencySelector

Identyfikator: frequency
Argumenty:
min_nz (size_t) - domyślnie 5
min_tf (size_t) - domyślnie 5
min_TF (size_t) - domyślnie 5

2.5.2. TScoreSelector

Identyfikator: TScore
Argumenty:
threshold (double) - domyślnie 2.576

2.5.3. TScoreKBestSelector

Identyfikator: TScoreKBest
Argumenty:
threshold (double) - domyślnie 2.576
k (size_t) - domyślnie 350

2.5.4. RFFSelector

Identyfikator: RFF
Argumenty:
TFThreshold (double) - obowiązkowy
weightThreshold (double) - obowiązkowy

2.6. ROW RELATIVE SELECTORS

Metoda: CreateRowRelativeSelector(string, SuperMatrixPtr)

2.6.1. RelativeTScoreKBestSelector

Identyfikator: TScoreKBest
Argumenty:
tscore_threshold (double) - obowiązkowy

2.7. LOCAL SIMFUNCTIONS

Metoda: CreateLocalSimfunction(string)

2.7.1. LocalCosineSimilarity

Identyfikator: local_cosine
Argumenty:
isNormalized (bool) - obowiązkowy
doFilter (bool) - obowiązkowy
percentInter (double) - domyślnie 0.1
minInter (size_t) - domyślnie 2

2.7.2. IRad

Identyfikator: irad
Argumenty:
beta (double) - domyślnie 20
weight - obowiązkowy - string opisujący funkcję ważącą

2.8. RANKBUILDERS

Metoda: CreateRankBuilder(string, SuperMatrixPtr)

2.8.1. NormalRankBuilder

Identyfikator: normal
Argumenty:
uniform_rank (bool) - domyślnie false
rank_size (size_t) - domyślnie 350

2.8.2. PartialOrderRankBuilder

Identyfikator: partial
Argumenty:
uniform_rank (bool) - domyślnie false
rank_size (size_t) - domyślnie 350
sport_ranking (bool) - domyślnie false
idf (bool) - domyślnie false
idf_strength (double) - domyślnie 1.0

2.8.3. RoundingBasedPartialOrder

Identyfikator: rounding\_partial
Argumenty:
uniform_rank (bool) - domyślnie false
rank_size (size_t) - domyślnie 350
sport_ranking (bool) - domyślnie false
idf (bool) - domyślnie false
idf_strength (double) - domyślnie 1.0
divide_factor (double) - domyślnie 10.0

2.9. LOCAL WEIGHERS

Metoda: CreateLocalWeigher(string)

2.9.1. LocalLogEntWeight

Identyfikator: logent
Argumenty: 
useFilteredEntropy (bool) - domyślnie false

2.10 RFF SELECTORS 

Metoda: CreateRFFSelector (string, SuperMatrixPtr)

2.10.0. RFFSelector

Identyfikator: RFF
Argumenty:
TFThreshold (double) - obowiązkowy
weightThreshold (double) - obowiązkowy

2.11 DISTANCE FUNCTIONS

Metoda: CreateDistFunction(string, SuperMatrixPtr)

2.11.1. EuclidianDist

Identyfikator: euclid
Argumenty: brak

2.11.2. MinkowskiDist

Identyfikator: minkowski
Argumenty: 
p (double) - domyślnie 2

3. ROZBUDOWA I SZCZEGÓŁY IMPLEMENTACYJNE

3.1. ARCHITEKTURA FUNCTION FACTORY 2

W celu tworzenia obiektów funkcyjnych Function Factory 2 udostępnia szereg publicznych metod opisanych dokładniej w sekcji 2. Najważniejsze chronione metody i komponenty klasy to:

3.1.1. mapa dozwolonych argumentów dla poszczególnych klas
3.1.2. mapa wskaźników funkcyjnych do metod parsujących zwracających konkretne obiekty
3.1.3. metody inicjujące parser danej konkretnej klasy (np. konkretnego filtru)
3.1.4. metody inicjujące parsery dla danej klasy abstrakcyjnej (np. wszystkich filtrów)
3.1.5. metody parsujące opisy konkretnej klasy (np. konkretnego filtru)

3.1.1. mapa dozwolonych argumentów dla poszczególnych klas

Jest to mapa postaci string -> vector<string>. Filtry, funkcje podobieństwa itd. mają osobne mapy, np. legal_filter_args dla filtrów. Mapa inicjowana jest przez metody opisane w 3.1.3. Przykładowe wpisy w mapie:

"cosine" -> ["matrixNormalized"]
"cosinefilter" -> ["percentInter", "minInter"]
"dice" -> []

3.1.2. mapa wskaźników funkcyjnych do metod parsujących zwracających konkretne obiekty

Jest to mapa postaci string -> boost::function (nagłówek funkcji zależny od klasy, którą mapa opisuje - lokalne wagi i funkcje podobieństwa nie potrzebują macierzy, reszta - tak). Przypisuje konkretnemu identyfikatorowi w ramach danej klasy metodę, która przeparsuje argumenty i zwróci pożądany obiekt.  Filtry, funkcje podobieństwa itd. mają osobne mapy, np. filter_functions dla filtrów. Mapa inicjowana jest przez metody opisane w 3.1.3. Przykładowy wpisy w mapie:

"cosine" -> &smartcomparator::compare::FunctionFactory2::CreateSimfunctionCosine
"cosinefilter" -> &smartcomparator::compare::FunctionFactory2::CreateSimfunctionCosineFilter
"dice" -> &smartcomparator::compare::FunctionFactory2::CreateSimfunctionDice

3.1.3. metody inicjujące parser danej konkretnej klasy (np. konkretnego filtru)

W ramach tej metody dokonywane są wpisy do map opisanych w 3.1.1. i 3.1.2. dotyczące konkretnej parsowanej klasy.

3.1.4. metody inicjujące parsery dla danej klasy abstrakcyjnej (np. wszystkich filtrów)

Metody te są wywoływane przez konstruktor FunctionFactory2. Zawierają wywołania metod opisanych w 3.1.3. 

3.1.5. metody parsujące opisy konkretnej klasy (np. konkretnego filtru)

Są to metody, na które wskazują wpisy w mapach opisanych w 3.1.2. Dokonują parsowania pojedynczych argumentów, wywołują konstruktor pożądanej klasy i zwracają wskaźnik na żądany obiekt. Zawierają też informacje o opcjonalności/obligatoryjności poszczególnych argumentów (opcjonalne są inicjowane wartością domyślną). 

3.2. ROZBUDOWA O NOWE KLASY

Aby dołączyć parsowanie nowo utworzonej klasy obiektów funkcyjnych, należy podjąć następujące kroki:

3.2.1. Stworzenie metody parsującej klasę (patrz: 3.1.5.)
3.2.2. Stworzenie metody inicjalizującej parser klasy (patrz: 3.1.3.)
3.2.3. Dodanie wywołania metody stworzonej w 3.2.1. do metody inicjalizującej klasę parserów (patrz: 3.1.4.)

PRZYKŁAD

Załóżmy, że chcemy dodać obsługę klasy FoobarFilter do Function Factory 2. Filtr FoobarFilter przyjmuje dwa argumenty:
foo (bool) - opcjonalny (domyślnie false)
bar (double) - obowiązkowy

Krok 3.2.1.

filters::FilterFeaturePtr FunctionFactory2::CreateFilterFoobar(std::map<std::string, std::string> & args,
								   Matrices::SuperMatrixPtr matrix)
{
		bool foo = false; //inicjalizacja zmiennej opcjonalnej
		double bar; //inicjalizacja zmiennej obowiazkowej
		if (args.find("foo") != args.end()) //sprawdzenie czy argument wystepuje w mapie argumentow (tworzona przez wywolujaca ta metode CreateFilter)
			GetBool2(args, "mintf", mintf); //przypisanie wartosci argumentowi logicznemu
		if (args.find("bar") != args.end())
			GetNumber2(args, "bar", bar); //przypisanie wartosci argumentowi double
		else
			throw std::runtime_error("Foobar filter missing required argument: bar"); //wyjatek w razie braku obowiazkowego argumentu
		return filters::FilterFeaturePtr(new filters::FoobarFilter(matrix->GetColumnFeatures(), foo, bar)); //wywolanie konstruktora i zwrocenie wskaznika
}

Krok 3.2.2.

void FunctionFactory2::initFilterFoobar()
{
    std::vector<std::string> args; //inicjalizacja wektora dozwolonych argumentow
    args.push_back("foo");
    args.push_back("bar"); //wypelnienie wektora dozwolonych argumentow
    legal_filter_args["foobar"] = args; //przypisanie wektora dozwolonych argumentow identyfikatorowi
    filter_functions["foobar"] = &smartcomparator::compare::FunctionFactory2::CreateFilterFoobar; //przypisanie metody parsujacej identyfikatorowi
}

Krok 3.2.2.

void FunctionFactory2::initFilters() //ta metoda juz istnieje
{
	initFilterFeature01();
	initFilterVector();
	initNoiseKFilter();
	initNoiseKTFFilter();
	//powyzej tego miejsca inicjalizowane sa inne filtry
	initFilterFoobar(); //wywolanie, ktore nalezy dodac (kolejnosc nieistotna)
}
