riser 1.1.0__py3-none-any.whl

riser/__init__.py

@@ -0,0 +1,63 @@
+# src/riser/__init__.py
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2025 Rob Zinke. Licensed under the MIT License.
+
+"""
+RISeR2: Rejection sampling for Incremental Slip Rate calculation.
+"""
+
+from importlib.metadata import version as _version
+
+
+__version__ = _version("riser")
+
+
+# Core modules (no internal dependency)
+from . import (  # noqa: I001
+    constants,
+    integration,
+    precision,
+    units,
+    variable_types,
+)
+
+
+# Subpackages (imported in dependency order)
+from . import (
+    probability_functions,
+    variable_functions,
+    variable_pairs,
+    sampling,
+    slip_rates,
+    plotting,
+)
+
+
+# Commonly used classes
+from .probability_functions import PDF
+from .variable_pairs import DatedMarker, VariablePair
+
+
+# Public API
+__all__ = [
+    # Core modules and subpackages
+    "constants",
+    "integration",
+    "precision",
+    "units",
+    "variable_types",
+    "probability_functions",
+    "variable_functions",
+    "sampling",
+    "variable_pairs",
+    "slip_rates",
+    "plotting",
+    # Commonly used classes
+    "PDF",
+    "VariablePair",
+    "DatedMarker",
+]
+
+
+# end of file

riser/cli/__init__.py

@@ -0,0 +1,11 @@
+# src/riser/cli/__init__.py
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2025 Rob Zinke. Licensed under the MIT License.
+
+"""
+Command Line Interface tools live here.
+"""
+
+
+# end of file

riser/cli/add_variables.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2025 Rob Zinke. Licensed under the MIT License.
+
+
+# Import modules
+import argparse
+
+import matplotlib.pyplot as plt
+
+from riser import (
+    plotting,
+    probability_functions as PDFs,
+    variable_functions as var_fcns,
+)
+
+
+#################### ARGUMENT PARSER ####################
+description = "Add two random variables expressed as PDFs."
+
+examples = """Examples:
+add_variables.py pdf1.txt pdf2.txt -o pdf12.txt
+"""
+
+def create_parser():
+    parser = argparse.ArgumentParser(
+        description=description,
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog=examples,
+    )
+
+    return parser
+
+def cmd_parser(iargs=None):
+    parser = create_parser()
+
+    input_args = parser.add_argument_group("Inputs")
+    input_args.add_argument(dest="fname1",
+        type=str,
+        help="File name of first PDF.")
+    input_args.add_argument(dest="fname2",
+        type=str,
+        help="File name of second PDF.")
+
+    input_args.add_argument("--name", dest="name",
+        type=str,
+        help="Name of summed PDF. [None]")
+
+    output_args = parser.add_argument_group("Outputs")
+    output_args.add_argument("-o", "--outname", dest="outname",
+        type=str, required=True,
+        help="Output file.")
+    output_args.add_argument("-v", "--verbose", dest="verbose",
+        action="store_true",
+        help="Verbose mode.")
+    output_args.add_argument("-p", "--plot", dest="plot",
+        action="store_true",
+        help="Plot distribution.")
+
+    return parser.parse_args(args=iargs)
+
+
+#################### MAIN ####################
+def main() -> None:
+    # Parse arguments
+    inps = cmd_parser()
+
+    # Read PDFs from files
+    pdf1 = PDFs.readers.read_pdf(inps.fname1, verbose=inps.verbose)
+    pdf2 = PDFs.readers.read_pdf(inps.fname2, verbose=inps.verbose)
+
+    # Sample PDFs on same axis
+    pdf1, pdf2 = PDFs.interpolation.interpolate_pdfs(
+        [pdf1, pdf2], verbose=inps.verbose
+    )
+
+    # Compute summed PDF
+    sum_pdf = var_fcns.transform.arithmetic.add_variables(
+        pdf1, pdf2, name=inps.name, verbose=inps.verbose
+    )
+
+    # Save to file
+    PDFs.readers.save_pdf(inps.outname, sum_pdf, verbose=inps.verbose)
+
+    # Plot function if requested
+    if inps.plot:
+        # Initialize figure and axis
+        fig, (inpt_ax, sum_ax) = plt.subplots(nrows=2)
+
+        # Plot input PDFs
+        plotting.plot_pdf_filled(inpt_ax, pdf1)
+        plotting.plot_pdf_filled(inpt_ax, pdf2)
+
+        # Plot PDF
+        plotting.plot_pdf_labeled(sum_ax, sum_pdf)
+
+        # Format figure
+        inpt_ax.legend()
+        inpt_ax.set_title("Inputs")
+        sum_ax.set_title("Summed PDF")
+        fig.tight_layout()
+
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()
+
+
+# end of file

