diff --git a/RELEASES.md b/RELEASES.md index 3743290ac85e..a491145b2d06 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -4,6 +4,8 @@ - Added support for writing tables to XLSX spreadsheets ([#1906](https://github.com/enso-org/enso/pull/1906)). +- Added documentation for the new searcher categories + ([#1910](https://github.com/enso-org/enso/pull/1910)). # Enso 0.2.17 (2021-07-28) diff --git a/distribution/lib/Standard/Base/0.1.0/src/Data/Text/Extensions.enso b/distribution/lib/Standard/Base/0.1.0/src/Data/Text/Extensions.enso index 219867c27d66..011fdfa8a23e 100644 --- a/distribution/lib/Standard/Base/0.1.0/src/Data/Text/Extensions.enso +++ b/distribution/lib/Standard/Base/0.1.0/src/Data/Text/Extensions.enso @@ -102,7 +102,7 @@ Text.characters = "ham,eggs,cheese,tomatoes".split "," > Example - Split the string on whitespace into a vector of items. + Split the text on whitespace into a vector of items. "ham eggs cheese tomatoes".split Split_Kind.Whitespace Text.split : Split_Kind -> Vector.Vector Text diff --git a/distribution/lib/Standard/Searcher/package.yaml b/distribution/lib/Standard/Searcher/0.1.0/package.yaml similarity index 100% rename from distribution/lib/Standard/Searcher/package.yaml rename to distribution/lib/Standard/Searcher/0.1.0/package.yaml diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science.enso new file mode 100644 index 000000000000..c0bb72a505ba --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science.enso @@ -0,0 +1,71 @@ +## Enso is, first and foremost, a tool for putting you in direct contact with + your data, and the Data Science tools are central to that workflow. + + This section contains the functionality that you need for working with data, + from loading it into your workflow, to cleaning and transforming it, to + visualising it and getting aggregate results from it, and much more besides. + + > Example + Read the active sheet of an XLSX from disk and convert it into a table. + + import Standard.Table + import Standard.Examples + + example_xlsx_to_table = Examples.xlsx.read_xlsx + + > Example + Write a table to an XLSX file. + + import Standard.Examples + + example_to_xlsx = + path = Enso_Project.data / example_xlsx_output.xlsx + Examples.inventory_table.write_xlsx path + + > Example + Join multiple tables together. It joins tables on their indices, so we need + to make sure the indices are correct. + + import Standard.Examples + import Standard.Table + + example_join = + table_1 = Examples.inventory_table + table_2 = Examples.popularity_table + Table.join [table_1, table_2] + + > Example + Select only the items where more than half the stock has been sold. + + import Standard.Examples + + example_where = + table = Examples.inventory_table + mask = (table.at "sold_stock" > (table.at "total_stock" / 2)) + table.where mask + + > Example + Sort the shop inventory based on the total stock, using the number sold to + break ties in descending order. + + import Standard.Examples + + example_sort = + table = Examples.inventory_table + table.sort by=["total_stock", "sold_stock"] order=Sort_Order.Descending + + > Example + Compute the number of transactions that each item has participated in, as + well as the number of each item sold across those transactions. + + import Standard.Examples + import Standard.Table + + example_group = + transactions = Examples.transactions_table + item_names = Examples.inventory_table.at "item_name" + aggregated = transactions.group by="item_id" + num_transactions = aggregated.at "transaction_id" . reduce .length . rename "transaction_count" + num_sold = aggregated.at "quantity" . reduce .sum . rename "num_sold" + Table.join [item_names, num_transactions, num_sold] + diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Aggregate.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Aggregate.enso new file mode 100644 index 000000000000..e0535666dcf4 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Aggregate.enso @@ -0,0 +1,42 @@ +## With your data in the state that you want, the next step is to pull useful + summaries from it to give you insight. This is the process of _aggregation_ + or _summarisation_. + + Enso provides robust facilities for getting aggregate results from your data, + all built on a flexible foundation of grouping. + + > Example + Compute the number of transactions that each item has participated in, as + well as the number of each item sold across those transactions. + + import Standard.Examples + import Standard.Table + + example_group = + transactions = Examples.transactions_table + item_names = Examples.inventory_table.at "item_name" + aggregated = transactions.group by="item_id" + num_transactions = aggregated.at "transaction_id" . reduce .length . rename "transaction_count" + num_sold = aggregated.at "quantity" . reduce .sum . rename "num_sold" + Table.join [item_names, num_transactions, num_sold] + + > Example + Compute the maximum value of a column. + + import Standard.Examples + + example_max = Examples.integer_column.max + + > Example + Sum the values in a column. + + import Standard.Examples + + example_sum = Examples.integer_column.sum + + > Example + Compute the mean value of a column. + + import Standard.Examples + + example_mean = Examples.integer_column.mean diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Compare.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Compare.enso new file mode 100644 index 000000000000..ac74ce0b334d --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Compare.enso @@ -0,0 +1,41 @@ +## Data never exists in isolation. Seeing how your data compares to previous + data sets, market trends or competitors is a key operation for data science. + + Enso provides a robust set of tools for comparing your data with itself or + with other data sets. + + > Example + Checking if the variable `a` is equal to `147`. + + from Standard.Base import all + + example_equality = + a = 7 * 21 + a == 147 + + > Example + Checking if the variable `a` is not equal to `147`. + + from Standard.Base import all + + example_inequality = + a = 7 * 21 + a != 147 + + > Example + Checking if the variable `a` is greater than `147`. + + from Standard.Base import all + + example_greater = + a = 7 * 28 + a > 147 + + > Example + Checking if the variable `a` is less than `147`. + + from Standard.Base import all + + example_less = + a = 7 * 21 + a < 147 diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Date_And_Time.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Date_And_Time.enso new file mode 100644 index 000000000000..c16e9a46a2e9 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Date_And_Time.enso @@ -0,0 +1,34 @@ +## Along with numbers and text, dates and times are probably the most common + type of data encountered whilst doing data analysis. + + Enso provides a robust and capable suite of date and time operations, + allowing you to work with your data with ease. + + > Example + Get the current time + + import Standard.Base.Data.Time + + example_now = Time.now + + > Example + Parse UTC time. + + import Standard.Base.Data.Time + + example_parse = Time.parse "2020-10-01T04:11:12Z" + + > Example + Convert time instance to -04:00 timezone. + + import Standard.Base.Data.Time + import Standard.Base.Data.Time.Zone + + exaomple_at_zone = Time.new 2020 . at_zone (Zone.new -4) + + > Example + Convert the current time to a date. + + import Standard.Base.Data.Time + + example_date = Time.now.date diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Input_And_Output.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Input_And_Output.enso new file mode 100644 index 000000000000..db75c68d0da8 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Input_And_Output.enso @@ -0,0 +1,42 @@ +## All the tools to work with data are useless without a way to get your data + into Enso. + + This section contains a suite of common tools for loading your data into your + workflow, including the ability to read and write Excel files, CSVs, and + text. Beyond that, it also provides tools for creating your own data on the + fly, including text, numbers, and tables. + + > Example + Read the active sheet of an XLSX from disk and convert it into a table. + + import Standard.Table + import Standard.Examples + + example_xlsx_to_table = Examples.xlsx.read_xlsx + + > Example + Read a CSV from disk and convert it into a table. + + import Standard.Table + import Standard.Examples + + example_csv_to_table = Examples.csv.read_csv + + > Example + Write a table to an XLSX file. + + import Standard.Examples + + example_to_xlsx = + path = Enso_Project.data / example_xlsx_output.xlsx + Examples.inventory_table.write_xlsx path + + > Example + Write a table to a CSV file. + + import Standard.Examples + + example_to_csv = + path = Enso_Project.data / example_csv_output.csv + Examples.inventory_table.write_csv path + diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Join.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Join.enso new file mode 100644 index 000000000000..fde13544cb81 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Join.enso @@ -0,0 +1,26 @@ +## It is common to have multiple sources of data that you want to combine to get + your insights from. Joining is this process. + + This section contains Enso's utilities for joining data, be it two sources or + multiple. + + > Example + Join multiple tables together. It joins tables on their indices, so we need + to make sure the indices are correct. + + import Standard.Examples + import Standard.Table + + example_join = + table_1 = Examples.inventory_table + table_2 = Examples.popularity_table + Table.join [table_1, table_2] + + > Example + Join the popularity table and the inventory table to see the relative + popularities of the items in the shop inventory. + + import Standard.Examples + + example_join = + Examples.inventory_table.join Examples.popularity_table diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Numbers.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Numbers.enso new file mode 100644 index 000000000000..fde633b252c0 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Numbers.enso @@ -0,0 +1,25 @@ +## Numerical data is _everywhere_. This makes it of the greatest importance that + any data analysis system provides a robust set of numerical operations. + + Enso provides a comprehensive suite of tools to work with numbers, spanning + from the standard mathematical operations to some more advanced tools. + + > Example + Create a range containing the numbers 0, 1, 2, 3, 4. + + 0.up_to 5 + + > Example + Calculate the smallest number out of 1 and 2. + + Math.min 1 2 + + > Example + Calculate the largest number out of 1 and 2. + + Math.max 1 2 + + > Example + Calculate the sine of 2. + + 2.sin diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Preparation.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Preparation.enso new file mode 100644 index 000000000000..e03e572a4ab7 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Preparation.enso @@ -0,0 +1,39 @@ +## As nice as it would be to have your data all ready for analysis, this is + rarely the case. The process of getting it ready to provide insights is known + as data preparation. + + This section of the library contains a curated selection of tools that help + you to get the best out of your data. From dealing with missing values to + getting rid of erroneous rows and columns, the tools here are specialised for + getting the most out of your data. + + > Example + Get the item name and price columns from the shop inventory. + + import Standard.Examples + + example_select = + Examples.inventory_table.select ["item_name", "price"] + + > Example + Remove any rows that contain missing values from the table. + + import Standard.Examples + + example_drop_missing_rows = + Examples.inventory_table.drop_missing_rows + + > Example + Remove any columns that contain missing values from the table. + + import Standard.Examples + + example_drop_missing_cols = + Examples.inventory_table.drop_missing_columns + + > Example + Fill missing values in a column with the value 20.5. + + import Standard.Examples + + example_fill_missing = Examples.decimal_column.fill_missing 20.5 diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Text.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Text.enso new file mode 100644 index 000000000000..0b8553c1f7c5 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Text.enso @@ -0,0 +1,26 @@ +## Textual data is one of the most common formats found during data analysis. + This makes it all the more important that you have robust tools to manipulate + the text as you need. + + Enso's text representation is highly efficient and comes with a robust suite + of tools for processing the text in any way you can think of. + + > Example + Split the text on whitespace into a vector of items. + + "ham eggs cheese tomatoes".split Split_Kind.Whitespace + + > Example + Getting the words in the sentence "I have not one, but two cats." + + "I have not one, but two cats.".words + + > Example + See if the text "Hello" contains the text "ell". + + "Hello".contains "ell" + + > Example + Replace letters in the text "aaa". + + 'aaa'.replace 'aa' 'b' == 'ba' diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Transform.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Transform.enso new file mode 100644 index 000000000000..2773a990004c --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Data_Science/Transform.enso @@ -0,0 +1,42 @@ +## With all your data combined, the next step is to get insight from your data. + This is the process of transformation, shaping it into a form that tells you + what you want to know. + + Enso provides a whole host of utilities for data transformation. These + include being able to to perform arithmetic and text operations on columns, + as well as the ability to mask columns based on criteria you specify. + + > Example + Select only the items where more than half the stock has been sold. + + import Standard.Examples + + example_where = + table = Examples.inventory_table + mask = (table.at "sold_stock" > (table.at "total_stock" / 2)) + table.where mask + + > Example + Multiply each element of the column by itself. + + import Standard.Examples + + example_map = Examples.integer_column.map (x -> x * x) + + > Example + Sort the shop inventory based on the per-item price in descending order and + placing missing values at the top of the table. + + import Standard.Examples + + example_sort = + table = Examples.inventory_table + table.sort by="price" order=Sort_Order.Descending missing_last=false + + > Example + Add two columns to each other. + + import Standard.Examples + + example_plus = Examples.decimal_column + Examples.integer_column + diff --git a/distribution/lib/Standard/Searcher/src/Main.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Main.enso similarity index 99% rename from distribution/lib/Standard/Searcher/src/Main.enso rename to distribution/lib/Standard/Searcher/0.1.0/src/Main.enso index 42b8fc7eee5b..512461427506 100644 --- a/distribution/lib/Standard/Searcher/src/Main.enso +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Main.enso @@ -7,6 +7,7 @@ suggestions database. from Standard.Base import all + import Standard.Base.Error.Extensions as Error ## ALIAS Text Input diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Network.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Network.enso new file mode 100644 index 000000000000..c60f01f97837 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Network.enso @@ -0,0 +1,46 @@ +## While it is not uncommon for data to live on your computer, these days it is + more and more common for data to live elsewhere, accessible via a network. + + Enso provides a robust suite of tools for interacting with external data + sources, fetching data and analysing it locally. + + > Example + Download a file. NOTE: This example will make a network request. + + import Standard.Base.Network.Http + import Standard.Examples + + example_fetch = + out_file = Examples.scratch_file + res = Http.fetch "http://httpbin.org/bytes/1024" . to_file out_file + + > Example + Send authenticated Get request (note the use of TLS). NOTE: This example + will make a network request. + + import Standard.Base.Network.Http + import Standard.Base.Network.Http.Header + + example_get = + headers = [Header.authorization_basic "user" "pass"] + Http.get "https://httpbin.org/basic-auth/user/pass" headers + + > Example + Send a Post request with binary data. NOTE: This example will make a + network request. + + import Standard.Base.Network.Http + import Standard.Base.Network.Http.Header + import Standard.Base.Network.Http.Request.Body + + example_post = + body = Body.Bytes "Hello".utf_8 + header_binary = Header.content_type "application/octet-stream" + Http.post "http://httpbin.org/post" body [header_binary] + + > Example + Parse Uri text. + + import Standard.Base.Network.Uri + + example_parse = Uri.parse "http://example.com" diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/Network/Http.enso b/distribution/lib/Standard/Searcher/0.1.0/src/Network/Http.enso new file mode 100644 index 000000000000..f8debda63495 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/Network/Http.enso @@ -0,0 +1,47 @@ +## HTTP is the heart of Enso's networking toolkit, with a huge variety of data + available over simple endpoints. + + It provides the tools for you to fetch data from remote services, query API + endpoints and so much more. It is flexible and highly configurable, but also + provides simple and easy to use defaults. + + > Example + Download a file. NOTE: This example will make a network request. + + import Standard.Base.Network.Http + import Standard.Examples + + example_fetch = + out_file = Examples.scratch_file + res = Http.fetch "http://httpbin.org/bytes/1024" . to_file out_file + + > Example + Send authenticated Get request (note the use of TLS). NOTE: This example + will make a network request. + + import Standard.Base.Network.Http + import Standard.Base.Network.Http.Header + + example_get = + headers = [Header.authorization_basic "user" "pass"] + Http.get "https://httpbin.org/basic-auth/user/pass" headers + + > Example + Send a Post request with binary data. NOTE: This example will make a + network request. + + import Standard.Base.Network.Http + import Standard.Base.Network.Http.Header + import Standard.Base.Network.Http.Request.Body + + example_post = + body = Body.Bytes "Hello".utf_8 + header_binary = Header.content_type "application/octet-stream" + Http.post "http://httpbin.org/post" body [header_binary] + + > Example + Parse Uri text. + + import Standard.Base.Network.Uri + + example_parse = Uri.parse "http://example.com" diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/System.enso b/distribution/lib/Standard/Searcher/0.1.0/src/System.enso new file mode 100644 index 000000000000..6c562ca6f918 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/System.enso @@ -0,0 +1,39 @@ +## Sometimes Enso alone isn't enough for your work. That is why you're provided + with a robust suite of tools to use to interact with the system on which it + is running. + + From involving external processes in your workflow, to working with the file + system directly, to reading information from your computer's environment, + Enso's System library has you covered. + + > Example + Create a new file pointing to the `data.csv` file in the project directory. + + import Standard.Base.System.File + import Standard.Examples + + example_new = File.new Examples.csv_path + + > Example + Get the program's current working directory. + + import Standard.Base.System.File + + example_cwd = File.current_directory + + > Example + Get the current user's home directory. + + import Standard.Base.System.File + + example_home = File.home + + > Example + Call the "echo" command. + + import Standard.Base.System.Platform + import Standard.Base.System.Process + + example_run = case Platform.os of + Platform.Windows -> Process.run "PowerShell" ["-Command", "exit 42"] + _ -> Process.run "bash" ["-c", "exit 42"] diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/System/Environment.enso b/distribution/lib/Standard/Searcher/0.1.0/src/System/Environment.enso new file mode 100644 index 000000000000..c3f646503af4 --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/System/Environment.enso @@ -0,0 +1,11 @@ +## It is not uncommon for systems to pass configuration data and information in + their environment variables. Enso provides you with the tools to read that + environment, and better integrate into your workflow. + + > Example + Look up the value of the `PATH` environment variable. + + import Standard.Base.System.Environment + + example_get = Environment.get "PATH" + diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/System/Filesystem.enso b/distribution/lib/Standard/Searcher/0.1.0/src/System/Filesystem.enso new file mode 100644 index 000000000000..ee7e16a25d2d --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/System/Filesystem.enso @@ -0,0 +1,30 @@ +## The filesystem is where so much of your data actually lives. While Enso + provides easy-to-use functionality for working with your files, sometimes you + need to do things that are more complex. + + Enso's Filesystem libraries provide a robust set of tools for interacting + with the files on your computer. You can read them and write them, yes, but + you can also query their attributes and exert detailed control over their + structure and contents. + + > Example + Create a new file pointing to the `data.csv` file in the project directory. + + import Standard.Base.System.File + import Standard.Examples + + example_new = File.new Examples.csv_path + + > Example + Get the program's current working directory. + + import Standard.Base.System.File + + example_cwd = File.current_directory + + > Example + Get the current user's home directory. + + import Standard.Base.System.File + + example_home = File.home diff --git a/distribution/lib/Standard/Searcher/0.1.0/src/System/Process.enso b/distribution/lib/Standard/Searcher/0.1.0/src/System/Process.enso new file mode 100644 index 000000000000..2cbde078447c --- /dev/null +++ b/distribution/lib/Standard/Searcher/0.1.0/src/System/Process.enso @@ -0,0 +1,17 @@ +## As powerful a data analysis tool that Enso is, it doesn't yet account for + every eventuality. To that end, it provides you with the tools to integrate + it into your workflow, rather than forcing you to do everything inside it. + + Enso's process library provides you with a robust and easy-to-use mechanism + for utilising other programs in your Enso workflow, providing them with their + parameters and getting results back from them. + + > Example + Call the "echo" command. + + import Standard.Base.System.Platform + import Standard.Base.System.Process + + example_run = case Platform.os of + Platform.Windows -> Process.run "PowerShell" ["-Command", "exit 42"] + _ -> Process.run "bash" ["-c", "exit 42"] diff --git a/distribution/lib/Standard/Table/0.1.0/src/Data/Table.enso b/distribution/lib/Standard/Table/0.1.0/src/Data/Table.enso index 43624e438aa5..82f3608b9019 100644 --- a/distribution/lib/Standard/Table/0.1.0/src/Data/Table.enso +++ b/distribution/lib/Standard/Table/0.1.0/src/Data/Table.enso @@ -350,6 +350,14 @@ type Table Returns a new Table without rows that contained missing values in any of the columns. + + > Example + Remove any rows that contain missing values from the table. + + import Standard.Examples + + example_drop_missing_rows = + Examples.inventory_table.drop_missing_rows drop_missing_rows : Table drop_missing_rows = cols = this.columns @@ -486,7 +494,7 @@ type Table example_sort = table = Examples.inventory_table - table.sort by="price" order=Sort_Order.Descending missing_last = false + table.sort by="price" order=Sort_Order.Descending missing_last=false > Example Sort the shop inventory based on the total stock, using the number sold