rgwfuncs 0.0.23__tar.gz → 0.0.25__tar.gz

{rgwfuncs-0.0.23/src/rgwfuncs.egg-info → rgwfuncs-0.0.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: rgwfuncs
-Version: 0.0.23
+Version: 0.0.25
 Summary: A functional programming paradigm for mathematical modelling and data science
 Home-page: https://github.com/ryangerardwilson/rgwfunc
 Author: Ryan Gerard Wilson
@@ -135,22 +135,126 @@ To display all docstrings, use:
 
 --------------------------------------------------------------------------------
 
-## String Based Functions
+## Documentation Access Functions
 
-### 1. str_docs
-Print a list of available function names in alphabetical order. If a filter is provided, print the matching docstrings.
+### 1. docs
+Print a list of available function names in alphabetical order. If a filter is provided, print the docstrings of functions containing the term.
 
 • Parameters:
   - `method_type_filter` (str): Optional, comma-separated to select docstring types, or '*' for all.
 
 • Example:
 
-    import rgwfuncs
-    rgwfuncs.str_docs(method_type_filter='numeric_clean,limit_dataframe')
+    from rgwfuncs import docs
+    docs(method_type_filter='numeric_clean,limit_dataframe')
 
 --------------------------------------------------------------------------------
 
-### 2. send_telegram_message
+## Algebra Based Functions
+
+This section provides comprehensive functions for handling algebraic expressions, performing tasks such as computation, simplification, solving equations, and prime factorization, all outputted in LaTeX format.
+
+### 1. `compute_algebraic_expression`
+
+Evaluates complex algebraic expressions and provides numerical results.
+
+- **Parameters:**
+  - `expression` (str): A string representing an arithmetic operation.
+
+- **Returns:**
+  - `float`: The computed numerical result.
+
+- **Example:**
+
+    from rgwfuncs import compute_algebraic_expression
+    result1 = compute_algebraic_expression("2 + 2")
+    print(result1)  # Output: 4.0
+
+    result2 = compute_algebraic_expression("10 % 3")
+    print(result2)  # Output: 1.0
+
+    result3 = compute_algebraic_expression("math.gcd(36, 60) * math.sin(math.radians(45)) * 10000")
+    print(result3)  # Output: 84852.8137423857
+
+These examples illustrate the ability to handle basic arithmetic, the modulo operator, and functions utilizing the Python math module.
+
+--------------------------------------------------------------------------------
+
+### 2. `simplify_algebraic_expression`
+
+Simplifies expressions and returns them in LaTeX format.
+
+- **Parameters:**
+  - `expression` (str): A string of the expression to simplify.
+
+- **Returns:**
+  - `str`: Simplified expression in LaTeX.
+
+- **Example:**
+
+    from rgwfuncs import simplify_algebraic_expression
+    simplified_expr1 = simplify_algebraic_expression("2*x + 3*x")
+    print(simplified_expr1)  # Output: "5 x"
+
+    simplified_expr2 = simplify_algebraic_expression("(np.diff(3*x**8)) / (np.diff(8*x**30) * 11*y**3)")
+    print(simplified_expr2)  # Output: "\frac{1}{110 x^{22} y^{3}}"
+
+These examples demonstrate simplification of polynomial expressions and more complex ratios involving derivatives.
+
+--------------------------------------------------------------------------------
+
+### 3. `solve_algebraic_expression`
+
+Solves equations for specified variables, with optional substitutions, returning LaTeX-formatted solutions.
+
+- **Parameters:**
+  - `expression` (str): A string of the equation to solve.
+  - `variable` (str): The variable to solve for.
+  - `subs` (Optional[Dict[str, float]]): Substitutions for variables.
+
+- **Returns:**
+  - `str`: Solutions formatted in LaTeX.
+
+- **Example:**
+
+    from rgwfuncs import solve_algebraic_expression
+    solutions1 = solve_algebraic_expression("a*x**2 + b*x + c", "x", {"a": 3, "b": 7, "c": 5})
+    print(solutions1)  # Output: "\left[-7/6 - sqrt(11)*I/6, -7/6 + sqrt(11)*I/6\right]"
+
+    solutions2 = solve_algebraic_expression("x**2 - 4", "x")
+    print(solutions2)  # Output: "\left[-2, 2\right]"
+    
+Here, we solve both a quadratic equation with complex solutions and a simpler polynomial equation.
+
+--------------------------------------------------------------------------------
+
+### 4. `get_prime_factors_latex`
+
+Computes prime factors of a number and presents them in LaTeX format.
+
+- **Parameters:**
+  - `n` (int): The integer to factorize.
+
+- **Returns:**
+  - `str`: Prime factorization in LaTeX.
+
+- **Example:**
+
+    from rgwfuncs import get_prime_factors_latex
+    factors1 = get_prime_factors_latex(100)
+    print(factors1)  # Output: "2^{2} \cdot 5^{2}"
+
+    factors2 = get_prime_factors_latex(60)
+    print(factors2)  # Output: "2^{2} \cdot 3 \cdot 5"
+
+    factors3 = get_prime_factors_latex(17)
+    print(factors3)  # Output: "17"    
+ 
+--------------------------------------------------------------------------------
+
+## String Based Functions
+
+### 1. send_telegram_message
 
 Send a message to a Telegram chat using a specified preset from your configuration file.
 
@@ -176,20 +280,7 @@ Send a message to a Telegram chat using a specified preset from your configurati
 
 Below is a quick reference of available functions, their purpose, and basic usage examples.
 
-### 1. df_docs
-Print a list of available function names in alphabetical order. If a filter is provided, print the matching docstrings.
-
-• Parameters:
-  - `method_type_filter` (str): Optional, comma-separated to select docstring types, or '*' for all.
-
-• Example:
-
-    import rgwfuncs
-    rgwfuncs.df_docs(method_type_filter='numeric_clean,limit_dataframe')
-
---------------------------------------------------------------------------------
-
-### 2. `numeric_clean`
+### 1. `numeric_clean`
 Cleans the numeric columns in a DataFrame according to specified treatments.
 
 • Parameters:
@@ -218,7 +309,7 @@ Cleans the numeric columns in a DataFrame according to specified treatments.
 
 --------------------------------------------------------------------------------
 
-### 3. `limit_dataframe`
+### 2. `limit_dataframe`
 Limit the DataFrame to a specified number of rows.
 
 • Parameters:
@@ -239,7 +330,7 @@ Limit the DataFrame to a specified number of rows.
 
 --------------------------------------------------------------------------------
 
-### 4. `from_raw_data`
+### 3. `from_raw_data`
 Create a DataFrame from raw data.
 
 • Parameters:
@@ -265,7 +356,7 @@ Create a DataFrame from raw data.
 
 --------------------------------------------------------------------------------
 
-### 5. `append_rows`
+### 4. `append_rows`
 Append rows to the DataFrame.
 
 • Parameters:
@@ -290,7 +381,7 @@ Append rows to the DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 6. `append_columns`
+### 5. `append_columns`
 Append new columns to the DataFrame with None values.
 
 • Parameters:
@@ -311,7 +402,7 @@ Append new columns to the DataFrame with None values.
     
 --------------------------------------------------------------------------------
 
-### 7. `update_rows`
+### 6. `update_rows`
 Update specific rows in the DataFrame based on a condition.
 
 • Parameters:
@@ -333,7 +424,7 @@ Update specific rows in the DataFrame based on a condition.
     
 --------------------------------------------------------------------------------
 
-### 8. `delete_rows`
+### 7. `delete_rows`
 Delete rows from the DataFrame based on a condition.
 
 • Parameters:
@@ -354,7 +445,7 @@ Delete rows from the DataFrame based on a condition.
     
 --------------------------------------------------------------------------------
 
-### 9. `drop_duplicates`
+### 8. `drop_duplicates`
 Drop duplicate rows in the DataFrame, retaining the first occurrence.
 
 • Parameters:
@@ -374,7 +465,7 @@ Drop duplicate rows in the DataFrame, retaining the first occurrence.
     
 --------------------------------------------------------------------------------
 
-### 10. `drop_duplicates_retain_first`
+### 9. `drop_duplicates_retain_first`
 Drop duplicate rows based on specified columns, retaining the first occurrence.
 
 • Parameters:
@@ -395,7 +486,7 @@ Drop duplicate rows based on specified columns, retaining the first occurrence.
     
 --------------------------------------------------------------------------------
 
-### 11. `drop_duplicates_retain_last`
+### 10. `drop_duplicates_retain_last`
 Drop duplicate rows based on specified columns, retaining the last occurrence.
 
 • Parameters:
@@ -417,7 +508,7 @@ Drop duplicate rows based on specified columns, retaining the last occurrence.
 
 --------------------------------------------------------------------------------
 
-### 12. `load_data_from_query`
+### 11. `load_data_from_query`
 
 Load data from a database query into a DataFrame based on a configuration preset.
 
@@ -444,7 +535,7 @@ Load data from a database query into a DataFrame based on a configuration preset
     
 --------------------------------------------------------------------------------
 
-### 13. `load_data_from_path`
+### 12. `load_data_from_path`
 Load data from a file into a DataFrame based on the file extension.
 
 • Parameters:
@@ -463,7 +554,7 @@ Load data from a file into a DataFrame based on the file extension.
 
 --------------------------------------------------------------------------------
 
-### 14. `load_data_from_sqlite_path`
+### 13. `load_data_from_sqlite_path`
 Execute a query on a SQLite database file and return the results as a DataFrame.
 
 • Parameters:
@@ -483,7 +574,7 @@ Execute a query on a SQLite database file and return the results as a DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 15. `first_n_rows`
+### 14. `first_n_rows`
 Display the first n rows of the DataFrame (prints out in dictionary format).
 
 • Parameters:
@@ -501,7 +592,7 @@ Display the first n rows of the DataFrame (prints out in dictionary format).
 
 --------------------------------------------------------------------------------
 
-### 16. `last_n_rows`
+### 15. `last_n_rows`
 Display the last n rows of the DataFrame (prints out in dictionary format).
 
 • Parameters:
@@ -519,7 +610,7 @@ Display the last n rows of the DataFrame (prints out in dictionary format).
 
 --------------------------------------------------------------------------------
 
-### 17. `top_n_unique_values`
+### 16. `top_n_unique_values`
 Print the top n unique values for specified columns in the DataFrame.
 
 • Parameters:
@@ -538,7 +629,7 @@ Print the top n unique values for specified columns in the DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 18. `bottom_n_unique_values`
+### 17. `bottom_n_unique_values`
 Print the bottom n unique values for specified columns in the DataFrame.
 
 • Parameters:
@@ -557,7 +648,7 @@ Print the bottom n unique values for specified columns in the DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 19. `print_correlation`
+### 18. `print_correlation`
 Print correlation for multiple pairs of columns in the DataFrame.
 
 • Parameters:
@@ -582,7 +673,7 @@ Print correlation for multiple pairs of columns in the DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 20. `print_memory_usage`
+### 19. `print_memory_usage`
 Print the memory usage of the DataFrame in megabytes.
 
 • Parameters:
@@ -599,7 +690,7 @@ Print the memory usage of the DataFrame in megabytes.
 
 --------------------------------------------------------------------------------
 
-### 21. `filter_dataframe`
+### 20. `filter_dataframe`
 Return a new DataFrame filtered by a given query expression.
 
 • Parameters:
@@ -625,7 +716,7 @@ Return a new DataFrame filtered by a given query expression.
 
 --------------------------------------------------------------------------------
 
-### 22. `filter_indian_mobiles`
+### 21. `filter_indian_mobiles`
 Filter and return rows containing valid Indian mobile numbers in the specified column.
 
 • Parameters:
@@ -647,7 +738,7 @@ Filter and return rows containing valid Indian mobile numbers in the specified c
 
 --------------------------------------------------------------------------------
 
-### 23. `print_dataframe`
+### 22. `print_dataframe`
 Print the entire DataFrame and its column types. Optionally print a source path.
 
 • Parameters:
@@ -665,7 +756,7 @@ Print the entire DataFrame and its column types. Optionally print a source path.
 
 --------------------------------------------------------------------------------
 
-### 24. `send_dataframe_via_telegram`
+### 23. `send_dataframe_via_telegram`
 Send a DataFrame via Telegram using a specified bot configuration.
 
 • Parameters:
@@ -692,7 +783,7 @@ Send a DataFrame via Telegram using a specified bot configuration.
 
 --------------------------------------------------------------------------------
 
-### 25. `send_data_to_email`
+### 24. `send_data_to_email`
 Send an email with an optional DataFrame attachment using the Gmail API via a specified preset.
 
 • Parameters:
@@ -722,7 +813,7 @@ Send an email with an optional DataFrame attachment using the Gmail API via a sp
 
 --------------------------------------------------------------------------------
 
-### 26. `send_data_to_slack`
+### 25. `send_data_to_slack`
 Send a DataFrame or message to Slack using a specified bot configuration.
 
 • Parameters:
@@ -748,7 +839,7 @@ Send a DataFrame or message to Slack using a specified bot configuration.
 
 --------------------------------------------------------------------------------
 
-### 27. `order_columns`
+### 26. `order_columns`
 Reorder the columns of a DataFrame based on a string input.
 
 • Parameters:
@@ -770,7 +861,7 @@ Reorder the columns of a DataFrame based on a string input.
 
 --------------------------------------------------------------------------------
 
-### 28. `append_ranged_classification_column`
+### 27. `append_ranged_classification_column`
 Append a ranged classification column to the DataFrame.
 
 • Parameters:
@@ -794,7 +885,7 @@ Append a ranged classification column to the DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 29. `append_percentile_classification_column`
+### 28. `append_percentile_classification_column`
 Append a percentile classification column to the DataFrame.
 
 • Parameters:
@@ -818,7 +909,7 @@ Append a percentile classification column to the DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 30. `append_ranged_date_classification_column`
+### 29. `append_ranged_date_classification_column`
 Append a ranged date classification column to the DataFrame.
 
 • Parameters:
@@ -847,7 +938,7 @@ Append a ranged date classification column to the DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 31. `rename_columns`
+### 30. `rename_columns`
 Rename columns in the DataFrame.
 
 • Parameters:
@@ -869,7 +960,7 @@ Rename columns in the DataFrame.
 
 --------------------------------------------------------------------------------
 
-### 32. `cascade_sort`
+### 31. `cascade_sort`
 Cascade sort the DataFrame by specified columns and order.
 
 • Parameters:
@@ -895,7 +986,7 @@ Cascade sort the DataFrame by specified columns and order.
 
 --------------------------------------------------------------------------------
 
-### 33. `append_xgb_labels`
+### 32. `append_xgb_labels`
 Append XGB training labels (TRAIN, VALIDATE, TEST) based on a ratio string.
 
 • Parameters:
@@ -917,7 +1008,7 @@ Append XGB training labels (TRAIN, VALIDATE, TEST) based on a ratio string.
 
 --------------------------------------------------------------------------------
 
-### 34. `append_xgb_regression_predictions`
+### 33. `append_xgb_regression_predictions`
 Append XGB regression predictions to the DataFrame. Requires an `XGB_TYPE` column for TRAIN/TEST splits.
 
 • Parameters:
@@ -949,7 +1040,7 @@ Append XGB regression predictions to the DataFrame. Requires an `XGB_TYPE` colum
 
 --------------------------------------------------------------------------------
 
-### 35. `append_xgb_logistic_regression_predictions`
+### 34. `append_xgb_logistic_regression_predictions`
 Append XGB logistic regression predictions to the DataFrame. Requires an `XGB_TYPE` column for TRAIN/TEST splits.
 
 • Parameters:
@@ -981,7 +1072,7 @@ Append XGB logistic regression predictions to the DataFrame. Requires an `XGB_TY
 
 --------------------------------------------------------------------------------
 
-### 36. `print_n_frequency_cascading`
+### 35. `print_n_frequency_cascading`
 Print the cascading frequency of top n values for specified columns.
 
 • Parameters:
@@ -1001,27 +1092,36 @@ Print the cascading frequency of top n values for specified columns.
 
 --------------------------------------------------------------------------------
 
-### 37. `print_n_frequency_linear`
-Print the linear frequency of top n values for specified columns.
+### 36. `print_n_frequency_linear`
 
-• Parameters:
-  - df (pd.DataFrame)
-  - n (int)
-  - columns (str): Comma-separated columns.
-  - `order_by` (str)
+Prints the linear frequency of the top `n` values for specified columns.
+
+#### Parameters:
+- **df** (`pd.DataFrame`): The DataFrame to analyze.
+- **n** (`int`): The number of top values to print for each column.
+- **columns** (`list`): A list of column names to be analyzed.
+- **order_by** (`str`): The order of frequency. The available options are:
+  - `"ASC"`: Sort keys in ascending lexicographical order.
+  - `"DESC"`: Sort keys in descending lexicographical order.
+  - `"FREQ_ASC"`: Sort the frequencies in ascending order (least frequent first).
+  - `"FREQ_DESC"`: Sort the frequencies in descending order (most frequent first).
+  - `"BY_KEYS_ASC"`: Sort keys in ascending order, numerically if possible, handling special strings like 'NaN' as typical entries.
+  - `"BY_KEYS_DESC"`: Sort keys in descending order, numerically if possible, handling special strings like 'NaN' as typical entries.
+
+#### Example:
 
-• Example:
-    
     from rgwfuncs import print_n_frequency_linear
     import pandas as pd
 
-    df = pd.DataFrame({'City': ['NY','LA','NY','SF','LA','LA']})
-    print_n_frequency_linear(df, 2, 'City', 'FREQ_DESC')
-    
+    df = pd.DataFrame({'City': ['NY', 'LA', 'NY', 'SF', 'LA', 'LA']})
+    print_n_frequency_linear(df, 2, ['City'], 'FREQ_DESC')
+
+This example analyzes the `City` column, printing the top 2 most frequent values in descending order of frequency.
+
 
 --------------------------------------------------------------------------------
 
-### 38. `retain_columns`
+### 37. `retain_columns`
 Retain specified columns in the DataFrame and drop the others.
 
 • Parameters:
@@ -1043,7 +1143,7 @@ Retain specified columns in the DataFrame and drop the others.
 
 --------------------------------------------------------------------------------
 
-### 39. `mask_against_dataframe`
+### 38. `mask_against_dataframe`
 Retain only rows with common column values between two DataFrames.
 
 • Parameters:
@@ -1068,7 +1168,7 @@ Retain only rows with common column values between two DataFrames.
 
 --------------------------------------------------------------------------------
 
-### 40. `mask_against_dataframe_converse`
+### 39. `mask_against_dataframe_converse`
 Retain only rows with uncommon column values between two DataFrames.
 
 • Parameters:
@@ -1093,7 +1193,7 @@ Retain only rows with uncommon column values between two DataFrames.
 
 --------------------------------------------------------------------------------
 
-### 41. `union_join`
+### 40. `union_join`
 Perform a union join, concatenating two DataFrames and dropping duplicates.
 
 • Parameters:
@@ -1116,7 +1216,7 @@ Perform a union join, concatenating two DataFrames and dropping duplicates.
 
 --------------------------------------------------------------------------------
 
-### 42. `bag_union_join`
+### 41. `bag_union_join`
 Perform a bag union join, concatenating two DataFrames without dropping duplicates.
 
 • Parameters:
@@ -1139,7 +1239,7 @@ Perform a bag union join, concatenating two DataFrames without dropping duplicat
 
 --------------------------------------------------------------------------------
 
-### 43. `left_join`
+### 42. `left_join`
 Perform a left join on two DataFrames.
 
 • Parameters:
@@ -1164,7 +1264,7 @@ Perform a left join on two DataFrames.
 
 --------------------------------------------------------------------------------
 
-### 44. `right_join`
+### 43. `right_join`
 Perform a right join on two DataFrames.
 
 • Parameters:
@@ -1189,7 +1289,7 @@ Perform a right join on two DataFrames.
 
 --------------------------------------------------------------------------------
 
-### 45. `insert_dataframe_in_sqlite_database`
+### 44. `insert_dataframe_in_sqlite_database`
 
 Inserts a Pandas DataFrame into a SQLite database table. If the specified table does not exist, it will be created with column types automatically inferred from the DataFrame's data types.
 
@@ -1227,7 +1327,7 @@ Inserts a Pandas DataFrame into a SQLite database table. If the specified table
 
 --------------------------------------------------------------------------------
 
-### 46. `sync_dataframe_to_sqlite_database`
+### 45. `sync_dataframe_to_sqlite_database`
 Processes and saves a DataFrame to an SQLite database, adding a timestamp column and replacing the existing table if needed. Creates the table if it does not exist.
 
 • Parameters:
@@ -1251,6 +1351,8 @@ Processes and saves a DataFrame to an SQLite database, adding a timestamp column
 
 --------------------------------------------------------------------------------
 
+
+
 ## Additional Info
 
 For more information, refer to each function’s docstring by calling: