From 8215eef62b79bdc404d76cd4aefbc1ebda4f8da6 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Thu, 24 Oct 2024 07:59:41 +0000 Subject: [PATCH] build based on 14f22e9 --- dev/.documenter-siteinfo.json | 2 +- dev/90-contributing/index.html | 2 +- dev/91-developer/index.html | 2 +- dev/95-reference/index.html | 14 +++++++------- dev/index.html | 2 +- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index fe65213..f136fd6 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-10-24T07:54:43","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-10-24T07:59:37","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/90-contributing/index.html b/dev/90-contributing/index.html index 0f8d486..e43c069 100644 --- a/dev/90-contributing/index.html +++ b/dev/90-contributing/index.html @@ -1,2 +1,2 @@ -Contributing guidelines · 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, and follow the code of conduct.

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 guidelines · 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, and follow the code of conduct.

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/91-developer/index.html b/dev/91-developer/index.html index 8380070..bba331e 100644 --- a/dev/91-developer/index.html +++ b/dev/91-developer/index.html @@ -7,4 +7,4 @@ pkg> test

Working on a new issue

We try to keep a linear history in this repo, so it is important to keep your branches up-to-date.

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

    git fetch upstream
 git switch main
 git merge --ff-only upstream/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

Commit message

Before creating a pull request

Atomic git commits

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

Building and viewing the documentation locally

Following the latest suggestions, we recommend using LiveServer to build the documentation. Here is how you do it:

  1. Run julia --project=docs to open Julia in the environment of the docs.
  2. If this is the first time building the docs
    1. Press ] to enter pkg mode
    2. Run pkg> dev . to use the development version of your package
    3. Press backspace to leave pkg mode
  3. Run julia> using LiveServer
  4. Run julia> servedocs()

Making a new release

To create a new release, you can follow these simple steps:

After that, you only need to wait and verify:

