Update docs

.github/workflows/coverage.yml

@@ -4,7 +4,7 @@ on:
  push:
  pull_request:
  paths:
- - prog_models
+ - progpy
 
 jobs:
  coverage:

.github/workflows/greetings.yml

@@ -12,4 +12,4 @@ jobs:
  - uses: actions/first-interaction@v1
  with:
  repo-token: ${{ secrets.GITHUB_TOKEN }}
- pr-message: "Thank you for your contributions. If you haven't already, please send a signed Contributor License Agreement (CLA) to Christopher Teubert (christopher.a.teubert@nasa.gov). CLAs can be found here: https://github.com/nasa/prog_models/tree/master/forms. Also, make sure you're familiar with the developer notes and contributing sections of our developers guide, https://nasa.github.io/progpy/dev_guide.html#notes-for-developers"
+ pr-message: "Thank you for your contributions. If you haven't already, please send a signed Contributor License Agreement (CLA) to Christopher Teubert (christopher.a.teubert@nasa.gov). CLAs can be found here: https://github.com/nasa/progpy/tree/master/forms. Also, make sure you're familiar with the developer notes and contributing sections of our developers guide, https://nasa.github.io/progpy/dev_guide.html#notes-for-developers"

README.md

@@ -53,7 +53,7 @@ ProgPy was created by a partnership of multiple organizations, working together
 * Vanderbilt University
 
 ## Acknowledgements
