Simplify handling of subject's age

lirical-core/src/main/java/org/monarchinitiative/lirical/core/LiricalOptions.java

@@ -3,7 +3,9 @@
 import java.util.Optional;
 
 /**
- * Options of the LIRICAL process that live independent of the analyses.
+ * Global options to parameterize LIRICAL execution.
+ * <p>
+ * Note, these options do <em>not</em> parameterize the analyses.
  */
 public class LiricalOptions {
 

lirical-core/src/main/java/org/monarchinitiative/lirical/core/analysis/AnalysisData.java

@@ -9,43 +9,70 @@
 
 import java.util.Collection;
 import java.util.List;
-import java.util.Objects;
+import java.util.Optional;
 
 /**
- * An interface for representing proband data.
+ * Representation of subject data required by LIRICAL analysis.
  */
 public interface AnalysisData {
 
+    /**
+     * Construct analysis data from the inputs.
+     *
+     * @param sampleId non-null sample identifier.
+     * @param age subject's age or {@code null} if not available.
+     * @param sex non-null sex.
+     * @param presentPhenotypeTerms a collection of observed HPO terms.
+     * @param negatedPhenotypeTerms a collection of excluded HPO terms.
+     * @param genes non-null container of genes and genotypes.
+     */
     static AnalysisData of(String sampleId,
                            Age age,
                            Sex sex,
                            Collection<TermId> presentPhenotypeTerms,
                            Collection<TermId> negatedPhenotypeTerms,
                            GenesAndGenotypes genes) {
-        return new AnalysisDataDefault(Objects.requireNonNull(sampleId),
+        return new AnalysisDataDefault(sampleId,
                 age,
-                Objects.requireNonNull(sex),
-                List.copyOf(Objects.requireNonNull(presentPhenotypeTerms)),
-                List.copyOf(Objects.requireNonNull(negatedPhenotypeTerms)),
+                sex,
+                presentPhenotypeTerms,
+                negatedPhenotypeTerms,
                 genes);
     }
 
     /**
      * @return a non-null sample ID.
      */
+    @JsonGetter
     String sampleId();
 
-    // TODO - make non-null or wrap into Optional. See the TODO in Age for more info.
-    Age age();
+    /**
+     * @return an optional with age or empty optional if age is not available.
+     */
+    @JsonGetter
+    Optional<Age> age();
 
+    /**
+     * @return a non-null sex of the subject.
+     */
+    @JsonGetter(value = "sex")
     Sex sex();
 
+    /**
+     * @return a list of the HPO terms that were observed in the subject.
+     */
     @JsonGetter(value = "observedPhenotypicFeatures")
     List<TermId> presentPhenotypeTerms();
 
+    /**
+     * @return a list of the HPO terms whose presence was explicitly excluded in the subject.
+     */
     @JsonGetter(value = "excludedPhenotypicFeatures")
     List<TermId> negatedPhenotypeTerms();
 
+    /**
+     * @return container with genes and genotypes observed in the subject.
+     */
     @JsonIgnore
     GenesAndGenotypes genes();
 

lirical-core/src/main/java/org/monarchinitiative/lirical/core/analysis/AnalysisDataDefault.java

@@ -1,19 +1,97 @@
 package org.monarchinitiative.lirical.core.analysis;
 
-import org.monarchinitiative.lirical.core.model.GenesAndGenotypes;
 import org.monarchinitiative.lirical.core.model.Age;
+import org.monarchinitiative.lirical.core.model.GenesAndGenotypes;
 import org.monarchinitiative.lirical.core.model.Sex;
 import org.monarchinitiative.phenol.ontology.data.TermId;
 
+import java.util.Collection;
 import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
 
 /**
  * Default implementation of {@link AnalysisData}.
  */
-record AnalysisDataDefault(String sampleId,
-                           Age age,
-                           Sex sex,
-                           List<TermId> presentPhenotypeTerms,
-                           List<TermId> negatedPhenotypeTerms,
-                           GenesAndGenotypes genes) implements AnalysisData {
+final class AnalysisDataDefault implements AnalysisData {
+    private final String sampleId;
+    private final Age age;
+    private final Sex sex;
+    private final List<TermId> presentPhenotypeTerms;
+    private final List<TermId> negatedPhenotypeTerms;
+    private final GenesAndGenotypes genes;
+
+    AnalysisDataDefault(String sampleId,
+                        Age age,
+                        Sex sex,
+                        Collection<TermId> presentPhenotypeTerms,
+                        Collection<TermId> negatedPhenotypeTerms,
+                        GenesAndGenotypes genes) {
+        this.sampleId = Objects.requireNonNull(sampleId);
+        this.age = age;
+        this.sex = Objects.requireNonNull(sex);
+        this.presentPhenotypeTerms = List.copyOf(Objects.requireNonNull(presentPhenotypeTerms));
+        this.negatedPhenotypeTerms = List.copyOf(Objects.requireNonNull(negatedPhenotypeTerms));
+        this.genes = Objects.requireNonNull(genes);
+    }
+
+    @Override
+    public String sampleId() {
+        return sampleId;
+    }
+
+    @Override
+    public Optional<Age> age() {
+        return Optional.ofNullable(age);
+    }
+
+    @Override
+    public Sex sex() {
+        return sex;
+    }
+
+    @Override
+    public List<TermId> presentPhenotypeTerms() {
+        return presentPhenotypeTerms;
+    }
+
+    @Override
+    public List<TermId> negatedPhenotypeTerms() {
+        return negatedPhenotypeTerms;
+    }
+
+    @Override
+    public GenesAndGenotypes genes() {
+        return genes;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj == this) return true;
+        if (obj == null || obj.getClass() != this.getClass()) return false;
+        var that = (AnalysisDataDefault) obj;
+        return Objects.equals(this.sampleId, that.sampleId) &&
+                Objects.equals(this.age, that.age) &&
+                Objects.equals(this.sex, that.sex) &&
+                Objects.equals(this.presentPhenotypeTerms, that.presentPhenotypeTerms) &&
+                Objects.equals(this.negatedPhenotypeTerms, that.negatedPhenotypeTerms) &&
+                Objects.equals(this.genes, that.genes);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(sampleId, age, sex, presentPhenotypeTerms, negatedPhenotypeTerms, genes);
+    }
+
+    @Override
+    public String toString() {
+        return "AnalysisDataDefault[" +
+                "sampleId=" + sampleId + ", " +
+                "age=" + age + ", " +
+                "sex=" + sex + ", " +
+                "presentPhenotypeTerms=" + presentPhenotypeTerms + ", " +
+                "negatedPhenotypeTerms=" + negatedPhenotypeTerms + ", " +
+                "genes=" + genes + ']';
+    }
+
 }

lirical-core/src/main/java/org/monarchinitiative/lirical/core/analysis/AnalysisDataParser.java

@@ -5,6 +5,7 @@
 
 import java.io.InputStream;
 
+// REMOVE(v2.0.0)
 @Deprecated(forRemoval = true)
 public interface AnalysisDataParser {
 

lirical-core/src/main/java/org/monarchinitiative/lirical/core/analysis/LiricalParseException.java

@@ -5,6 +5,7 @@
 /**
  * An exception thrown when user-provided input is invalid.
  */
+// TODO - move to CLI after removing AnalysisDataParser.
 public class LiricalParseException extends LiricalException {
 
     public LiricalParseException() {

lirical-core/src/main/java/org/monarchinitiative/lirical/core/analysis/impl/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Default LIRICAL analysis implementation.
+ */
+package org.monarchinitiative.lirical.core.analysis.impl;

lirical-core/src/main/java/org/monarchinitiative/lirical/core/analysis/package-info.java

@@ -1,4 +1,11 @@
 /**
- * Classes for coordinating the main Lirical analysis goals.
+ * A high-level representation of LIRICAL analysis.
+ * <p>
+ * The analysis subject is provided as {@link org.monarchinitiative.lirical.core.analysis.AnalysisData}. The analysis
+ * is parameterized by {@link org.monarchinitiative.lirical.core.analysis.AnalysisOptions}.
+ * {@link org.monarchinitiative.lirical.core.analysis.LiricalAnalysisRunner} executes the analysis. The output
+ * are wrapped into {@link org.monarchinitiative.lirical.core.analysis.AnalysisResults} which reports results
+ * of matching the subject to computational disease models,
+ * one {@link org.monarchinitiative.lirical.core.analysis.TestResult} per disease.
  */
 package org.monarchinitiative.lirical.core.analysis;

lirical-core/src/main/java/org/monarchinitiative/lirical/core/analysis/probability/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Model of pretest probability of diseases.
+ */
+package org.monarchinitiative.lirical.core.analysis.probability;

lirical-core/src/main/java/org/monarchinitiative/lirical/core/exception/LiricalAnalysisException.java

@@ -3,7 +3,10 @@
 /**
  * An exception thrown by {@link org.monarchinitiative.lirical.core.analysis.LiricalAnalysisRunner} if the analysis
  * cannot be run.
+ * @deprecated will be moved into {@link org.monarchinitiative.lirical.core.analysis} package.
  */
+// TODO - move to analysis package.
+@Deprecated(forRemoval = true)
 public class LiricalAnalysisException extends LiricalException {
     public LiricalAnalysisException() {
         super();

lirical-core/src/main/java/org/monarchinitiative/lirical/core/exception/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Top-level exceptions.
+ */
+package org.monarchinitiative.lirical.core.exception;

lirical-core/src/main/java/org/monarchinitiative/lirical/core/io/package-info.java

@@ -0,0 +1,14 @@
+/**
+ * APIs for reading and annotation of genomic variants.
+ * <p>
+ * LIRICAL needs to read genomic variants, perform functional annotation, and fetch variant frequencies for the variants.
+ * LIRICAL does not care about how this is done, as long as the variants meet
+ * the {@link org.monarchinitiative.lirical.core.model.LiricalVariant} requirements.
+ * <p>
+ * One way to configure the functional annotation is to implement {@link org.monarchinitiative.lirical.core.io.VariantParserFactory}
+ * which can provide a {@link org.monarchinitiative.lirical.core.io.VariantParser} to read variants
+ * from a {@link java.nio.file.Path} given {@link org.monarchinitiative.lirical.core.model.GenomeBuild}
+ * and {@link org.monarchinitiative.lirical.core.model.TranscriptDatabase}. For instance, to read variants
+ * from a VCF file.
+ */
+package org.monarchinitiative.lirical.core.io;

lirical-core/src/main/java/org/monarchinitiative/lirical/core/likelihoodratio/package-info.java

@@ -1,4 +1,6 @@
-/** Classes related to the calculation of likelihood ratios for phenotypic or genotypic test results.
+/**
+ * Package with logic for calculation of likelihood ratios for phenotypic or genotypic test results.
+ *
  * @author <a href="mailto:[email protected]">Peter Robinson</a>
  */
 package org.monarchinitiative.lirical.core.likelihoodratio;