diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 2f3e6da..3ffdbcb 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-12-05T07:48:24","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-12-05T07:50:50","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/dev/contributing/index.html b/dev/contributing/index.html index c8e19cf..1b2f7e7 100644 --- a/dev/contributing/index.html +++ b/dev/contributing/index.html @@ -1,2 +1,2 @@ -Contributing · TulipaClustering.jl

Contributing guidelines

First of all, thanks for the interest!

We welcome all kinds of contribution, including, but not limited to code, documentation, examples, configuration, issue creating, etc.

Be polite and respectful.

Bug reports and discussions

If you think you found a bug, feel free to open an issue. Focused suggestions and requests can also be opened as issues. Before opening a pull request, start an issue or a discussion on the topic, please.

Working on an issue

If you found an issue that interests you, comment on that issue what your plans are. If the solution to the issue is clear, you can immediately create a pull request (see below). Otherwise, say what your proposed solution is and wait for a discussion around it.

Tip

Feel free to ping us after a few days if there are no responses.

If your solution involves code (or something that requires running the package locally), check the developer documentation. Otherwise, you can use the GitHub interface directly to create your pull request.

+Contributing · TulipaClustering.jl

Contributing guidelines

First of all, thanks for the interest!

We welcome all kinds of contribution, including, but not limited to code, documentation, examples, configuration, issue creating, etc.

Be polite and respectful.

Bug reports and discussions

If you think you found a bug, feel free to open an issue. Focused suggestions and requests can also be opened as issues. Before opening a pull request, start an issue or a discussion on the topic, please.

Working on an issue

If you found an issue that interests you, comment on that issue what your plans are. If the solution to the issue is clear, you can immediately create a pull request (see below). Otherwise, say what your proposed solution is and wait for a discussion around it.

Tip

Feel free to ping us after a few days if there are no responses.

If your solution involves code (or something that requires running the package locally), check the developer documentation. Otherwise, you can use the GitHub interface directly to create your pull request.

diff --git a/dev/developer/index.html b/dev/developer/index.html index 8ec9426..77f65c9 100644 --- a/dev/developer/index.html +++ b/dev/developer/index.html @@ -2,4 +2,4 @@ Dev setup · TulipaClustering.jl

Developer documentation

If you haven't, please read the Contributing guidelines first.

Linting and formatting

Install a plugin on your editor to use EditorConfig. This will ensure that your editor is configured with important formatting settings.

We use https://pre-commit.com to run the linters and formatters. In particular, the Julia code is formatted using JuliaFormatter.jl, so please install it globally first.

To install pre-commit, we recommend using pipx as follows:

# Install pipx following the link
 pipx install pre-commit

With pre-commit installed, activate it as a pre-commit hook:

pre-commit install

To run the linting and formatting manually, enter the command below:

pre-commit run -a

Now, you can only commit if all the pre-commit tests pass.

First time clone

If this is the first time you work with this repository, follow the instructions below to clone the repository.

  1. Fork this repo

  2. Clone your repo (this will create a git remote called origin)

  3. Add this repo as a remote:

    git remote add orgremote https://github.com/TulipaEnergy/TulipaClustering.jl

Working on a new issue

  1. Fetch from the JSO remote and fast-forward your local main

    git fetch orgremote
 git switch main
-git merge --ff-only orgremote/main

  2. Branch from main to address the issue (see below for naming)

    git switch -c 42-add-answer-universe

  3. Push the new local branch to your personal remote repository

    git push -u origin 42-add-answer-universe

  4. Create a pull request to merge your remote branch into the org main.

Branch naming

  • If there is an associated issue, add the issue number.
  • If there is no associated issue, and the changes are small, add a prefix such as "typo", "hotfix", "small-refactor", according to the type of update.
  • If the changes are not small and there is no associated issue, then create the issue first, so we can properly discuss the changes.
  • Use dash separated imperative wording related to the issue (e.g., 14-add-tests, 15-fix-model, 16-remove-obsolete-files).

Commit message

  • Use imperative or present tense, for instance: Add feature or Fix bug.
  • Have informative titles.
  • If necessary, add a body with details.

