From 31de55633e3e2eb91682b04face3a4ff47081246 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Tue, 10 Oct 2023 11:52:15 +0200 Subject: [PATCH] Improve docs --- README.md | 28 ++++++++++++++++++++--- lib/scholar.ex | 11 --------- lib/scholar/interpolation/linear.ex | 2 ++ lib/scholar/linear/isotonic_regression.ex | 2 +- mix.exs | 3 ++- mix.lock | 2 +- 6 files changed, 31 insertions(+), 17 deletions(-) delete mode 100644 lib/scholar.ex diff --git a/README.md b/README.md index 0533a518..b07e9ab4 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,11 @@ -

Scholar

+

+ Scholar +
+ + +

-[![Documentation](http://img.shields.io/badge/hex.pm-docs-green.svg?style=flat)](https://hexdocs.pm/scholar) -[![Package](https://img.shields.io/hexpm/v/scholar.svg)](https://hex.pm/packages/scholar) +
Traditional machine learning tools built on top of Nx. Scholar implements several algorithms for classification, regression, clustering, dimensionality @@ -45,6 +49,15 @@ config :nx, :default_backend, EXLA.Backend config :nx, :default_defn_options, [compiler: EXLA, client: :host] ``` +> #### JIT required! {: .warning} +> +> It is important you set the `default_defn_options` as shown in the snippet above, +> as many algorithms in Scholar use loops which are much more memory efficient when +> JIT compiled. +> +> If for some reason you cannot set a default `defn` compiler, you can explicitly +> JIT any function, for example: `EXLA.jit(&Scholar.Cluster.AffinityPropagation.fit/1)`. + ### Notebooks To use Scholar inside code notebooks, run: @@ -60,6 +73,15 @@ Nx.global_default_backend(EXLA.Backend) Nx.Defn.global_default_options(compiler: EXLA, client: :host) ``` +> #### JIT required! {: .warning} +> +> It is important you set the `Nx.Defn.global_default_options/1` as shown in the snippet +> above, as many algorithms in Scholar use loops which are much more memory efficient +> when JIT compiled. +> +> If for some reason you cannot set a default `defn` compiler, you can explicitly +> JIT any function, for example: `EXLA.jit(&Scholar.Cluster.AffinityPropagation.fit/1)`. + ## License Copyright (c) 2022 The Machine Learning Working Group of the Erlang Ecosystem Foundation diff --git a/lib/scholar.ex b/lib/scholar.ex deleted file mode 100644 index abf64ad8..00000000 --- a/lib/scholar.ex +++ /dev/null @@ -1,11 +0,0 @@ -defmodule Scholar do - @moduledoc """ - Traditional machine learning tools built on top of Nx. Scholar implements - several algorithms for classification, regression, clustering, dimensionality - reduction, metrics, and preprocessing. - - For deep learning, see [Axon](https://github.com/elixir-nx/axon). - - Click on the "Guides" tab for some example notebooks. - """ -end diff --git a/lib/scholar/interpolation/linear.ex b/lib/scholar/interpolation/linear.ex index 9f65152a..e6ae850f 100644 --- a/lib/scholar/interpolation/linear.ex +++ b/lib/scholar/interpolation/linear.ex @@ -20,6 +20,8 @@ defmodule Scholar.Interpolation.Linear do @derive {Nx.Container, containers: [:coefficients, :x]} defstruct [:coefficients, :x] + @type t :: %Scholar.Interpolation.Linear{} + @doc """ Fits a linear interpolation of the given `(x, y)` points diff --git a/lib/scholar/linear/isotonic_regression.ex b/lib/scholar/linear/isotonic_regression.ex index 0360b995..e4f641be 100644 --- a/lib/scholar/linear/isotonic_regression.ex +++ b/lib/scholar/linear/isotonic_regression.ex @@ -38,7 +38,7 @@ defmodule Scholar.Linear.IsotonicRegression do y_thresholds: Nx.Tensor.t(), increasing: Nx.Tensor.t(), cutoff_index: Nx.Tensor.t(), - preprocess: Tuple.t() | Scholar.Interpolation.Linear.t() + preprocess: tuple() | Scholar.Interpolation.Linear.t() } opts = [ diff --git a/mix.exs b/mix.exs index 4908188d..c439392e 100644 --- a/mix.exs +++ b/mix.exs @@ -49,11 +49,12 @@ defmodule Scholar.MixProject do defp docs do [ - main: "Scholar", + main: "readme", source_url: @source_url, logo: "images/scholar_simplified.png", extra_section: "Guides", extras: [ + "README.md", "notebooks/linear_regression.livemd", "notebooks/k_means.livemd", "notebooks/k_nearest_neighbors.livemd", diff --git a/mix.lock b/mix.lock index a69d4862..cb415b64 100644 --- a/mix.lock +++ b/mix.lock @@ -1,6 +1,6 @@ %{ "complex": {:hex, :complex, "0.5.0", "af2d2331ff6170b61bb738695e481b27a66780e18763e066ee2cd863d0b1dd92", [:mix], [], "hexpm", "2683bd3c184466cfb94fad74cbfddfaa94b860e27ad4ca1bffe3bff169d91ef1"}, - "earmark_parser": {:hex, :earmark_parser, "1.4.33", "3c3fd9673bb5dcc9edc28dd90f50c87ce506d1f71b70e3de69aa8154bc695d44", [:mix], [], "hexpm", "2d526833729b59b9fdb85785078697c72ac5e5066350663e5be6a1182da61b8f"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.37", "2ad73550e27c8946648b06905a57e4d454e4d7229c2dafa72a0348c99d8be5f7", [:mix], [], "hexpm", "6b19783f2802f039806f375610faa22da130b8edc21209d0bff47918bb48360e"}, "elixir_make": {:hex, :elixir_make, "0.7.7", "7128c60c2476019ed978210c245badf08b03dbec4f24d05790ef791da11aa17c", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}], "hexpm", "5bc19fff950fad52bbe5f211b12db9ec82c6b34a9647da0c2224b8b8464c7e6c"}, "ex_doc": {:hex, :ex_doc, "0.30.6", "5f8b54854b240a2b55c9734c4b1d0dd7bdd41f71a095d42a70445c03cf05a281", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "bd48f2ddacf4e482c727f9293d9498e0881597eae6ddc3d9562bd7923375109f"}, "exla": {:hex, :exla, "0.6.0", "af63e45ce41ad25630967923147d14292a0cc48e507b8a3cf3bf3d5483099a28", [:make, :mix], [{:elixir_make, "~> 0.6", [hex: :elixir_make, repo: "hexpm", optional: false]}, {:nx, "~> 0.6.0", [hex: :nx, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4.0 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:xla, "~> 0.5.0", [hex: :xla, repo: "hexpm", optional: false]}], "hexpm", "5f6a4a105ea9ab207b9aa4de5a294730e2bfe9639f4b8d37a7c00da131090d7a"},