+git rebase upstream/main BRANCH_NAME

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

    • Building and viewing the documentation locally

    Following the latest suggestions, we recommend using LiveServer to build the documentation. Here is how you do it:

    1. Run julia --project=docs to open Julia in the environment of the docs.
    2. If this is the first time building the docs
      1. Press ] to enter pkg mode
      2. Run pkg> dev . to use the development version of your package
      3. Press backspace to leave pkg mode
    3. Run julia> using LiveServer
    4. Run julia> servedocs()

    Making a new release

    To create a new release, you can follow these simple steps:

    After that, you only need to wait and verify:

    diff --git a/dev/95-reference/index.html b/dev/95-reference/index.html index df3e205..1ec8902 100644 --- a/dev/95-reference/index.html +++ b/dev/95-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], :timestep => [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], :timestep => [1, 2, 1, 2], :a .=> "b", :value => 5:8])
 4×4 DataFrame
  Row │ period  timestep  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 timestep and period into a single column timestep 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], :timestep => [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 timestep and period into a single column timestep 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], :timestep => [1, 2, 1], :value => 1:3])
 3×3 DataFrame
  Row │ period  timestep  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], :timestep => [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], :timestep => [1, 2, 1, 2], :a .=> "a", :value => 1:4])
 4×4 DataFrame
  Row │ period  timestep  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.fit_rep_period_weights! — Method
    fitrepperiodweights!(weightmatrix, clusteringmatrix, rpmatrix; weight_type, tol, args...)
    Given the initial weight guesses, finds better weights for convex or conical combinations of representative periods. For conical weights, it is possible to bound the total weight by one.
    The arguments:
    • clustering_result: the result of running TulipaClustering.find_representative_periods
    • weight_type: the type of weights to find; possible values are:
      • :convex: each period is represented as a convex sum of the representative periods (a sum with nonnegative weights adding into one)
      • :conical: each period is represented as a conical sum of the representative periods (a sum with nonnegative weights)
      • :conical_bounded: each period is represented as a conical sum of the representative periods (a sum with nonnegative weights) with the total weight bounded from above by one.
    • tol: algorithm's tolerance; when the weights are adjusted by a value less then or equal to tol, they stop being fitted further.
    • other arguments control the projected subgradient method; they are passed through to TulipaClustering.projected_subgradient_descent!.
    source
    TulipaClustering.fit_rep_period_weights! — Method
    fitrepperiodweights!(weightmatrix, clusteringmatrix, rpmatrix; weight_type, tol, args...)
    Given the initial weight guesses, finds better weights for convex or conical combinations of representative periods. For conical weights, it is possible to bound the total weight by one.
    The arguments:
    • weight_matrix: the initial guess for weights; the weights are adjusted using a projected subgradient descent method
    • clustering_matrix: the matrix of raw clustering data
    • rp_matrix: the matrix of raw representative period data
    • weight_type: the type of weights to find; possible values are:
      • :convex: each period is represented as a convex sum of the representative periods (a sum with nonnegative weights adding into one)
      • :conical: each period is represented as a conical sum of the representative periods (a sum with nonnegative weights)
      • :conical_bounded: each period is represented as a conical sum of the representative periods (a sum with nonnegative weights) with the total weight bounded from above by one.
    • tol: algorithm's tolerance; when the weights are adjusted by a value less then or equal to tol, they stop being fitted further.
    • show_progress: if true, a progress bar will be displayed.
    • other arguments control the projected subgradient method; they are passed through to TulipaClustering.projected_subgradient_descent!.
    source
    TulipaClustering.greedy_convex_hull — Method
    greedy_convex_hull(matrix; n_points, distance, initial_indices, mean_vector)
    Greedy method for finding n_points points in a hull of the dataset. The points   are added iteratively, at each step the point that is the furthest away from the   hull of the current set of points is found and added to the hull.
    • matrix: the clustering matrix
    • n_points: number of hull points to find
    • distance: distance semimetric
    • initial_indices: initial points which must be added to the hull, can be nothing
    • mean_vector: when adding the first point (if initial_indices is not given),   it will be chosen as the point furthest away from the mean_vector; this can be   nothing, in which case the first step will add a point furtherst away from   the centroid (the mean) of the dataset
    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.fit_rep_period_weights! — Method
    fitrepperiodweights!(weightmatrix, clusteringmatrix, rpmatrix; weight_type, tol, args...)
    Given the initial weight guesses, finds better weights for convex or conical combinations of representative periods. For conical weights, it is possible to bound the total weight by one.
    The arguments:
    • clustering_result: the result of running TulipaClustering.find_representative_periods
    • weight_type: the type of weights to find; possible values are:
      • :convex: each period is represented as a convex sum of the representative periods (a sum with nonnegative weights adding into one)
      • :conical: each period is represented as a conical sum of the representative periods (a sum with nonnegative weights)
      • :conical_bounded: each period is represented as a conical sum of the representative periods (a sum with nonnegative weights) with the total weight bounded from above by one.
    • tol: algorithm's tolerance; when the weights are adjusted by a value less then or equal to tol, they stop being fitted further.
    • other arguments control the projected subgradient method; they are passed through to TulipaClustering.projected_subgradient_descent!.
    source
    TulipaClustering.fit_rep_period_weights! — Method
    fitrepperiodweights!(weightmatrix, clusteringmatrix, rpmatrix; weight_type, tol, args...)
    Given the initial weight guesses, finds better weights for convex or conical combinations of representative periods. For conical weights, it is possible to bound the total weight by one.
    The arguments:
    • weight_matrix: the initial guess for weights; the weights are adjusted using a projected subgradient descent method
    • clustering_matrix: the matrix of raw clustering data
    • rp_matrix: the matrix of raw representative period data
    • weight_type: the type of weights to find; possible values are:
      • :convex: each period is represented as a convex sum of the representative periods (a sum with nonnegative weights adding into one)
      • :conical: each period is represented as a conical sum of the representative periods (a sum with nonnegative weights)
      • :conical_bounded: each period is represented as a conical sum of the representative periods (a sum with nonnegative weights) with the total weight bounded from above by one.
    • tol: algorithm's tolerance; when the weights are adjusted by a value less then or equal to tol, they stop being fitted further.
    • show_progress: if true, a progress bar will be displayed.
    • other arguments control the projected subgradient method; they are passed through to TulipaClustering.projected_subgradient_descent!.
    source
    TulipaClustering.greedy_convex_hull — Method
    greedy_convex_hull(matrix; n_points, distance, initial_indices, mean_vector)
    Greedy method for finding n_points points in a hull of the dataset. The points   are added iteratively, at each step the point that is the furthest away from the   hull of the current set of points is found and added to the hull.
    • matrix: the clustering matrix
    • n_points: number of hull points to find
    • distance: distance semimetric
    • initial_indices: initial points which must be added to the hull, can be nothing
    • mean_vector: when adding the first point (if initial_indices is not given),   it will be chosen as the point furthest away from the mean_vector; this can be   nothing, in which case the first step will add a point furtherst away from   the centroid (the mean) of the dataset
    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.project_onto_standard_basis — Method
    projectontostandard_basis(vector)
    Projects vector onto the standard basis. This projection is trivial: replace all components of the vector with zeros, except for the largest one, which is replaced with one.
    source
    TulipaClustering.projected_subgradient_descent! — Method
    projectedsubgradientdescent!(x; gradient, projection, niters, rtol, learningrate, adaptivegrad)
    Fits x using the projected gradient descent scheme.
    The arguments:
    source
    TulipaClustering.split_into_periods! — Method
    split_into_periods!(df; period_duration=nothing)
    Modifies a dataframe df by separating the column timestep into periods of length period_duration. The new data is written into two columns:
    • period: the period ID;
    • timestep: 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([:timestep => 1:4, :value => 5:8])