Before creating a pull request

  • [Advanced] Try to create "atomic git commits" (recommended reading: The Utopic Git History).

  • Make sure the tests pass.

  • Make sure the pre-commit tests pass.

  • Fetch any main updates from upstream and rebase your branch, if necessary:

    bash git fetch orgremote git rebase orgremote/main BRANCH_NAME

  • Then you can open a pull request and work with the reviewer to address any issues.

+git merge --ff-only orgremote/main

  • Branch from main to address the issue (see below for naming)

    git switch -c 42-add-answer-universe

  • Push the new local branch to your personal remote repository

    git push -u origin 42-add-answer-universe

  • Create a pull request to merge your remote branch into the org main.

    • Branch naming

    Commit message

    Before creating a pull request

    diff --git a/dev/index.html b/dev/index.html index f7375e0..7ba7e70 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · TulipaClustering.jl
    +Home · TulipaClustering.jl
    diff --git a/dev/reference/index.html b/dev/reference/index.html index 2df402e..b235a67 100644 --- a/dev/reference/index.html +++ b/dev/reference/index.html @@ -1,5 +1,5 @@ -Reference · TulipaClustering.jl

    Reference

    Contents

    Index

    TulipaClustering.append_period_from_source_df_as_rp! — Method
    append_period_from_source_df_as_rp!(df; source_df, period, rp, key_columns)

    Extracts a period with index period from source_df and appends it as a representative period with index rp to df, using key_columns as keys.

    Examples

    julia> source_df = DataFrame([:period => [1, 1, 2, 2], :time_step => [1, 2, 1, 2], :a .=> "b", :value => 5:8])
+Reference · TulipaClustering.jl
    Reference
    Contents
    Index
    TulipaClustering.append_period_from_source_df_as_rp! — Method
    append_period_from_source_df_as_rp!(df; source_df, period, rp, key_columns)
    Extracts a period with index period from source_df and appends it as a representative period with index rp to df, using key_columns as keys.
    Examples
    julia> source_df = DataFrame([:period => [1, 1, 2, 2], :time_step => [1, 2, 1, 2], :a .=> "b", :value => 5:8])
 4×4 DataFrame
  Row │ period  time_step  a       value
      │ Int64   Int64      String  Int64
@@ -29,7 +29,7 @@
    3 │          2          1  a           3
    4 │          2          2  a           4
    5 │          3          1  b           7
-   6 │          3          2  b           8
    source
    TulipaClustering.combine_periods! — Method
    combine_periods!(df)
    Modifies a dataframe df by combining the columns time_step and period into a single column time_step of global time steps. The period duration is inferred automatically from the maximum time step value, assuming that periods start with time step 1.
    Examples
    julia> df = DataFrame([:period => [1, 1, 2], :time_step => [1, 2, 1], :value => 1:3])
+   6 │          3          2  b           8
    source
    TulipaClustering.combine_periods! — Method
    combine_periods!(df)
    Modifies a dataframe df by combining the columns time_step and period into a single column time_step of global time steps. The period duration is inferred automatically from the maximum time step value, assuming that periods start with time step 1.
    Examples
    julia> df = DataFrame([:period => [1, 1, 2], :time_step => [1, 2, 1], :value => 1:3])
 3×3 DataFrame
  Row │ period  time_step  value
      │ Int64   Int64      Int64
@@ -45,7 +45,7 @@
 ─────┼──────────────────
    1 │         1      1
    2 │         2      2
-   3 │         3      3
    source
    TulipaClustering.df_to_matrix_and_keys — Method
    df_to_matrix_and_keys(df, key_columns)
    Converts a dataframe df (in a long format) to a matrix, ignoring the columns specified as key_columns. The key columns are converted from long to wide format and returned alongside the matrix.
    Examples
    julia> df = DataFrame([:period => [1, 1, 2, 2], :time_step => [1, 2, 1, 2], :a .=> "a", :value => 1:4])
+   3 │         3      3
    source
    TulipaClustering.df_to_matrix_and_keys — Method
    df_to_matrix_and_keys(df, key_columns)
    Converts a dataframe df (in a long format) to a matrix, ignoring the columns specified as key_columns. The key columns are converted from long to wide format and returned alongside the matrix.
    Examples
    julia> df = DataFrame([:period => [1, 1, 2, 2], :time_step => [1, 2, 1, 2], :a .=> "a", :value => 1:4])
 4×4 DataFrame
  Row │ period  time_step  a       value
      │ Int64   Int64      String  Int64
