First attempt at auto-documentation

This commit is contained in:
Ozzie Gooen 2022-06-03 17:59:02 -07:00
parent 9b0def16ef
commit 10de355f86
3 changed files with 315 additions and 39 deletions

View File

@ -42,6 +42,9 @@ type fnDefinition = {
type function = { type function = {
name: string, name: string,
definitions: array<fnDefinition>, definitions: array<fnDefinition>,
examples: option<string>,
description: option<string>,
isExperimental: bool,
} }
type registry = array<function> type registry = array<function>
@ -55,9 +58,9 @@ module FRType = {
| FRTypeDistOrNumber => "frValueDistOrNumber" | FRTypeDistOrNumber => "frValueDistOrNumber"
| FRTypeRecord(r) => { | FRTypeRecord(r) => {
let input = ((name, frType): frTypeRecordParam) => `${name}: ${toString(frType)}` let input = ((name, frType): frTypeRecordParam) => `${name}: ${toString(frType)}`
`record({${r->E.A2.fmap(input)->E.A2.joinWith(", ")}})` `{${r->E.A2.fmap(input)->E.A2.joinWith(", ")}}`
} }
| FRTypeArray(r) => `record(${toString(r)})` | FRTypeArray(r) => `array<${toString(r)}>`
| FRTypeLambda => `lambda` | FRTypeLambda => `lambda`
| FRTypeString => `string` | FRTypeString => `string`
| FRTypeVariant(_) => "variant" | FRTypeVariant(_) => "variant"
@ -291,13 +294,34 @@ module FnDefinition = {
module Function = { module Function = {
type t = function type t = function
let make = (~name, ~definitions): t => { type functionJson = {
name: string,
definitions: array<string>,
examples: option<string>,
description: option<string>,
isExperimental: bool,
}
let make = (~name, ~definitions, ~examples=?, ~description=?, ~isExperimental=false, ()): t => {
name: name, name: name,
definitions: definitions, definitions: definitions,
examples: examples,
isExperimental: isExperimental,
description: description,
}
let toSimple = (t: t): functionJson => {
name: t.name,
definitions: t.definitions->E.A2.fmap(FnDefinition.toString),
examples: t.examples,
description: t.description,
isExperimental: t.isExperimental,
} }
} }
module Registry = { module Registry = {
let toSimple = (r: registry) => r->E.A2.fmap(Function.toSimple)
/* /*
There's a (potential+minor) bug here: If a function definition is called outside of the calls There's a (potential+minor) bug here: If a function definition is called outside of the calls
to the registry, then it's possible that there could be a match after the registry is to the registry, then it's possible that there could be a match after the registry is
@ -310,6 +334,7 @@ module Registry = {
~env: DistributionOperation.env, ~env: DistributionOperation.env,
) => { ) => {
let matchToDef = m => Matcher.Registry.matchToDef(registry, m) let matchToDef = m => Matcher.Registry.matchToDef(registry, m)
Js.log(toSimple(registry))
let showNameMatchDefinitions = matches => { let showNameMatchDefinitions = matches => {
let defs = let defs =
matches matches

View File

@ -49,35 +49,10 @@ let inputsTodist = (inputs: array<FunctionRegistry_Core.frValue>, makeDist) => {
let registry = [ let registry = [
Function.make( Function.make(
~name="toContinuousPointSet", ~name="Normal Distribution",
~definitions=[ ~examples=`normal(5,1)
FnDefinition.make( normal({p5: 4, p95: 10})
~name="toContinuousPointSet", normal({mean: 5, stdev: 2})`,
~inputs=[FRTypeArray(FRTypeRecord([("x", FRTypeNumeric), ("y", FRTypeNumeric)]))],
~run=(inputs, _) => inputsTodist(inputs, r => Continuous(Continuous.make(r))),
),
],
),
Function.make(
~name="toDiscretePointSet",
~definitions=[
FnDefinition.make(
~name="toDiscretePointSet",
~inputs=[FRTypeArray(FRTypeRecord([("x", FRTypeNumeric), ("y", FRTypeNumeric)]))],
~run=(inputs, _) => inputsTodist(inputs, r => Discrete(Discrete.make(r))),
),
],
),
Function.make(
~name="Declaration",
~definitions=[
FnDefinition.make(~name="declareFn", ~inputs=[Declaration.frType], ~run=(inputs, _) => {
inputs->E.A.unsafe_get(0)->Declaration.fromExpressionValue
}),
],
),
Function.make(
~name="Normal",
~definitions=[ ~definitions=[
TwoArgDist.make("normal", twoArgs(SymbolicDist.Normal.make)), TwoArgDist.make("normal", twoArgs(SymbolicDist.Normal.make)),
TwoArgDist.makeRecordP5P95("normal", r => TwoArgDist.makeRecordP5P95("normal", r =>
@ -85,9 +60,13 @@ let registry = [
), ),
TwoArgDist.makeRecordMeanStdev("normal", twoArgs(SymbolicDist.Normal.make)), TwoArgDist.makeRecordMeanStdev("normal", twoArgs(SymbolicDist.Normal.make)),
], ],
(),
), ),
Function.make( Function.make(
~name="Lognormal", ~name="Lognormal Distribution",
~examples=`lognormal(0.5, 0.8)
lognormal({p5: 4, p95: 10})
lognormal({mean: 5, stdev: 2})`,
~definitions=[ ~definitions=[
TwoArgDist.make("lognormal", twoArgs(SymbolicDist.Lognormal.make)), TwoArgDist.make("lognormal", twoArgs(SymbolicDist.Lognormal.make)),
TwoArgDist.makeRecordP5P95("lognormal", r => TwoArgDist.makeRecordP5P95("lognormal", r =>
@ -95,29 +74,43 @@ let registry = [
), ),
TwoArgDist.makeRecordMeanStdev("lognormal", twoArgs(SymbolicDist.Lognormal.fromMeanAndStdev)), TwoArgDist.makeRecordMeanStdev("lognormal", twoArgs(SymbolicDist.Lognormal.fromMeanAndStdev)),
], ],
(),
), ),
Function.make( Function.make(
~name="Uniform", ~name="Uniform Distribution",
~examples=`uniform(10, 12)`,
~definitions=[TwoArgDist.make("uniform", twoArgs(SymbolicDist.Uniform.make))], ~definitions=[TwoArgDist.make("uniform", twoArgs(SymbolicDist.Uniform.make))],
(),
), ),
Function.make( Function.make(
~name="Beta", ~name="Beta Distribution",
~examples=`beta(20, 25)`,
~definitions=[TwoArgDist.make("beta", twoArgs(SymbolicDist.Beta.make))], ~definitions=[TwoArgDist.make("beta", twoArgs(SymbolicDist.Beta.make))],
(),
), ),
Function.make( Function.make(
~name="Cauchy", ~name="Cauchy Distribution",
~examples=`cauchy(5, 1)`,
~definitions=[TwoArgDist.make("cauchy", twoArgs(SymbolicDist.Cauchy.make))], ~definitions=[TwoArgDist.make("cauchy", twoArgs(SymbolicDist.Cauchy.make))],
(),
), ),
Function.make( Function.make(
~name="Gamma", ~name="Gamma Distribution",
~examples=`gamma(5, 1)`,
~definitions=[TwoArgDist.make("gamma", twoArgs(SymbolicDist.Gamma.make))], ~definitions=[TwoArgDist.make("gamma", twoArgs(SymbolicDist.Gamma.make))],
(),
), ),
Function.make( Function.make(
~name="Logistic", ~name="Logistic Distribution",
~examples=`gamma(5, 1)`,
~definitions=[TwoArgDist.make("logistic", twoArgs(SymbolicDist.Logistic.make))], ~definitions=[TwoArgDist.make("logistic", twoArgs(SymbolicDist.Logistic.make))],
(),
), ),
Function.make( Function.make(
~name="To", ~name="To (Distribution)",
~examples=`5 to 10
to(5,10)
-5 to 5`,
~definitions=[ ~definitions=[
TwoArgDist.make("to", twoArgs(SymbolicDist.From90thPercentile.make)), TwoArgDist.make("to", twoArgs(SymbolicDist.From90thPercentile.make)),
TwoArgDist.make( TwoArgDist.make(
@ -125,13 +118,72 @@ let registry = [
twoArgs(SymbolicDist.From90thPercentile.make), twoArgs(SymbolicDist.From90thPercentile.make),
), ),
], ],
(),
), ),
Function.make( Function.make(
~name="Exponential", ~name="Exponential",
~examples=`exponential(2)`,
~definitions=[OneArgDist.make("exponential", SymbolicDist.Exponential.make)], ~definitions=[OneArgDist.make("exponential", SymbolicDist.Exponential.make)],
(),
), ),
Function.make( Function.make(
~name="Bernoulli", ~name="Bernoulli",
~examples=`bernoulli(0.5)`,
~definitions=[OneArgDist.make("bernoulli", SymbolicDist.Bernoulli.make)], ~definitions=[OneArgDist.make("bernoulli", SymbolicDist.Bernoulli.make)],
(),
),
Function.make(
~name="toContinuousPointSet",
~description="Converts a set of points to a continuous distribution",
~examples=`toContinuousPointSet([
{x: 0, y: 0.1},
{x: 1, y: 0.2},
{x: 2, y: 0.15},
{x: 3, y: 0.1}
])`,
~definitions=[
FnDefinition.make(
~name="toContinuousPointSet",
~inputs=[FRTypeArray(FRTypeRecord([("x", FRTypeNumeric), ("y", FRTypeNumeric)]))],
~run=(inputs, _) => inputsTodist(inputs, r => Continuous(Continuous.make(r))),
),
],
(),
),
Function.make(
~name="toDiscretePointSet",
~description="Converts a set of points to a discrete distribution",
~examples=`toDiscretePointSet([
{x: 0, y: 0.1},
{x: 1, y: 0.2},
{x: 2, y: 0.15},
{x: 3, y: 0.1}
])`,
~definitions=[
FnDefinition.make(
~name="toDiscretePointSet",
~inputs=[FRTypeArray(FRTypeRecord([("x", FRTypeNumeric), ("y", FRTypeNumeric)]))],
~run=(inputs, _) => inputsTodist(inputs, r => Discrete(Discrete.make(r))),
),
],
(),
),
Function.make(
~name="Declaration (Continuous Function)",
~description="Adds metadata to a function of the input ranges. Works now for numeric and date inputs. This is useful when making predictions. It allows you to limit the domain that your prediction will be used and scored within.",
~examples=`declareFn({
fn: {|a,b| a },
inputs: [
{min: 0, max: 100},
{min: 30, max: 50}
]
})`,
~definitions=[
FnDefinition.make(~name="declareFn", ~inputs=[Declaration.frType], ~run=(inputs, _) => {
inputs->E.A.unsafe_get(0)->Declaration.fromExpressionValue
}),
],
~isExperimental=true,
(),
), ),
] ]

View File

@ -0,0 +1,199 @@
---
sidebar_position: 5
title: API
---
## Normal Distribution
**Definitions**
```javascript
normal(frValueDistOrNumber, frValueDistOrNumber)
```
```javascript
normal(dict<{p5: frValueDistOrNumber, p95: frValueDistOrNumber}>)
```
```javascript
normal(dict<{mean: frValueDistOrNumber, stdev: frValueDistOrNumber}>)
```
**Examples**
```javascript
normal(5,1)
normal({p5: 4, p95: 10})
normal({mean: 5, stdev: 2})
```
## Lognormal Distribution
**Definitions**
```javascript
lognormal(frValueDistOrNumber, frValueDistOrNumber)
```
```javascript
lognormal(dict<{p5: frValueDistOrNumber, p95: frValueDistOrNumber}>)
```
```javascript
lognormal(dict<{mean: frValueDistOrNumber, stdev: frValueDistOrNumber}>)
```
**Examples**
```javascript
lognormal(0.5, 0.8)
lognormal({p5: 4, p95: 10})
lognormal({mean: 5, stdev: 2})
```
## Uniform Distribution
**Definitions**
```javascript
uniform(frValueDistOrNumber, frValueDistOrNumber)
```
**Examples**
```javascript
uniform(10, 12)
```
## Beta Distribution
**Definitions**
```javascript
beta(frValueDistOrNumber, frValueDistOrNumber)
```
**Examples**
```javascript
beta(20, 25)
```
## Cauchy Distribution
**Definitions**
```javascript
cauchy(frValueDistOrNumber, frValueDistOrNumber)
```
**Examples**
```javascript
cauchy(5, 1)
```
## Gamma Distribution
**Definitions**
```javascript
gamma(frValueDistOrNumber, frValueDistOrNumber)
```
**Examples**
```javascript
gamma(5, 1)
```
## Logistic Distribution
**Definitions**
```javascript
logistic(frValueDistOrNumber, frValueDistOrNumber)
```
**Examples**
```javascript
gamma(5, 1)
```
## To (Distribution)
**Definitions**
```javascript
to(frValueDistOrNumber, frValueDistOrNumber)
```
```javascript
credibleIntervalToDistribution(frValueDistOrNumber, frValueDistOrNumber)
```
**Examples**
```javascript
5 to 10
to(5,10)
-5 to 5
```
## Exponential
**Definitions**
```javascript
exponential(frValueDistOrNumber)
```
**Examples**
```javascript
exponential(2)
```
## Bernoulli
**Definitions**
```javascript
bernoulli(frValueDistOrNumber)
```
**Examples**
```javascript
bernoulli(0.5)
```
## toContinuousPointSet
Converts a set of points to a continuous distribution
**Definitions**
```javascript
toContinuousPointSet(array<dict<{x: numeric, y: numeric}>>)
```
**Examples**
```javascript
toContinuousPointSet([
{x: 0, y: 0.1},
{x: 1, y: 0.2},
{x: 2, y: 0.15},
{x:3, y: 0.1}
])
```
## toDiscretePointSet
Converts a set of points to a discrete distribution
**Definitions**
```javascript
toDiscretePointSet(array<dict<{x: numeric, y: numeric}>>)
```
**Examples**
```javascript
toDiscretePointSet([
{x: 0, y: 0.1},
{x: 1, y: 0.2},
{x: 2, y: 0.15},
{x:3, y: 0.1}
])
```
## Declaration (Continuous Function)
Adds metadata to a function of the input ranges. Works now for numeric and date inputs. This is useful when making predictions. It allows you to limit the domain that your prediction will be used and scored within.
**Definitions**
```javascript
declareFn(dict<{fn: lambda, inputs: array<dict<{min: number, max: number}>>}>)
```
**Examples**
```javascript
declareFn({
fn: {|a,b| a },
inputs: [
{min: 0, max: 100},
{min: 30, max: 50}
]
})
```