-The structure and algorithms of this package are strongly inspired by the [MATLAB Prognostics Model Library](https://github.com/nasa/PrognosticsModelLibrary), [MATLAB Prognostics Algorithm Library](https://github.com/nasa/PrognosticsAlgorithmLibrary), and the [MATLAB Prognostics Metrics Library](https://github.com/nasa/PrognosticsMetricsLibrary). We would like to recognize Matthew Daigle and the rest of the team that contributed to the Prognostics Model Library for the contributions their work on the MATLAB library made to the design of prog_models.
+The structure and algorithms of this package are strongly inspired by the [MATLAB Prognostics Model Library](https://github.com/nasa/PrognosticsModelLibrary), [MATLAB Prognostics Algorithm Library](https://github.com/nasa/PrognosticsAlgorithmLibrary), and the [MATLAB Prognostics Metrics Library](https://github.com/nasa/PrognosticsMetricsLibrary). We would like to recognize Matthew Daigle and the rest of the team that contributed to the Prognostics Models, Algorithms, and Metrics Libraries for the contributions their work on the MATLAB library made to the design of progpy.
 
 ## Notices
 Copyright © 2021 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. All Rights Reserved.

examples/basic_example_battery.py

@@ -45,7 +45,7 @@ def run_example():
  batt.InputContainer({'i': 2}),
  batt.InputContainer({'i': 3})
  ]
- def future_loading(t, x = None):
+ def future_loading(t, x=None):
  # Variable (piece-wise) future loading scheme 
  if (t < 600):
  return loads[0]
@@ -94,7 +94,7 @@ def future_loading(t, x = None):
  NUM_SAMPLES = 25
  STEP_SIZE = 0.1
  SAVE_FREQ = 100 # How often to save results
- mc_results = mc.predict(filt.x, future_loading, n_samples = NUM_SAMPLES, dt=STEP_SIZE, save_freq = SAVE_FREQ)
+ mc_results = mc.predict(filt.x, future_loading, n_samples=NUM_SAMPLES, dt=STEP_SIZE, save_freq=SAVE_FREQ)
  print('ToE', mc_results.time_of_event.mean)
 
  # Step 3c: Analyze the results

sphinx-config/releases.rst

@@ -18,10 +18,13 @@ progpy
 
 * Various bug fixes and performance improvements
 
+Upgrading from v1.5
+^^^^^^^^^^^^^^^^^^^^^^
+v1.6 combined prog_models and prog_algs into a single package progpy. To upgrade to 1.6, you will need to download the new progpy package (pip install progpy) and update all imports to use progpy. For example `from prog_models import PrognosticsModel` becomes `from progpy import PrognosticsModel`, and `from prog_algs import predictors` becomes `from progpy import predictors`.
+
 prog_server
 ************
-
-
+* Updated to work with progpy v1.6
 
 Updates in V1.5
 -----------------------

tutorial.ipynb

@@ -5,17 +5,17 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "# Welcome to the Prognostics Model Package Tutorial"
+ "# Welcome to the Prognostics Python Package (ProgPy) Tutorial"
  ]
  },
  {
  "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "The goal of this notebook is to instruct users on how to use and extend the NASA PCoE Python Prognostics Model Package (prog_models). \n",
+ "The goal of this notebook is to instruct users on how to use and extend the NASA PCoE Python Prognostics Python Package (progpy). \n",
  "\n",
- "First some background. The Prognostics Model Package is a python package for the modeling and simulation of the evolution of state for components, systems, and systems of systems, with a focus on simulating specific events. When used for prognostics, these events are typically system failures, such as a winding failure on a motor or full discharge of a battery. \n",
+ "First some background. The Prognostics Python Package is a python package for the modeling, simulation, state estimation, and prediction of the evolution of state for components, systems, and systems of systems, with a focus on simulating specific events. When used for prognostics, these events are typically system failures, such as a winding failure on a motor or full discharge of a battery. \n",
  "\n",
  "A few definitions:\n",
  "* __Event__: Something that can be predicted (e.g., system failure, warning threshold). An event has either occurred or not. \n",
@@ -24,19 +24,25 @@
  "* __Outputs__: Measured sensor values from a system (e.g., voltage and temperature of a battery), outputs can be estimated from system state\n",
  "* __States__: Internal parameters (typically hidden states) used to represent the state of the system- can be the same as inputs/outputs but do not have to be.\n",
  "* __Performance Metrics__: Performance characteristics of a system that are a function of system state, but are not directly measured. For example, a performance metric for a electric motor might be the maximum achievable torque \n",
+ "* __State Estimation__: The process of estimating the (possibly hidden) state of a system given sensor information on observable states\n",
+ "* __Prediction__: The process of predicting the evolution of a system state with time and the occurrence of events. \n",
  "\n",
  "The `progpy` package has the following structure\n",
- "* `progpy.data_models` - package containing algorithms for data-driven models, and parent class `prog_models.data_models.DataModel`\n",
+ "* `progpy.data_models` - package containing algorithms for data-driven models, and parent class `progpy.data_models.DataModel`\n",
  "* `progpy.datasets` - package containing tools for downloading a few relevant datasets\n",
  "* `progpy.loading` - package containing tools for representing different loading profiles\n",
  "* `progpy.models.*` - implemented models (e.g., pump, valve, battery)\n",
+ "* `progpy.state_estimators.*` - State Estimation algorithms\n",
+ "* `progpy.predictors.*` - Prediction algorithms\n",
+ "* `progpy.uncertain_data.*` - Classes for representing data with uncertainty\n",
  "* `progpy.utils.*` - various utility functions and classes\n",
  "* `progpy.CompositeModel` - model of a system-of-systems, combining multiple interrelated models into a single model\n",
  "* `progpy.EnsembleModel` - model combining multiple models of the same system into a single model\n",
+ "* `progpy.MixtureOfExpertsModel` - model combining multiple models of the same system into a single model where the \"best\" model is used at every step\n",
  "* `progpy.LinearModel` - parent class for simple linear models\n",
  "* `progpy.PrognosticsModel` - parent class for all prognostics models - defines interfaces that a model must implement, and tools for simulating said model\n",
  "\n",
- "In addition to the `proypy` package, the GitHub repository includes many examples illustrating how to use the package (see `examples/`), a template for implementing a new model (`prog_model_template`), and this tutorial (`tutorial.ipynb`). Documentation for ProgPy can be found at <https://nasa.github.io/progpy>,\n",
+ "In addition to the `proypy` package, the GitHub repository includes many examples illustrating how to use the package (see `examples/`), a template for implementing a new model (`prog_model_template`), a template for implementing a new state estimator (`state_estimator_template`), a template for implementing a new predictor (`predictor_template`), and this tutorial (`tutorial.ipynb`). Documentation for ProgPy can be found at <https://nasa.github.io/progpy>,\n",
  "\n",
  "Before you start, make sure to install progpy using the following command:\n",
  "\n",
@@ -60,7 +66,7 @@
  "source": [
  "This first example is for using the included prognostics models. \n",
  "\n",
- "The `progpy.models` package includes implemented models, including ones for pumps, valves, batteries, and more. See <https://nasa.github.io/progpy/api_ref/prog_models/IncludedModels.html> for a full description of the included models.\n",
+ "The `progpy.models` package includes implemented models, including ones for pumps, valves, batteries, and more. See <https://nasa.github.io/progpy/api_ref/progpy/IncludedModels.html> for a full description of the included models.\n",
  "\n",
  "First thing to do is to import the model you would like to use:"
  ]
@@ -79,7 +85,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "This imports the BatteryCircuit model distributed with the `prog_models` package. See <https://nasa.github.io/progpy/api_ref/prog_models/IncludedModels.html> for details on this model.\n",
+ "This imports the BatteryCircuit model distributed with the `progpy` package. See <https://nasa.github.io/progpy/api_ref/progpy/IncludedModels.html> for details on this model.\n",
  "\n",
  "Next, let's create a new battery using the default settings:"
  ]
