Docs for multi-color stuff

Author: hombit

src/multicolor/features/color_of_maximum.rs

@@ -11,6 +11,10 @@ pub use serde::{Deserialize, Serialize};
 use std::collections::BTreeSet;
 use std::fmt::Debug;
 
+/// Difference maximum value magnitudes of two passbands
+///
+/// Note that maximum is calculated for each passband separately, and maximum has mathematical
+/// meaning, not "magnitudial" (astronomical) one.
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(bound(deserialize = "P: PassbandTrait + Deserialize<'de>"))]
 pub struct ColorOfMaximum<P>
@@ -27,6 +31,10 @@ impl<P> ColorOfMaximum<P>
 where
     P: PassbandTrait,
 {
+    /// Create new [ColorOfMaximum] evaluator
+    ///
+    /// # Arguments
+    /// - `passbands` - two passbands
     pub fn new(passbands: [P; 2]) -> Self {
         let set: BTreeSet<_> = passbands.clone().into();
         Self {

src/multicolor/features/color_of_median.rs

@@ -14,6 +14,9 @@ pub use serde::{Deserialize, Serialize};
 use std::collections::BTreeSet;
 use std::fmt::Debug;
 
+/// Difference of median magnitudes in two passbands
+///
+/// Note that median is calculated for each passband separately
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(bound(deserialize = "P: PassbandTrait + Deserialize<'de>"))]
 pub struct ColorOfMedian<P>

src/multicolor/features/color_of_minimum.rs

@@ -11,6 +11,10 @@ pub use serde::{Deserialize, Serialize};
 use std::collections::BTreeSet;
 use std::fmt::Debug;
 
+/// Difference of minimum magnitudes of two passbands
+///
+/// Note that minimum is calculated for each passband separately, and maximum has mathematical
+/// meaning, not "magnitudial" (astronomical) one.
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(bound(deserialize = "P: PassbandTrait + Deserialize<'de>"))]
 pub struct ColorOfMinimum<P>
@@ -27,6 +31,10 @@ impl<P> ColorOfMinimum<P>
 where
     P: PassbandTrait,
 {
+    /// Create new [ColorOfMinimum] evaluator
+    ///
+    /// # Arguments
+    /// - `passbands` - two passbands
     pub fn new(passbands: [P; 2]) -> Self {
         let set: BTreeSet<_> = passbands.clone().into();
         Self {

src/multicolor/features/multi_color_periodogram.rs

@@ -4,17 +4,16 @@ use crate::evaluator::TmArrays;
 use crate::evaluator::{
     EvaluatorInfo, EvaluatorInfoTrait, FeatureEvaluator, FeatureNamesDescriptionsTrait, OwnedArrays,
 };
-
 use crate::features::{Periodogram, PeriodogramPeaks};
 use crate::float_trait::Float;
 use crate::multicolor::multicolor_evaluator::*;
 use crate::multicolor::{PassbandSet, PassbandTrait};
 use crate::periodogram::{self, NyquistFreq, PeriodogramPower};
 
 use ndarray::Array1;
-
 use std::fmt::Debug;
 
+/// Multi-passband periodogram
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(
     bound = "T: Float, F: FeatureEvaluator<T> + From<PeriodogramPeaks> + TryInto<PeriodogramPeaks>, <F as TryInto<PeriodogramPeaks>>::Error: Debug,"

src/multicolor/monochrome_feature.rs

@@ -15,6 +15,7 @@ use std::collections::BTreeSet;
 use std::fmt::Debug;
 use std::marker::PhantomData;
 
+/// Multi-color feature which evaluates non-color dependent feature for each passband.
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(bound(
     deserialize = "P: PassbandTrait + Deserialize<'de>, T: Float, F: FeatureEvaluator<T>"
@@ -35,6 +36,11 @@ where
     T: Float,
     F: FeatureEvaluator<T>,
 {
+    /// Creates a new instance of `MonochromeFeature`.
+    ///
+    /// # Arguments
+    /// - `feature` - non-multi-color feature to evaluate for each passband.
+    /// - `passband_set` - set of passbands to evaluate the feature for.
     pub fn new(feature: F, passband_set: BTreeSet<P>) -> Self {
         let names = passband_set
             .iter()
@@ -130,3 +136,32 @@ where
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::features::Mean;
+    use crate::multicolor::passband::MonochromePassband;
+    use crate::Feature;
+
+    #[test]
+    fn test_monochrome_feature() {
+        let feature: MonochromeFeature<MonochromePassband<_>, f64, Feature<_>> =
+            MonochromeFeature::new(
+                Mean::default().into(),
+                [
+                    MonochromePassband::new(4700e-8, "g"),
+                    MonochromePassband::new(6200e-8, "r"),
+                ]
+                .into_iter()
+                .collect(),
+            );
+        assert_eq!(feature.get_names(), vec!["mean_g", "mean_r"]);
+        assert_eq!(
+            feature.get_descriptions(),
+            vec!["mean magnitude, passband g", "mean magnitude, passband r"]
+        );
+        assert_eq!(feature.get_info().size, 2);
+    }
+}

src/multicolor/multicolor_evaluator.rs

@@ -16,22 +16,30 @@ pub use serde::{Deserialize, Serialize};
 use std::collections::BTreeSet;
 use std::fmt::Debug;
 
+/// Trait for getting alphabetically sorted passbands
 #[enum_dispatch]
 pub trait MultiColorPassbandSetTrait<P>
 where
     P: PassbandTrait,
 {
+    /// Get passband set for this evaluator
     fn get_passband_set(&self) -> &PassbandSet<P>;
 }
 
+/// Enum for passband set, which can be either fixed set or all available passbands.
+/// This is used for [MultiColorEvaluator]s, which can be evaluated on all available passbands
+/// (for example [MultiColorPeriodogram](super::features::MultiColorPeriodogram)) or on fixed set of
+/// passbands (for example [ColorOfMaximum](super::ColorOfMaximum)).
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(bound(deserialize = "P: PassbandTrait + Deserialize<'de>"))]
 #[non_exhaustive]
 pub enum PassbandSet<P>
 where
     P: Ord,
 {
+    /// Fixed set of passbands
     FixedSet(BTreeSet<P>),
+    /// All available passbands
     AllAvailable,
 }
 
@@ -44,6 +52,7 @@ where
     }
 }
 
+/// Helper error for [MultiColorEvaluator]
 enum InternalMctsError {
     MultiColorEvaluatorError(MultiColorEvaluatorError),
     InternalWrongPassbandSet,
@@ -78,6 +87,7 @@ impl InternalMctsError {
     }
 }
 
+/// Trait for multi-color feature evaluators
 #[enum_dispatch]
 pub trait MultiColorEvaluator<P, T>:
     FeatureNamesDescriptionsTrait

src/multicolor/multicolor_extractor.rs

@@ -12,6 +12,7 @@ use std::collections::BTreeSet;
 use std::fmt::Debug;
 use std::marker::PhantomData;
 
+/// Bulk feature evaluator.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 #[serde(
     into = "MultiColorExtractorParameters<MCF>",
@@ -37,6 +38,10 @@ where
     T: Float,
     MCF: MultiColorEvaluator<P, T>,
 {
+    /// Create a new [MultiColorExtractor]
+    ///
+    /// # Arguments
+    /// `features` - A vector of multi-color features to be evaluated
     pub fn new(features: Vec<MCF>) -> Self {
         let passband_set = {
             let set: BTreeSet<_> = features

src/multicolor/passband/dump_passband.rs

@@ -4,6 +4,7 @@ pub use schemars::JsonSchema;
 pub use serde::{Deserialize, Serialize};
 use std::fmt::Debug;
 
+/// A passband for the cases where we don't care about the actual passband.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema)]
 pub struct DumpPassband {}
 
@@ -12,3 +13,14 @@ impl PassbandTrait for DumpPassband {
         ""
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_dump_passband() {
+        let passband = DumpPassband {};
+        assert_eq!(passband.name(), "");
+    }
+}

src/multicolor/passband/monochrome_passband.rs

@@ -7,6 +7,7 @@ pub use serde::{Deserialize, Serialize};
 use std::cmp::Ordering;
 use std::fmt::Debug;
 
+/// A passband specified by a single wavelength.
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 pub struct MonochromePassband<'a, T> {
     pub name: &'a str,
@@ -17,6 +18,11 @@ impl<'a, T> MonochromePassband<'a, T>
 where
     T: Float,
 {
+    /// Create a new `MonochromePassband`.
+    ///
+    /// # Arguments
+    /// - `wavelength`: The wavelength of the passband, panic if it is not a positive normal number.
+    /// - `name`: The name of the passband.
     pub fn new(wavelength: T, name: &'a str) -> Self {
         assert!(
             wavelength.is_normal(),
@@ -67,3 +73,15 @@ where
         self.name
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_monochrome_passband() {
+        let passband = MonochromePassband::new(1.0, "test");
+        assert_eq!(passband.name(), "test");
+        assert_eq!(passband.wavelength, 1.0);
+    }
+}