@@ -66,7 +66,7 @@
      │ Int64      String
 ─────┼───────────────────
    1 │         1  a
-   2 │         2  a
    source
    TulipaClustering.find_auxiliary_data — Method
    find_auxiliary_data(clustering_data)
    Calculates auxiliary data associated with the clustering_data. These include:
    • key_columns_demand: key columns in the demand dataframe
    • key_columns_generation_availability: key columns in the generation availability dataframe
    • period_duration: duration of time periods (in time steps)
    • last_period_duration: duration of the last period
    • n_periods: total number of periods
    source
    TulipaClustering.find_period_weights — Method
    find_period_weights(period_duration, last_period_duration, n_periods, drop_incomplete_periods)
    Finds weights of two different types of periods in the clustering data:
    • complete periods: these are all of the periods with length equal to period_duration.
    • incomplete last period: if last period duration is less than period_duration, it is incomplete.
    source
    TulipaClustering.find_representative_periods — Method
    findrepresentativeperiods(     clusteringdata;     nrp = 10,     rescaledemanddata = true,     dropincompletelastperiod = false,     method = :kmeans,     distance = SqEuclidean(),     args...,   )
    Finds representative periods via data clustering.
    • clustering_data: the data to perform clustering on.
    • n_rp: number of representative periods to find.
    • rescale_demand_data: if true, demands are first divided by the maximum demand value, so that they are between zero and one like the generation availability data
    • drop_incomplete_last_period: controls how the last period is treated if it is not complete: if this parameter is set to true, the incomplete period is dropped and the weights are rescaled accordingly; otherwise, clustering is done for n_rp - 1 periods, and the last period is added as a special shorter representative period
    • method: clustering method to use, either :k_means and :k_medoids
    • distance: semimetric used to measure distance between data points.
    • other named arguments can be provided; they are passed to the clustering method.
    source
    TulipaClustering.matrix_and_keys_to_df — Method
    matrix_and_keys_to_df(matrix, keys)
    Converts a a matrix matrix to a dataframe, appending the key columns given by keys.
    Examples
    julia> m = [1.0 3.0; 2.0 4.0]
+   2 │         2  a
    source
    TulipaClustering.find_auxiliary_data — Method
    find_auxiliary_data(clustering_data)
    Calculates auxiliary data associated with the clustering_data. These include:
    • key_columns_demand: key columns in the demand dataframe
    • key_columns_generation_availability: key columns in the generation availability dataframe
    • period_duration: duration of time periods (in time steps)
    • last_period_duration: duration of the last period
    • n_periods: total number of periods
    source
    TulipaClustering.find_period_weights — Method
    find_period_weights(period_duration, last_period_duration, n_periods, drop_incomplete_periods)
    Finds weights of two different types of periods in the clustering data:
    • complete periods: these are all of the periods with length equal to period_duration.
    • incomplete last period: if last period duration is less than period_duration, it is incomplete.
    source
    TulipaClustering.find_representative_periods — Method
    findrepresentativeperiods(     clusteringdata;     nrp = 10,     rescaledemanddata = true,     dropincompletelastperiod = false,     method = :kmeans,     distance = SqEuclidean(),     args...,   )
    Finds representative periods via data clustering.
    • clustering_data: the data to perform clustering on.
    • n_rp: number of representative periods to find.
    • rescale_demand_data: if true, demands are first divided by the maximum demand value, so that they are between zero and one like the generation availability data
    • drop_incomplete_last_period: controls how the last period is treated if it is not complete: if this parameter is set to true, the incomplete period is dropped and the weights are rescaled accordingly; otherwise, clustering is done for n_rp - 1 periods, and the last period is added as a special shorter representative period
    • method: clustering method to use, either :k_means and :k_medoids
    • distance: semimetric used to measure distance between data points.
    • other named arguments can be provided; they are passed to the clustering method.
    source
    TulipaClustering.matrix_and_keys_to_df — Method
    matrix_and_keys_to_df(matrix, keys)
    Converts a a matrix matrix to a dataframe, appending the key columns given by keys.
    Examples
    julia> m = [1.0 3.0; 2.0 4.0]
 2×2 Matrix{Float64}:
  1.0  3.0
  2.0  4.0