@@ -118,7 +124,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "These parameters describe the specific system (in this case battery) the model is simulating. See <https://nasa.github.io/progpy/api_ref/prog_models/IncludedModels.html> for a full list of configurable model parameters. Let's use the model properties to check out some details of this model, first the model configuration:"
+ "These parameters describe the specific system (in this case battery) the model is simulating. See <https://nasa.github.io/progpy/api_ref/progpy/IncludedModels.html> for a full list of configurable model parameters. Let's use the model properties to check out some details of this model, first the model configuration:"
  ]
  },
  {
@@ -210,7 +216,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "Now let's look at what events we're predicting. This model only predicts one event, called EOD (End of Discharge), but that's not true for every model. See <https://nasa.github.io/prog_models/models.html>"
+ "Now let's look at what events we're predicting. This model only predicts one event, called EOD (End of Discharge), but that's not true for every model. See <https://nasa.github.io/progpy/models.html>"
  ]
  },
  {
@@ -273,7 +279,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "Note that future loading can be modeled using various classes in prog_models.loading or as any function f(t: float, x: StateContainer) -> InputContainer.\n",
+ "Note that future loading can be modeled using various classes in progpy.loading or as any function f(t: float, x: StateContainer) -> InputContainer.\n",
  "\n",
  "At last it's time to simulate. First we're going to simulate forward 200 seconds. To do this we use the function simulate_to() to simulate to the specified time and print the results."
  ]
@@ -1220,6 +1226,154 @@
  "See also examples.param_est for more details about this feature"
  ]
  },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## UncertainData - Representing a Distribution"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Uncertainty is sometimes present in data used for performing state estimations or making predictions.\n",
+ "\n",
+ "In `progpy`, data with uncertainty is represented using classes inheriting from `UncertainData`:\n",
+ "* `progpy.uncertain_data.MultivariateNormalDist` - Data represented by a multivariate normal distribution with mean and covariance matrix\n",
+ "* `progpy.uncertain_data.ScalarData` - Data without uncertainty, a single value\n",
+ "* `progpy.uncertain_data.UnweightedSamples` - Data represented by a set of unweighted samples. Objects of this class can be treated like a list where samples[n] returns the nth sample (Dict)\n",
+ "\n",
+ "To begin using `UncertainData`, import the type that best portrays the data. In this simple demonstration, we import the `UnweightedSamples` data type. See <https://nasa.github.io/progpy/api_ref/progpy/UncertainData.html> for full details on the available `UncertainData` types."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from progpy.uncertain_data import UnweightedSamples"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "With `UnweightedSamples` imported, construct an object with samples. This object can be initialized using either a dictionary, list, or model.*Container type from prog_models (e.g., StateContainer). Let's try creating an object using a dictionary. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "samples = UnweightedSamples([{'x': 1, 'v':2}, {'x': 3, 'v':-2}])\n",
+ "print(samples)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Given an integer value, addition and subtraction can be performed on the `UncertainData` classes to adjust the distribution by a scalar amount."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "samples = samples + 5\n",
+ "print(samples)\n",
+ "samples -= 3\n",
+ "print(samples)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can also sample from any `UncertainData` distribution using the `sample` method. In this case it resamples from the existing samples"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print(samples.sample()) # A single sample\n",
+ "print(samples.sample(10)) # 10 samples"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can see the keys present using the `.keys()` method:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print(samples.keys())"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "and the data corresponding to a specific key can be retrieved using `.key()`"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print(samples.key('x'))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Various properties are available to quantify the `UncertainData` distribution"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print('mean', samples.mean)\n",
+ "print('median', samples.median)\n",
+ "print('covariance', samples.cov)\n",
+ "print('size', samples.size)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "These `UncertainData` classes are used throughout the prog_algs package to represent data with uncertainty, as described in the following sections."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## State Estimation"
+ ]
+ },
  {
  "attachments": {},
  "cell_type": "markdown",
@@ -1239,7 +1393,7 @@
  "* `examples.new_model`: Example building a new model\n",
  "* `examples.noise`: Example demonstrating how noise can be added in simulation\n",
  "* `examples.vectorized`: Example simulating a vectorized model\n",
- "* `examples.sim`, `examples.sim_battery_eol`, `examples.sim_pump`, `examples.sim_valve`, `examples.sim_powertrain`, `examples.sim_dcmotor_singlephase`: Examples using specific models from `prog_models.models`\n",
+ "* `examples.sim`, `examples.sim_battery_eol`, `examples.sim_pump`, `examples.sim_valve`, `examples.sim_powertrain`, `examples.sim_dcmotor_singlephase`: Examples using specific models from `progpy.models`\n",
  "* `examples.lstm_model`, `examples.full_lstm_model`, and `examples.custom_model`: Examples using data-driven models\n",
  "\n",
  "Thank you for trying out this tutorial. Open an issue on github (https://github.com/nasa/progpy/issues) or email Chris Teubert (christopher.a.teubert@nasa.gov) with any questions or issues."