+   4 │          2          2  a           4.0
    source
    TulipaClustering.project_onto_standard_basis — Method
    projectontostandard_basis(vector)
    Projects vector onto the standard basis. This projection is trivial: replace all components of the vector with zeros, except for the largest one, which is replaced with one.
    source
    TulipaClustering.projected_subgradient_descent! — Method
    projectedsubgradientdescent!(x; gradient, projection, niters, rtol, learningrate, adaptivegrad)
    Fits x using the projected gradient descent scheme.
    The arguments:
    source
    TulipaClustering.split_into_periods! — Method
    split_into_periods!(df; period_duration=nothing)
    Modifies a dataframe df by separating the column timestep into periods of length period_duration. The new data is written into two columns:
    • period: the period ID;
    • timestep: 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([:timestep => 1:4, :value => 5:8])
 4×2 DataFrame
  Row │ timestep  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], :timestep => [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], :timestep => [1, 2, 1], :a .=> "a", :value => 1:3])
 3×4 DataFrame
  Row │ period  timestep  a       value
      │ Int64   Int64      String  Int64
@@ -159,4 +159,4 @@
      │ Int64
 ─────┼───────
    1 │     1:
-DataFrame must contain columns `timestep` and `value`
    source
    TulipaClustering.weight_matrix_to_df — Method
    weight_matrix_to_df(weights)
    Converts a weight matrix from a (sparse) matrix, which is more convenient for internal computations, to a dataframe, which is better for saving into a file. Zero weights are dropped to avoid cluttering the dataframe.
    source
    
+DataFrame must contain columns `timestep` and `value`
    source
    TulipaClustering.weight_matrix_to_df — Method
    weight_matrix_to_df(weights)

    Converts a weight matrix from a (sparse) matrix, which is more convenient for internal computations, to a dataframe, which is better for saving into a file. Zero weights are dropped to avoid cluttering the dataframe.

    source
    diff --git a/dev/index.html b/dev/index.html index 8aafd8b..f017107 100644 --- a/dev/index.html +++ b/dev/index.html @@ -17,4 +17,4 @@ - +