@@ -87,7 +87,7 @@
    1 │          1          1  a           1.0
    2 │          1          2  a           2.0
    3 │          2          1  a           3.0
-   4 │          2          2  a           4.0
    source
    TulipaClustering.read_clustering_data_from_csv_folder — Method
    read_clustering_data_from_csv_folder(input_folder)
    Returns the TulipaClustering.ClusteringData reading all data from CSV files in the input_folder.
    The following files are expected to exist in the input folder:
    The output contains:
    • demand: a DataFrame of demand values at different nodes per time step
    • generation_availability: a DataFrame of availability coefficients for different generation technologies located at different nodes per time step
    source
    TulipaClustering.read_csv_with_schema — Method
    read_csv_with_schema(file_path, schema)
    Reads the csv with file_name at location path validating the data using the schema. It is assumes that the file's header is at the second row. The first row of the file contains some metadata information that is not used.
    source
    TulipaClustering.split_into_periods! — Method
    split_into_periods!(df; period_duration=nothing)
    Modifies a dataframe df by separating the column time_step into periods of length period_duration. The new data is written into two columns:
    • period: the period ID;
    • time_step: the time step within the current period.
    If period_duration is nothing, then all of the time steps are within the same period with index 1.
    Examples
    julia> df = DataFrame([:time_step => 1:4, :value => 5:8])
+   4 │          2          2  a           4.0
    source
    TulipaClustering.read_clustering_data_from_csv_folder — Method
    read_clustering_data_from_csv_folder(input_folder)
    Returns the TulipaClustering.ClusteringData reading all data from CSV files in the input_folder.
    The following files are expected to exist in the input folder:
    The output contains:
    • demand: a DataFrame of demand values at different nodes per time step
    • generation_availability: a DataFrame of availability coefficients for different generation technologies located at different nodes per time step
    source
    TulipaClustering.read_csv_with_schema — Method
    read_csv_with_schema(file_path, schema)
    Reads the csv with file_name at location path validating the data using the schema. It is assumes that the file's header is at the second row. The first row of the file contains some metadata information that is not used.
    source
    TulipaClustering.split_into_periods! — Method
    split_into_periods!(df; period_duration=nothing)
    Modifies a dataframe df by separating the column time_step into periods of length period_duration. The new data is written into two columns:
    • period: the period ID;
    • time_step: the time step within the current period.
    If period_duration is nothing, then all of the time steps are within the same period with index 1.
    Examples
    julia> df = DataFrame([:time_step => 1:4, :value => 5:8])
 4×2 DataFrame
  Row │ time_step  value
      │ Int64      Int64
@@ -132,7 +132,7 @@
 ─────┼──────────────────────────
    1 │      1          1      1
    2 │      1          2      2
-   3 │      1          3      3
    source
    TulipaClustering.validate_df_and_find_key_columns — Method
    validate_df_and_find_key_columns(df)
    Checks that dataframe df contains the necessary columns and returns a list of columns that act as keys (i.e., unique data identifiers within different periods).
    Examples
    julia> df = DataFrame([:period => [1, 1, 2], :time_step => [1, 2, 1], :a .=> "a", :value => 1:3])
+   3 │      1          3      3
    source
    TulipaClustering.validate_df_and_find_key_columns — Method
    validate_df_and_find_key_columns(df)
    Checks that dataframe df contains the necessary columns and returns a list of columns that act as keys (i.e., unique data identifiers within different periods).
    Examples
    julia> df = DataFrame([:period => [1, 1, 2], :time_step => [1, 2, 1], :a .=> "a", :value => 1:3])
 3×4 DataFrame
  Row │ period  time_step  a       value
      │ Int64   Int64      String  Int64
@@ -159,4 +159,4 @@
      │ Int64
 ─────┼───────
    1 │     1:
-DataFrame must contain columns `time_step` and `value`
    source
    
+DataFrame must contain columns `time_step` and `value`
    source