Merge pull request #4 from emilyriederer/reorder

Reorder arguments to align with dplyr API

README.md

@@ -20,8 +20,8 @@ This package enables us to similarly write `dbt` data models with commands like:
 
 ```
 {% set cols = dbtplyr.get_column_names( ref('mydata') ) %}
-{% set cols_n = dbtplyr.starts_with(cols, 'N') %}
-{% set cols_ind = dbtplyr.starts_with(cols, 'IND') %}
+{% set cols_n = dbtplyr.starts_with('N', cols) %}
+{% set cols_ind = dbtplyr.starts_with('IND', cols) %}
 
 select
 
@@ -45,11 +45,10 @@ so that it is only compiled to SQL when relevant by using the `final_comma` para
 Note that, slightly more `dplyr`-like, you may also write:
 
 ```
-
 select
 
-  {{ dbtplyr.across(dbtplyr.starts_with( ref('mydata'), 'N'), "sum({{var}}) as {{var}}_tot") }},
-  {{ dbtplyr.across(dbtplyr.starts_with( ref('mydata'), 'IND'), "mean({{var}}) as {{var}}_avg") }}
+  {{ dbtplyr.across(dbtplyr.starts_with('N', ref('mydata')), "sum({{var}}) as {{var}}_tot") }},
+  {{ dbtplyr.across(dbtplyr.starts_with('IND', ref('mydata')), "mean({{var}}) as {{var}}_avg") }}
 
 from {{ ref('mydata') }}
 ```
@@ -60,17 +59,25 @@ But, as each function call is a bit longer than the equivalent `dplyr` code, I p
 
 The complete list of macros included are:
 
+**Functions to apply operation across columns**
+
 - `across(var_list, script_string, final_comma)`
 - `c_across(var_list, script_string)`
+
+**Functions to evaluation condition across columns**
+
 - `if_any(var_list, script_string)`
 - `if_all(var_list, script_string)`
-- `starts_with(relation, string)` 
-- `ends_with(relation, string)`
-- `contains(relation, string)`
-- `not_contains(relation, string)`
-- `one_of(relation, string_list)`
-- `not_one_of(relation, string_list)`
-- `matches(relation, string)`
+
+**Functions to subset columns by naming conventions**
+
+- `starts_with(string, relation or list)` 
+- `ends_with(string, relation or list)`
+- `contains(string, relation or list)`
+- `not_contains(string, relation or list)`
+- `one_of(string_list, relation or list)`
+- `not_one_of(string_list, relation or list)`
+- `matches(string, relation)`
 - `everything(relation)`
 
 Note that all of the select-helper functions that take a relation as an argument can optionally be passed a list of names instead.

docs/catalog.json

@@ -1 +1 @@
-{"metadata": {"dbt_schema_version": "https://schemas.getdbt.com/dbt/catalog/v1.json", "dbt_version": "0.19.0", "generated_at": "2021-04-10T15:21:33.535951Z", "invocation_id": "d0f36208-f480-49e7-901b-4197b7a3548e", "env": {}}, "nodes": {}, "sources": {}, "errors": null}
+{"metadata": {"dbt_schema_version": "https://schemas.getdbt.com/dbt/catalog/v1.json", "dbt_version": "0.19.0", "generated_at": "2021-04-10T16:37:46.220893Z", "invocation_id": "02c1793a-12e3-403e-94f3-88d1e09499b8", "env": {}}, "nodes": {}, "sources": {}, "errors": null}

integration_tests/models/as_values.sql

@@ -10,14 +10,14 @@
 select
 
   -- starts_with
-  cast({{ "'" ~ dbtplyr.starts_with(cols, 'n') | join(',') ~ "'"}} as {{cast_to}})    as starts_with_n, -- single item
-  cast({{ "'" ~ dbtplyr.starts_with(cols, 'ind') | join(',') ~ "'" }} as {{cast_to}}) as starts_with_ind, -- multiple items
-  cast({{ "'" ~ dbtplyr.starts_with(cols, 'cat') | join(',') ~ "'"}} as {{cast_to}})  as starts_with_cat, -- no items
+  cast({{ "'" ~ dbtplyr.starts_with('n',   cols) | join(',') ~ "'"}} as {{cast_to}}) as starts_with_n, -- single item
+  cast({{ "'" ~ dbtplyr.starts_with('ind', cols) | join(',') ~ "'"}} as {{cast_to}}) as starts_with_ind, -- multiple items
+  cast({{ "'" ~ dbtplyr.starts_with('cat', cols) | join(',') ~ "'"}} as {{cast_to}}) as starts_with_cat, -- no items
 
   -- ends_with (TODO)
-  cast({{ "'" ~ dbtplyr.ends_with(cols, 'b') | join(',') ~ "'"}} as {{cast_to}})  as ends_with_b, -- single item
-  cast({{ "'" ~ dbtplyr.ends_with(cols, 'a') | join(',') ~ "'" }} as {{cast_to}}) as ends_with_a, -- multiple items
-  cast({{ "'" ~ dbtplyr.ends_with(cols, 'z') | join(',') ~ "'"}} as {{cast_to}})  as ends_with_z, -- no items
+  cast({{ "'" ~ dbtplyr.ends_with('b', cols) | join(',') ~ "'"}} as {{cast_to}}) as ends_with_b, -- single item
+  cast({{ "'" ~ dbtplyr.ends_with('a', cols) | join(',') ~ "'"}} as {{cast_to}}) as ends_with_a, -- multiple items
+  cast({{ "'" ~ dbtplyr.ends_with('z', cols) | join(',') ~ "'"}} as {{cast_to}}) as ends_with_z, -- no items
 
   -- matches (TODO)
 

integration_tests/models/contains.sql

@@ -1,3 +1,3 @@
-{% set cols_n = dbtplyr.contains( ref('data'), 'c') %}
+{% set cols_n = dbtplyr.contains( 'c', ref('data') ) %}
 select {{ dbtplyr.across(cols_n, "{{var}}") }}
 from {{ ref('data') }}

integration_tests/models/ends_with.sql

@@ -1,3 +1,3 @@
-{% set cols_n = dbtplyr.ends_with( ref('data'), 'c') %}
+{% set cols_n = dbtplyr.ends_with( 'c', ref('data') ) %}
 select {{ dbtplyr.across(cols_n, "{{var}}") }}
 from {{ ref('data') }}

integration_tests/models/matches.sql

@@ -1,3 +1,3 @@
-{% set cols_n = dbtplyr.matches( ref('data'), '.*_c') %}
+{% set cols_n = dbtplyr.matches('.*_c', ref('data')) %}
 select {{ dbtplyr.across(cols_n, "{{var}}") }}
 from {{ ref('data') }}

integration_tests/models/not_contains.sql

@@ -1,3 +1,3 @@
-{% set cols_n = dbtplyr.not_contains( ref('data'), 'n') %}
+{% set cols_n = dbtplyr.not_contains('n', ref('data')) %}
 select {{ dbtplyr.across(cols_n, "{{var}}") }}
 from {{ ref('data') }}

integration_tests/models/not_one_of.sql

@@ -1,3 +1,3 @@
-{% set cols_n = dbtplyr.not_one_of( ref('data'), ['n_a', 'ind_a', 'ind_b']) %}
+{% set cols_n = dbtplyr.not_one_of(['n_a', 'ind_a', 'ind_b'], ref('data')) %}
 select {{ dbtplyr.across(cols_n, "{{var}}") }}
 from {{ ref('data') }}

integration_tests/models/one_of.sql

@@ -1,3 +1,3 @@
-{% set cols_n = dbtplyr.one_of( ref('data'), ['amt_c']) %}
+{% set cols_n = dbtplyr.one_of(['amt_c'], ref('data')) %}
 select {{ dbtplyr.across(cols_n, "{{var}}") }}
 from {{ ref('data') }}

integration_tests/models/starts_with.sql

@@ -1,3 +1,3 @@
-{% set cols_n = dbtplyr.starts_with( ref('data'), 'amt') %}
+{% set cols_n = dbtplyr.starts_with('amt', ref('data')) %}
 select {{ dbtplyr.across(cols_n, "{{var}}") }}
 from {{ ref('data') }}

macros/macro.yml

@@ -89,15 +89,15 @@ macros:
       Returns list of string column names from relation 
       which start with a specified string
     arguments: &args 
+    - name: string
+      type: 'String'
+      description: String to match
     - name: relation
       type: 'Relation'
       description: >
         'Relation whose column names should be evaluated for matches.
         If list of column names has already been obtained with a separate
         call to get_column_names(), this list may be passed instead for efficiency.'
-    - name: string
-      type: 'String'
-      description: String to match
   
   - name: ends_with
     description: > 
@@ -122,12 +122,12 @@ macros:
       Returns list of string column names from relation
       which exactly match any of a list of strings
     arguments: &argsOneOf 
-    - name: relation
-      type: 'Relation'
-      description: Relation whose column names should be evaluated for matches or list of column names
     - name: strings
       type: 'List'
       description: List of strings against which to compare column names
+    - name: relation
+      type: 'Relation'
+      description: Relation whose column names should be evaluated for matches or list of column names
 
   - name: not_one_of
     description: >

macros/select_helpers.sql

@@ -1,4 +1,4 @@
-{% macro starts_with(relation, string) %}
+{% macro starts_with(string, relation) %}
 
 {%set cols = dbtplyr.get_column_names(relation) %}
 {%set regex = "^" ~ string ~ ".*" %}
@@ -7,7 +7,7 @@
 
 {% endmacro %}
 
-{% macro ends_with(relation, string) %}
+{% macro ends_with(string, relation) %}
 
 {%set cols = dbtplyr.get_column_names(relation) %}
 {%set regex = "^.*" ~ string ~ "$" %}
@@ -16,7 +16,7 @@
 
 {% endmacro %}
 
-{% macro contains(relation, string) %}
+{% macro contains(string, relation) %}
 
 {%set cols = dbtplyr.get_column_names(relation) %}
 {%set regex = "^.*" ~ string ~ ".*$" %}
@@ -25,7 +25,7 @@
 
 {% endmacro %}
 
-{% macro not_contains(relation, string) %}
+{% macro not_contains(string, relation) %}
 
 {%set cols = dbtplyr.get_column_names(relation) %}
 {%set regex = "^((?!" ~ string ~ ").)*$" %}
@@ -34,7 +34,7 @@
 
 {% endmacro %}
 
-{% macro one_of(relation, strings) %}
+{% macro one_of(strings, relation) %}
 
 {%set cols = dbtplyr.get_column_names(relation) %}
 {%set regex = "^("+ strings|join("|") +")$" %}
@@ -43,15 +43,15 @@
 
 {% endmacro %}
 
-{% macro not_one_of(relation, strings) %}
+{% macro not_one_of(strings, relation) %}
 
 {%set cols = dbtplyr.get_column_names(relation) %}
 {%set results = cols | reject('in', strings) %}
 {{return(results)}}
 
 {% endmacro %}
 
-{% macro matches(relation, string) %}
+{% macro matches(string, relation) %}
 
 {%set cols = dbtplyr.get_column_names(relation) %}
 {%set regex = string %}

models/overview.md

@@ -23,8 +23,8 @@ This package enables us to similarly write `dbt` data models with commands like:
 ```
 {% raw %}
 {% set cols = dbtplyr.get_column_names( ref('mydata') ) %}
-{% set cols_n = dbtplyr.starts_with(cols, 'N') %}
-{% set cols_ind = dbtplyr.starts_with(cols, 'IND') %}
+{% set cols_n = dbtplyr.starts_with('N', cols) %}
+{% set cols_ind = dbtplyr.starts_with('IND', cols) %}
 
 select
 
@@ -54,8 +54,8 @@ Note that, slightly more `dplyr`-like, you may also write:
 {% raw %}
 select
 
-  {{ dbtplyr.across(dbtplyr.starts_with( ref('mydata'), 'N'), "sum({{var}}) as {{var}}_tot") }},
-  {{ dbtplyr.across(dbtplyr.starts_with( ref('mydata'), 'IND'), "mean({{var}}) as {{var}}_avg") }}
+  {{ dbtplyr.across(dbtplyr.starts_with('N', ref('mydata')), "sum({{var}}) as {{var}}_tot") }},
+  {{ dbtplyr.across(dbtplyr.starts_with('IND', ref('mydata')), "mean({{var}}) as {{var}}_avg") }}
 
 from {{ ref('mydata') }}
 {% endraw %}
@@ -67,17 +67,25 @@ But, as each function call is a bit longer than the equivalent `dplyr` code, I p
 
 The complete list of macros included are:
 
+**Functions to apply operation across columns**
+
 - `across(var_list, script_string, final_comma)`
 - `c_across(var_list, script_string)`
+
+**Functions to evaluation condition across columns**
+
 - `if_any(var_list, script_string)`
 - `if_all(var_list, script_string)`
-- `starts_with(relation, string)` 
-- `ends_with(relation, string)`
-- `contains(relation, string)`
-- `not_contains(relation, string)`
-- `one_of(relation, string_list)`
-- `not_one_of(relation, string_list)`
-- `matches(relation, string)`
+
+**Functions to subset columns by naming conventions**
+
+- `starts_with(string, relation or list)` 
+- `ends_with(string, relation or list)`
+- `contains(string, relation or list)`
+- `not_contains(string, relation or list)`
+- `one_of(string_list, relation or list)`
+- `not_one_of(string_list, relation or list)`
+- `matches(string, relation)`
 - `everything(relation)`
 
 Note that all of the select-helper functions that take a relation as an argument can optionally be passed a list of names instead.