riser/cli/calyr_to_age.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2025 Rob Zinke. Licensed under the MIT License.
+
+
+# Import modules
+import argparse
+
+import matplotlib.pyplot as plt
+
+from riser import (
+    plotting,
+    probability_functions as PDFs,
+    sampling,
+    units,
+)
+
+
+#################### ARGUMENT PARSER ####################
+description = (
+    "Convert an age PDF from calendar years to (kilo)years before present."
+)
+
+examples = """Examples:
+riser-calyr-to-age C_date.txt -o C_age.txt
+riser-calyr-to-age C_date.txt --name C14 --smoothing-type mean --smoothing-width 3 -v -p -o C_age.txt
+"""
+
+def create_parser():
+    parser = argparse.ArgumentParser(
+        description=description,
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog=examples,
+    )
+
+    return parser
+
+def cmd_parser(iargs=None):
+    parser = create_parser()
+
+    input_args = parser.add_argument_group("Inputs")
+    input_args.add_argument(dest="date_fname",
+        type=str,
+        help="Calendar years file name.")
+
+    # Metadata
+    metadata_args = parser.add_argument_group("Metadata")
+    metadata_args.add_argument("--name", dest="name",
+        type=str,
+        help="Name.")
+    metadata_args.add_argument("--variable-type", dest="variable_type",
+        type=str, default="age",
+        help="Variable type. [age]")
+
+    # Referencing
+    referencing_args = parser.add_argument_group("Referencing")
+    referencing_args.add_argument("--reference-date", dest="reference_date",
+        type=float, default=1950,
+        help="Reference date, e.g., 1950 for radiocarbon, 2000 for OSL, etc. "
+             "[1950]")
+    referencing_args.add_argument("--limit-zero", dest="limit_zero",
+        action="store_true",
+        help="Limit youngest value to zero.")
+
+    # Units
+    unit_args = parser.add_argument_group("Units")
+    unit_args.add_argument("--input-unit", dest="input_unit",
+        type=str, default="y",
+        help="Unit of input data. [y]")
+    unit_args.add_argument("--output-unit", dest="output_unit",
+        type=str, default="ky",
+        help="Unit of output data. [ky]")
+
+    # Smoothing
+    smoothing_args = parser.add_argument_group("Smoothing")
+    smoothing_args.add_argument("--smoothing-type", dest="smoothing_type",
+        type=str, choices=sampling.filtering.FILTER_TYPES,
+        help="Smoothing filter type. [None]")
+    smoothing_args.add_argument("--smoothing-width", dest="smoothing_width",
+        type=int, default=0,
+        help="Smoothing kernel width. [0]")
+
+    # Outputs
+    output_args = parser.add_argument_group("Outputs")
+    output_args.add_argument("-o", "--outname", dest="outname",
+        type=str, required=True,
+        help="Output file.")
+    output_args.add_argument("-v", "--verbose", dest="verbose",
+        action="store_true",
+        help="Verbose mode.")
+    output_args.add_argument("-p", "--plot", dest="plot",
+        action="store_true",
+        help="Plot.")
+
+    return parser.parse_args(args=iargs)
+
+
+#################### MAIN ####################
+def main() -> None:
+    # Parse arguments
+    inps = cmd_parser()
+
+    # Read calendar years file
+    calyr, calpx, metadata = PDFs.readers.read_calendar_file(
+        fname=inps.date_fname,
+        name=inps.name,
+        variable_type=inps.variable_type,
+        unit=inps.input_unit,
+        verbose=inps.verbose,
+    )
+
+    # Convert calendar year to years before present (ypb)
+    if inps.verbose:
+        print(f"Shifting dates relative to reference: {inps.reference_date}")
+    ybp = inps.reference_date - calyr
+
+    # Scale from input units to output units
+    x = units.scale_values_by_units(
+        ybp, metadata["unit"], inps.output_unit, verbose=inps.verbose
+    )
+
+    # Flip left for right, so age is increasing
+    x = x[::-1]
+    px = calpx[::-1]
+
+    # Limit minimum age to zero
+    if inps.limit_zero:
+        # Non-negative indices
+        non_neg_ndx = (x >= 0)
+
+        # Crop arrays
+        x = x[non_neg_ndx]
+        px = px[non_neg_ndx]
+
+    # Form data into PDF
+    pdf = PDFs.PDF(
+        x=x,
+        px=px,
+        name=inps.name,
+        variable_type=inps.variable_type,
+        unit=inps.output_unit,
+    )
+
+    # Smooth data
+    if inps.smoothing_width > 0:
+        pdf = sampling.filtering.filter_pdf(
+            pdf=pdf,
+            filter_type=inps.smoothing_type,
+            filter_width=inps.smoothing_width,
+            edge_padding="zeros",
+            verbose=inps.verbose,
+        )
+
+    # Report final stats if requested
+    if inps.verbose:
+        PDFs.analytics.compute_pdf_statistics(pdf, verbose=True)
+
+    # Save to file
+    PDFs.readers.save_pdf(inps.outname, pdf, verbose=inps.verbose)
+
+    # Plot function if requested
+    if inps.plot:
+        # Initialize figure and axis
+        fig, (cal_ax, age_ax) = plt.subplots(nrows=2)
+
+        # Plot calendar years
+        cal_ax.plot(calyr, calpx, color="k")
+
+        # Plot PDF
+        plotting.plot_pdf_labeled(age_ax, pdf)
+
+        # Format plot
+        cal_ax.invert_xaxis()
+        cal_ax.set_xlabel("Calendar year (CE / BCE)")
+        cal_ax.set_ylabel("Probability density")
+
+        fig.tight_layout()
+
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()
+
+
+# end of file

riser/cli/compute_slip_rate.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2025 Rob Zinke. Licensed under the MIT License.
+
+
+# Import modules
+import argparse
+
+import matplotlib.pyplot as plt
+
+from riser import (
+    constants,
+    plotting,
+    probability_functions as PDFs,
+    variable_pairs,
+)
+from riser.slip_rates import rate_computation, reporting
+
+
+#################### ARGUMENT PARSER ####################
+description = (
+    "Compute the slip rate for a single marker by dividing feature "
+    "displacement by age, using the analytical formulation."
+)
+
+examples = """Examples:
+compute_slip_rate.py marker_config.toml -o v1
+compute_slip_rate.py marker_config.toml --age-unit-out y --displacement-unit-out mm -o v2/v2
+"""
+
+def create_parser():
+    parser = argparse.ArgumentParser(
+        description=description,
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog=examples,
+    )
+
+    return parser
+
+def cmd_parser(iargs=None):
+    parser = create_parser()
+
+    # Inputs
+    input_args = parser.add_argument_group("Inputs")
+    input_args.add_argument(dest="marker_config",
+        type=str,
+        help="Dated displacement marker configuration file.")
+
+    # Units
+    unit_args = parser.add_argument_group("Units")
+    unit_args.add_argument("--age-unit-out", dest="age_unit_out",
+        type=str,
+        help="Output age units.")
+    unit_args.add_argument(
+        "--displacement-unit-out", dest="displacement_unit_out",
+        type=str,
+        help="Output displacement units.")
+
+    # Slip rate
+    rate_args = parser.add_argument_group("Slip rates")
+    rate_args.add_argument("--limit-positive", dest="limit_positive",
+        action="store_true",
+        help="Enforce the condition that values are >= to 0.")
+    rate_args.add_argument("--max-rate", dest="max_rate",
+        type=float,
+        help="Maximum slip rate to consider.")
+    rate_args.add_argument("--dr", dest="dr",
+        type=float, default=0.01,
+        help="Slip rate step. [0.01]")
+
+    # Reporting
+    reporting_args = parser.add_argument_group("Reporting")
+    reporting_args.add_argument(
+        "--confidence-metric", dest="confidence_metric",
+        type=str, choices=PDFs.analytics.PDF_CONFIDENCE_METRICS,
+        default=PDFs.analytics.DEFAULT_CONFIDENCE_METRIC,
+        help=f"Function for computing function confidence. "
+             f"[{PDFs.analytics.DEFAULT_CONFIDENCE_METRIC}]")
+    reporting_args.add_argument(
+        "--confidence-limits", dest="confidence_limits",
+        type=float, default=constants.Psigma["1"],
+        help=f"Confidence level. [{constants.Psigma['1']:.2f}]")
+
+    # Outputs
+    output_args = parser.add_argument_group("Outputs")
+    output_args.add_argument("-o", "--output-prefix", dest="output_prefix",
+        type=str, required=True,
+        help="Output prefix as <prefix> or <folder>/<prefix>.")
+    output_args.add_argument("-v", "--verbose", dest="verbose",
+        action="store_true",
+        help="Verbose mode.")
+    output_args.add_argument("-p", "--plot", dest="plot",
+        action="store_true",
+        help="Show results plots. Figures will be generated and saved "
+             "whether plot flag is raised.")
+
+    return parser.parse_args(args=iargs)
+
+
+#################### MAIN ####################
+def main() -> None:
+    # Parse arguments
+    inps = cmd_parser()
+
+    # Establish output directory
+    reporting.establish_output_dir(inps.output_prefix, verbose=inps.verbose)
+
+    # Read markers
+    markers = variable_pairs.readers.read_dated_markers_from_config(
+        inps.marker_config, verbose=inps.verbose
+    )
+
+    # Check that only one marker is specified
+    if len(markers) > 1:
+        raise ValueError("Only one marker can be specified")
+
+    # Use only first marker
+    marker = next(iter(markers.values()))
+
+    # Scale input units to output units
+    marker.age = PDFs.scaling.scale_pdf_by_units(
+        marker.age, inps.age_unit_out, verbose=inps.verbose
+    )
+
+    marker.displacement = PDFs.scaling.scale_pdf_by_units(
+        marker.displacement, inps.displacement_unit_out, verbose=inps.verbose
+    )
+
+    # Initialize figure and axis for input marker
+    marker_fig, marker_ax = plt.subplots()
+
+    # Plot marker
+    plotting.variable_pair_plots.plot_variable_pair_whisker(
+        marker_ax, marker, label=True
+    )
+
+    # Format marker fig
+    plotting.variable_pair_plots.set_origin_zero(marker_ax)
+    plotting.variable_pair_plots.format_marker_plot(marker_ax, marker)
+
+    # Save marker fig
+    reporting.save_marker_fig(
+        inps.output_prefix, marker_fig, verbose=inps.verbose
+    )
+
+    # Compute slip rate
+    slip_rate = rate_computation.compute_slip_rate(
+        marker=marker,
+        dr=inps.dr,
+        max_rate=inps.max_rate,
+    )
+
+    # Save PDF to file
+    rate_outname = f"{inps.output_prefix}_{slip_rate.name}_slip_rate.txt"
+    PDFs.readers.save_pdf(rate_outname, slip_rate, verbose=inps.verbose)
+
+    # Compute PDF statistics
+    pdf_stats = PDFs.analytics.compute_pdf_statistics(
+        slip_rate, verbose=inps.verbose
+    )
+
+    # Compute confidence range
+    conf_range = PDFs.analytics.compute_pdf_confidence_range(
+        pdf=slip_rate,
+        metric=inps.confidence_metric,
+        confidence=inps.confidence_limits,
+        verbose=inps.verbose,
+    )
+
+    # Initialize figure and axis for slip rate PDF
+    rate_fig, rate_ax = plt.subplots()
+
+    # Plot slip rate PDF
+    plotting.plot_pdf_labeled(rate_ax, slip_rate)
+
+    # Plot confidence range
+    plotting.plot_pdf_confidence_range(
+        rate_ax, slip_rate, conf_range
+    )
+
+    # Save slip rate figure
+    reporting.save_slip_rate_fig(
+        inps.output_prefix, rate_fig, verbose=inps.verbose
+    )
+
+    # Save slip rate report to file
+    if marker.name is None:
+        raise AssertionError("Marker name is guaranteed non-None.")
+
+    reporting.write_slip_rates_report(
+        output_prefix=inps.output_prefix,
+        formulation="analytical",
+        slip_rates={marker.name: slip_rate},
+        pdf_statistics={marker.name: pdf_stats},
+        verbose=inps.verbose
+    )
+
+    # Plot if requested
+    if inps.plot:
+        plt.show()
+
+
+if __name__ == "__main__":
+    main()
+
+
+# end of file